企业官网建设流程全解析

tsParticles 仓库实践：用nx show projects --affected精准定位当前分支受影响的项目

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles

本指南以 tsParticles 仓库中 Nx workspace 技能参考文档 AFFECTED.md 为核心，完整讲解nx show projects --affected的 7 种核心用法，并结合本仓库的nx.json配置、根目录脚本以及@tsparticles/cli-nx-plugin插件源码，说明在拥有数百个 npm 包的大型 monorepo 中，如何精准筛选受影响项目、按需构建、并在 CI 中落地。读完本文，你将掌握 affected 命令的完整参数体系，并理解 tsParticles 仓库"只重跑需要重跑的包"这一高效工作流的底层机制。

为什么需要 affected：超大 monorepo 的精准构建

tsParticles 是一个由engine、bundles、effects、interactions、plugins、presets、shapes、updaters、wrappers、demo、cli等几十个目录、数百个 npm 包组成的大型 pnpm monorepo（工作区定义见 pnpm-workspace.yaml）。在这种规模的仓库里，每次提交只改动少量文件，却不可能也不应该重跑全部包的构建、测试与 lint。

Nx 的affected（受影响）机制正是解决这个问题：它基于 Git 历史与项目依赖图，计算出"当前分支相对基准分支到底有哪些项目受到了变更影响"，然后只针对这些项目执行目标任务。技能文档 AFFECTED.md 将这一能力浓缩为一组nx show projects --affected命令，本文逐一展开。

命令全景：AFFECTED.md 中的 7 种用法

原文档给出的全部命令如下（均已在本仓库验证可行，实际执行时需注意命令前缀，详见文末"注意事项"）：

# Affected since base branch (auto-detected) nx show projects --affected # Affected with explicit base nx show projects --affected --base=main nx show projects --affected --base=origin/main # Affected between two commits nx show projects --affected --base=abc123 --head=def456 # Affected apps only nx show projects --affected --type app # Affected excluding e2e projects nx show projects --affected --exclude="*-e2e" # Affected by uncommitted changes nx show projects --affected --uncommitted # Affected by untracked files nx show projects --affected --untracked

1. 默认基准分支（自动检测）

nx show projects --affected

这是最常用的形态：不指定任何基准，Nx 自动检测当前分支相对默认基准分支的差异，并输出受影响的项目名列表。

自动检测的"默认基准"由工作区配置决定。在 tsParticles 的 nx.json 中：

{ "defaultBase": "main" }

因此在本仓库中，不带--base的 affected 计算以main分支为默认基准；在 CI 环境中检出仓库后运行该命令，通常即等同于相对origin/main的比较。

2. 显式指定基准分支（--base）

nx show projects --affected --base=main nx show projects --affected --base=origin/main

当需要显式控制比较基准时使用--base，两种常见取值：

• --base=main：以本地main分支为基准；
• --base=origin/main：以远程origin/main分支为基准，这在本地分支落后于远程、需要按"远程最新状态"计算差异时尤其常用。

从本仓库根 package.json 的脚本可以看到，CI 场景正是围绕nx affected组织的：

"build:affected": "pnpm run prettify:readme && nx affected -t build --parallel=50%", "build:affected:ci": "pnpm run prettify:ci:readme && nx affected -t build --c=ci"

nx affected -t build与nx show projects --affected的区别在于：前者在受影响项目上执行build目标，后者仅列出受影响项目。--c=ci表示使用 nx.json 中targetDefaults.build.configurations.ci定义的 CI 配置（参数为--ci）。

3. 指定提交区间（--base 与 --head 组合）

nx show projects --affected --base=abc123 --head=def456

--base与--head同时给出时，affected 计算的对象是两个提交之间发生的变化，而不仅是"当前 HEAD 相对基准"的变化。典型场景：

• 审查某次合并或某个 PR 引入的变更范围；
• 复现某个历史区间内的构建状态；
• 在两个发布 tag 之间确定需要重新发布的包。

--base与--head都接受分支名、commit hash、tag 等任何 Git 可解析的引用。

4. 只筛选应用（--type）

nx show projects --affected --type app

--type按项目类型过滤受影响项目，app表示仅列出应用类项目（对应地还有lib表示库）。在 tsParticles 这类以 npm 包为主的 package-based 工作区中，项目类型由 Nx 的nx/plugins/package-json插件与本地@tsparticles/cli-nx-plugin插件推断生成——nx.json的plugins配置将这两个插件纳入了项目发现流程（见 nx.json），因此在执行前可用nx show projects --affected --type app --json先行查看过滤结果。

5. 排除指定项目（--exclude）

nx show projects --affected --exclude="*-e2e"

--exclude接受逗号分隔的项目名模式，用于从结果中剔除不需要的项目。示例中的"*-e2e"是 glob 模式，匹配所有以-e2e结尾的端到端测试项目。实际开发中常见的组合是排除 e2e、demo 等辅助项目，让构建只覆盖需要发布的核心包。技能文档 SKILL.md 中还展示了它与项目过滤参数一起使用的形态，例如：

nx show projects --affected --exclude="*-e2e" nx show projects --projects "tag:scope:client,packages/*"

6. 只算未提交变更（--uncommitted）

nx show projects --affected --uncommitted

--uncommitted将 affected 的计算范围收窄到工作区中尚未提交的变更（已暂存与未暂存的修改，但不包括新建但未跟踪的文件）。这在开发迭代中非常实用：改了几行代码还没 commit，就想知道"当前这次改动会影响哪些包"，从而只重跑相关的 lint/test。

7. 算上未跟踪文件（--untracked）

nx show projects --affected --untracked

