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 --basemain nx show projects --affected --baseorigin/main # Affected between two commits nx show projects --affected --baseabc123 --headdef456 # 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 --untracked1. 默认基准分支自动检测nx show projects --affected这是最常用的形态不指定任何基准Nx 自动检测当前分支相对默认基准分支的差异并输出受影响的项目名列表。自动检测的默认基准由工作区配置决定。在 tsParticles 的 nx.json 中{ defaultBase: main }因此在本仓库中不带--base的 affected 计算以main分支为默认基准在 CI 环境中检出仓库后运行该命令通常即等同于相对origin/main的比较。2. 显式指定基准分支--basenx show projects --affected --basemain nx show projects --affected --baseorigin/main当需要显式控制比较基准时使用--base两种常见取值--basemain以本地main分支为基准--baseorigin/main以远程origin/main分支为基准这在本地分支落后于远程、需要按远程最新状态计算差异时尤其常用。从本仓库根 package.json 的脚本可以看到CI 场景正是围绕nx affected组织的build:affected: pnpm run prettify:readme nx affected -t build --parallel50%, build:affected:ci: pnpm run prettify:ci:readme nx affected -t build --ccinx affected -t build与nx show projects --affected的区别在于前者在受影响项目上执行build目标后者仅列出受影响项目。--cci表示使用 nx.json 中targetDefaults.build.configurations.ci定义的 CI 配置参数为--ci。3. 指定提交区间--base 与 --head 组合nx show projects --affected --baseabc123 --headdef456--base与--head同时给出时affected 计算的对象是两个提交之间发生的变化而不仅是当前 HEAD 相对基准的变化。典型场景审查某次合并或某个 PR 引入的变更范围复现某个历史区间内的构建状态在两个发布 tag 之间确定需要重新发布的包。--base与--head都接受分支名、commit hash、tag 等任何 Git 可解析的引用。4. 只筛选应用--typenx 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. 排除指定项目--excludenx 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. 只算未提交变更--uncommittednx show projects --affected --uncommitted--uncommitted将 affected 的计算范围收窄到工作区中尚未提交的变更已暂存与未暂存的修改但不包括新建但未跟踪的文件。这在开发迭代中非常实用改了几行代码还没 commit就想知道当前这次改动会影响哪些包从而只重跑相关的 lint/test。7. 算上未跟踪文件--untrackednx show projects --affected --untracked--untracked则把新建但尚未被 Git 跟踪的文件也纳入 affected 计算。它与--uncommitted可以组合使用--uncommitted --untracked组合后即本地全部改动既包括已跟踪文件的修改也包括新建文件——这在新建了源文件或测试文件、尚未首次 commit 时尤为关键否则新文件可能消失在 affected 计算之外。组合使用与结构化输出affected 参数并非互斥可以灵活组合。例如本地所有改动含新建文件中的 app 项目排除 e2enx 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 中导出的createNodesV2export 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 可调用的目标规范化目标脚本回退候选用途cleanclear:dist清理 dist 输出prettifyprettify:src/format源码格式化prettify:ciprettify:ci:srcCI 格式化校验tsccompile/build:ts/typecheckTypeScript 编译bundle:webpackbuild:bundle:webpackWebpack 打包bundle:rollupbuild:bundle:rollupRollup 打包distfilesbuild:distfilesdist 文件整理同时create-nodes.ts 会为每个包补充build/build:ci回退目标并写入metadata.targetGroupstsParticles 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 与 targetDefaultsaffected 之所以高效还在于它与 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 的分层逻辑完全一致——先算谁受影响再通过输入指纹决定谁要真跑、谁能用缓存二者叠加构成整套增量构建体系。命令速查表场景命令默认基准分支下受影响的项目nx show projects --affected以 main 为基准nx show projects --affected --basemain以远程 main 为基准nx show projects --affected --baseorigin/main两个提交之间的受影响项目nx show projects --affected --baseabc123 --headdef456仅应用类项目nx show projects --affected --type app排除 e2e 项目nx show projects --affected --exclude*-e2e未提交变更影响的项目nx show projects --affected --uncommitted包含未跟踪文件nx show projects --affected --untracked在受影响项目上执行构建nx affected -t build结构化输出便于脚本处理nx show projects --affected --json \| jq .注意事项命令前缀若 nx 未全局安装需要按包管理器加前缀。本仓库使用 pnpm存在 pnpm-lock.yaml 与 pnpm-workspace.yamllerna.json 中npmClient也为pnpm仓库内脚本直接写nx affected ...见根 package.json手动执行时建议写pnpm nx show projects --affected或pnpm exec nx ...cli/README.md 即采用pnpm nx show project ...的写法。必须在工作区内执行nx命令依赖仓库根的 nx.json 与项目发现插件请在仓库根目录运行。基准分支的判定未指定--base时以nx.json的defaultBase本仓库为main为默认基准CI 中通常显式传--baseorigin/main更稳妥。受影响≠必须重跑affected 结果只是候选集合实际是否重跑还取决于输入指纹与缓存命中情况。项目类型过滤的边界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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考