Nx 任务运行实战指南run、run-many 与 affected 的用法、常用参数与底层原理【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nxNx 的核心工作流是运行任务——无论是构建、测试、lint、serve还是任何在project.json或package.json中定义的自定义任务。本文以 Nx 仓库中的 Agent 技能文档 .agents/skills/nx-run-tasks/SKILL.md 为骨架系统讲解如何在 Nx 工作区中单任务执行、批量执行与增量执行任务并结合本仓库的 CLI 源码解析run-many、affected等命令的实际行为。读完本文你将掌握 Nx 任务运行的全部核心命令、项目筛选语法与关键标志并能理解这些命令在底层是如何选择项目、调度进程的。准备工作确认 nx 的调用方式与可运行任务用包管理器前缀调用 nxNx 是一个命令行工具如果它没有全局安装就需要借助工作区正在使用的包管理器来调用。判断依据是仓库根目录的package.json与锁文件pnpm-lock.yaml、yarn.lock、package-lock.json等# 使用 npm npx nx command # 使用 pnpm pnpx nx command # 使用 yarn yarn nx commandSKILL.md 中明确提示在调用任意命令前先看package.json或锁文件确定当前工作区使用的包管理器。如果拿不准某个命令有哪些参数随时可以追加--help查看例如nx run-many --help、nx affected --help。查看哪些任务可以运行在运行任务之前最好先确认某个项目有哪些 target任务。最权威的方式不是直接读project.json而是使用nx show project命令获取解析后的完整配置nx show project projectname --json例如nx show project myapp --json该命令输出的 JSON 中包含targets字段列出该项目所有可运行的 target。SKILL.md 特别提醒直接翻看package.json的scripts或project.json的targets是可以的但可能会漏掉由 Nx 插件推断出来的任务inferred tasks。只有nx show project --json才会把插件推断的任务也合并进最终结果。这条建议在本仓库中同样成立。根目录 nx.json 的plugins配置注册了大量插件如nx/js/typescript、nx/jest/plugin、nx/eslint/plugin、nx/vite/plugin等它们会为匹配的项目自动推断出build、test、lint、e2e等 target。想快速定位拥有某个 target 的项目可以用nx show projects --withTarget build这两个命令都是nx show系列的能力详细用法可以参考同仓库的 .agents/skills/nx-workspace/SKILL.md。运行单个任务nx run运行单个项目上的单个任务使用nx runnx run project:task其中project是package.json或project.json如果存在中定义的项目名。例如nx run myapp:build nx run shared-ui:test从源码结构看nx run的解析入口位于 packages/nx/src/command-line/run/command-object.ts它会先读取nx.json再加载项目图project graph最终把任务交给任务执行器tasks runner调度整个调用链与run-many共用同一套执行机制。一次运行多个任务nx run-many当需要对多个项目执行一个或多个任务时使用nx run-manynx run-many -t build test lint typecheck这里-t是--targets的简写可以一次传入多个 target。默认情况下它会作用于所有项目除非你用-p即--projects过滤到特定项目nx run-many -t test -p proj1 proj2--projects参数支持灵活的筛选语法SKILL.md 给出了三类典型用法# 用 glob 模式匹配项目 nx run-many -t test --projects*-app --excludeexcluded-app # 用 tag 匹配项目Nx 的标签体系 nx run-many -t test --projectstag:api-*此外还有两个常用控制参数--exclude排除指定项目例如--excludeexcluded-app--parallel控制并发执行的进程数默认值是 3。源码层面run-many的参数定义在 packages/nx/src/command-line/run-many/command-object.ts实际逻辑在 packages/nx/src/command-line/run-many/run-many.ts。其中projectsToRun会先按 target 过滤出可运行该项目标的项目集合再调用findMatchingProjects定义于 packages/nx/src/utils/find-matching-projects.ts把--projects的显式名称、glob 模式、tag 引用解析为实际项目列表如果某项目不包含你指定的任何 target会输出警告而不是直接失败。最终所有任务通过runCommand统一调度执行。--parallel的默认值 3 与解析逻辑可以在 packages/nx/src/command-line/yargs-utils/shared-options.ts 中看到describe: Max number of parallel processes [default is 3].。该文件还支持通过NX_PARALLEL环境变量覆盖默认并发数并支持百分比形式的并发设置如--parallel50%表示按 CPU 核数的一定比例计算并发数。只运行受影响的项目nx affected在大型 monorepo 中每次改动往往只涉及一小部分代码。nx affected的作用是只对发生变更的项目以及依赖这些变更项目的项目运行任务从而显著节省 CI 时间和本地验证时间。SKILL.md 明确说明它尤其适合 CI 场景和大型工作区。nx affected -t build test lint默认情况下nx affected会对比**基础分支base branch**来计算变更。你可以用参数自定义对比范围# 指定 base 与 head nx affected -t test --basemain --headHEAD # 直接指定变更文件列表 nx affected -t test --fileslibs/mylib/src/index.ts--base和--head可以是分支名、commit hash 等 Git 引用--files则让你手动声明哪些文件发生了变更跳过 Git 对比。更丰富的 affected 用法如--uncommitted、--untracked、--type app等可以参考本仓库 .agents/skills/nx-workspace/references/AFFECTED.md。在源码中affected命令的参数与 handler 定义在 packages/nx/src/command-line/affected/command-object.ts。可以看到除了affected主命令外还存在affected:test、affected:build、affected:lint、affected:e2e这几个变体命令——它们本质上是把target固定为test/build/lint/e2e的快捷方式该文件中已标记为 describe: false即隐藏命令。核心实现 packages/nx/src/command-line/affected/affected.ts 的流程是通过calculateFileChanges计算变更文件加载完整项目图createProjectGraphAsync调用filterAffected位于 packages/nx/src/project-graph/affected/affected-project-graph.ts依据项目依赖关系过滤出受影响的节点同样交给runCommand执行任务。这就是变更的项目 依赖变更项目的项目这一语义的实现来源它不仅看直接改动的项目还会沿依赖图向上传播确保依赖方也能被重新构建或测试。通用 Flagsrun / run-many / affected 皆可用SKILL.md 指出以下标志对run、run-many、affected三个命令都有效标志作用--skipNxCache即使任务结果命中缓存也强制重新执行。用于验证缓存是否可信或某些场景下需要全新产物--verbose输出额外诊断信息如堆栈跟踪便于排查失败原因--nxBail遇到第一个失败的任务就停止后续执行快速失败、节省时间--configurationname使用指定的配置例如--configurationproduction对应project.json中 target 下的configurations字段几个使用示例# 强制重跑绕过缓存 nx run-many -t build --skipNxCache # 任务失败即中止 nx affected -t test --nxBail # 用 production 配置构建 nx run myapp:build --configurationproduction这些标志在 packages/nx/src/command-line/yargs-utils/shared-options.ts 中统一注册因此能被run、run-many、affected三个命令共享。其中--nxBail还支持通过环境变量NX_BAILtrue开启--verbose也可由NX_VERBOSE_LOGGINGtrue环境变量触发见 packages/nx/src/command-line/affected/affected.ts 中对NX_VERBOSE_LOGGING的读取。工作区级配置对任务运行的影响除了命令行参数任务运行还受 nx.json 工作区配置影响理解这些配置有助于解释为什么任务是这样运行的targetDefaults为同名 target 提供默认配置例如本仓库为build定义了cache: true与inputs决定缓存键的输入文件集合为test/lint/e2e也配置了缓存与dependsOn依赖关系namedInputs可复用的输入定义如production、sharedGlobals、native它们被targetDefaults引用以精确计算缓存命中parallel工作区级的并发默认值本仓库设为 1命令行--parallel可覆盖defaultBaseaffected在未显式传--base时使用的默认基础分支本仓库为master。这意味着nx affected在没有显式--base时实际对比的是nx.json中defaultBase指向的分支而缓存是否生效、何时命中则由targetDefaults与namedInputs共同决定。在 CI 与 AI Agent 场景中的应用nx affected特别适合 CI在一个 Pull Request 中只需要对变更波及的项目跑测试与 lint而不必全量执行整个仓库的任务CI 时间随代码规模的增长不会线性膨胀。典型 CI 片段# 安装依赖后对受影响的项目执行质量门禁 nx affected -t lint test --baseorigin/main --nxBail同时这份 SKILL.md 本身就是为 AI Agent 设计的运行指引当 Agent 被要求构建、测试、lint、serve 或运行工作区中的任何任务时应优先使用nx show project --json确认可运行的 target再选择nx run、nx run-many或nx affected之一执行并根据锁文件决定是否加npx/pnpx/yarn前缀。这套方法论对人工开发者同样适用先探测、再选型、后执行是高效使用 Nx 任务系统的不变顺序。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考