--untracked则把新建但尚未被 Git 跟踪的文件也纳入 affected 计算。它与--uncommitted可以组合使用（--uncommitted --untracked），组合后即"本地全部改动"：既包括已跟踪文件的修改，也包括新建文件——这在新建了源文件或测试文件、尚未首次 commit 时尤为关键，否则新文件可能"消失"在 affected 计算之外。

组合使用与结构化输出

affected 参数并非互斥，可以灵活组合。例如"本地所有改动（含新建文件）中的 app 项目，排除 e2e"：

nx show projects --affected --uncommitted --untracked --type app --exclude="*-e2e"

为了让结果可编程处理，务必使用--json输出结构化数据。技能文档 SKILL.md 给出了组合jq的常见模式：

# 获取受影响项目数组 nx show projects --affected --json | jq '.' # 统计受影响项目数量 nx show projects --affected --json | jq 'length' # 按名称前缀过滤 nx show projects --affected --json | jq '.[] | select(startswith("shared-"))'

--json输出的是一组项目名字符串数组，可以无缝接入 shell 脚本、CI 步骤或 Agent 的自动化流程。

仓库级支撑：@tsparticles/cli-nx-plugin如何定义"项目"

affected 计算的前提是 Nx 能完整发现工作区中的所有项目及其可执行目标。tsParticles 为此实现了本地 Nx 插件@tsparticles/cli-nx-plugin（源码位于 cli/packages/nx-plugin/src），其核心是 create-nodes.ts 中导出的createNodesV2：

export const createNodesV2: CreateNodesV2 = [ "**/package.json", (configFiles, options, context) => createNodesFromFiles( packageJsonPath => createProjectAugmentation(packageJsonPath, context.workspaceRoot), configFiles, options, context, ), ];

它扫描所有package.json，并借助 canonical-targets.ts 中的tsParticlesAliasDefinitions为每个 tsParticles 工作区包注入规范化别名目标（nx:run-script执行器），让不同包的历史遗留脚本名统一为 Nx 可调用的目标：

同时，create-nodes.ts 会为每个包补充build/build:ci回退目标，并写入metadata.targetGroups（"tsParticles Nx fallback" 与 "tsParticles Nx aliases"）。以 cli/commands/build/package.json 为例，其build脚本链为clear:dist → prettify:src → lint → compile → circular-deps → prettify:readme，对应包@tsparticles/cli-command-build即可直接执行：

pnpm nx run @tsparticles/cli-command-build:tsc pnpm nx run @tsparticles/cli-command-build:clean

插件行为有完整测试保障，见 create-nodes.test.ts：既验证了别名目标的生成（tsc、clean等），也验证了"已存在的脚本同名时不覆盖"以及"仅识别commands/、packages/、utils/下的工作区包"等边界条件。插件自身在 project.json 中登记，并在 cli/README.md 中有使用说明与验证命令：

pnpm nx show project @tsparticles/cli-command-build --json pnpm nx show projects --withTarget tsc pnpm nx run @tsparticles/cli-nx-plugin:test

正是因为每个受影响的项目都有这些可执行目标，nx affected -t build（乃至-t build:ci、-t test、-t lint）才得以在 affected 项目集合上直接调度执行。

受影响计算与缓存：namedInputs 与 targetDefaults

affected 之所以高效，还在于它与 Nx 的任务缓存配合：未受影响的项目的目标产物直接从缓存恢复，而不是重新执行。tsParticles 在 nx.json 中为build/build:ci配置了默认目标：

• outputs: ["{projectRoot}/dist"]：构建产物位置，作为缓存键的输出部分；
• inputs: ["production", "^production"]：决定哪些文件变化会"破坏"缓存；
• cache: true：启用本地缓存（nx.json中还配置了nxCloudId，表明接入了 Nx Cloud 的远程缓存/分布式执行能力）。

而 nx.json 的namedInputs定义了输入集合的语义：

"sharedGlobals": [ "{workspaceRoot}/nx.json", "{workspaceRoot}/tsconfig.json", "{workspaceRoot}/pnpm-workspace.yaml" ], "production": [ "{projectRoot}/src/**/*", "{projectRoot}/index.*", "{projectRoot}/package.json", "{projectRoot}/tsconfig*.json", "sharedGlobals" ]

这意味着：pnpm-workspace.yaml、根tsconfig.json、nx.json等"全局共享输入"一旦变化，会影响所有项目的缓存有效性；而单个包的src/**/*、package.json变化只影响该包。这与 affected 的分层逻辑完全一致——先算"谁受影响"，再通过输入指纹决定"谁要真跑、谁能用缓存"，二者叠加构成整套增量构建体系。

命令速查表

注意事项

1. 命令前缀：若 nx 未全局安装，需要按包管理器加前缀。本仓库使用 pnpm（存在 pnpm-lock.yaml 与 pnpm-workspace.yaml，lerna.json 中npmClient也为pnpm），仓库内脚本直接写nx affected ...（见根 package.json），手动执行时建议写pnpm nx show projects --affected或pnpm exec nx ...，cli/README.md 即采用pnpm nx show project ...的写法。
2. 必须在工作区内执行：nx命令依赖仓库根的 nx.json 与项目发现插件，请在仓库根目录运行。
3. 基准分支的判定：未指定--base时以nx.json的defaultBase（本仓库为main）为默认基准；CI 中通常显式传--base=origin/main更稳妥。
4. 受影响≠必须重跑：affected 结果只是"候选集合"，实际是否重跑还取决于输入指纹与缓存命中情况。
5. 项目类型过滤的边界：package-based 工作区的项目类型由插件推断，使用--type前可先用--json预览结果，避免误过滤。

通过本文的命令体系与仓库源码对照，你可以在 tsParticles 或任何 Nx 管理的 monorepo 中，把"全量构建"收敛为"受影响构建"，让每次改动都只触发真正需要验证的包。

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles