Nx 的受影响分析（Affected Analysis）：利用依赖图仅构建修改过的项目

各位开发者朋友，大家好！今天我们要深入探讨一个在大型前端或全栈项目中非常关键的技术主题——Nx 的受影响分析（Affected Analysis）。这个机制是现代 Monorepo 工程化实践的核心之一，尤其对于使用 Nx 构建的项目来说，它能极大提升开发效率和 CI/CD 流水线的速度。

如果你正在管理一个包含多个包、库、应用的 Monorepo（比如用 Nx 管理的 Angular + React + Node.js 项目），你一定遇到过这样的问题：

“我改了一个组件，为什么整个项目都要重新编译？”

或者更糟：

“CI 流水线跑了一小时，只因为一个文件改动。”

这就是我们今天的主角——Affected Analysis 要解决的问题。它不是魔法，而是一个基于依赖图的智能决策系统，能准确识别出哪些项目受你的代码变更影响，并且只对这些项目执行构建、测试或部署操作。

一、什么是 Affected Analysis？

Affected Analysis 是 Nx 提供的一项核心能力，其本质是一个 增量构建策略，它通过分析项目的依赖关系图（Dependency Graph），来判断当前修改了哪些源码文件后，哪些项目需要重新构建或运行测试。

简单来说：

如果你修改了一个工具函数（如 utils/helpers.ts），只有调用它的模块才会被标记为“受影响”；
如果你改了一个 UI 组件（如 components/Button.tsx），所有引用该组件的应用和库都会被标记为“受影响”。

这样做的好处显而易见：
✅ 减少不必要的构建时间
✅ 缩短 CI/CD 周期
✅ 提高开发体验（热重载更快）
✅ 更精准的测试范围（只跑相关测试）

二、Nx 如何实现 Affected Analysis？

核心原理：依赖图 + 文件变更追踪

Nx 使用两个关键数据结构来实现 Affected Analysis：

数据结构	描述
依赖图（Dependency Graph）	表示每个项目之间的依赖关系，例如 A 依赖 B，B 依赖 C。Nx 在构建时自动构建这个图。
变更日志（Change Log / File Watcher）	记录哪些文件被修改、新增或删除，通常来自 Git diff 或本地文件监听器。

当用户执行命令如：

nx affected:build --base=main --head=HEAD

Nx 会做以下几步：

获取基线版本（base）和 HEAD 版本的差异文件列表
遍历这些文件，找到它们所在的项目（project）
从依赖图出发，向上追溯所有依赖该项目的项目（即“受影响”的项目）
最终生成一个受影响项目的列表，然后只对这些项目执行 build 操作

这正是“仅构建修改过的项目及其下游依赖”的逻辑！

三、实战演示：如何使用 Affected Analysis

我们以一个典型的 Nx 项目为例，假设结构如下：

apps/
  web-app/
  mobile-app/
libs/
  core/
    utils/
      helpers.ts
    components/
      Button.tsx
  shared/
    theme/
      styles.css

其中：

web-app 和 mobile-app 都依赖 core。
core/components/Button.tsx 被 web-app 和 mobile-app 引用。

现在我们修改了 core/utils/helpers.ts 中的一个函数：

// libs/core/utils/helpers.ts
export function formatCurrency(amount: number): string {
  return `$${amount.toFixed(2)}`;
}

👉 这个文件被 core 自身使用，但没有直接被任何应用引用。那么，受影响的是谁？

答案是：只有 core 本身，因为它是唯一直接依赖这个文件的项目。

但如果我们将这个函数改为：

// libs/core/utils/helpers.ts
import { someOtherFunction } from './other-utils';

export function formatCurrency(amount: number): string {
  return `$${someOtherFunction(amount).toFixed(2)}`;
}

此时如果 someOtherFunction 来自另一个文件（比如 other-utils.ts），而该文件也属于 core，那依然不会影响外部应用。

但若你在 core/components/Button.tsx 中引入了这个函数：

// libs/core/components/Button.tsx
import { formatCurrency } from '../utils/helpers';

export const Button = ({ amount }: { amount: number }) => (
  <button>{formatCurrency(amount)}</button>
);

这时，Button 组件的变更会导致：

core 受影响（因为内部文件变了）
web-app 和 mobile-app 也受影响（因为它们依赖 core 的组件）

这就体现了 Affected Analysis 的强大之处：它不只看文件，还看语义依赖。

四、底层代码解析：Nx 是怎么计算受影响项目的？

虽然 Nx 是用 TypeScript 写的，但我们可以通过模拟其算法逻辑来理解其工作方式。

步骤 1：构建依赖图（简化版）

{
  "web-app": ["core"],
  "mobile-app": ["core"],
  "core": [],
  "shared": []
}

这是通过 project.json 中的 dependencies 字段自动生成的。

步骤 2：获取变更文件 → 映射到项目

假设你通过 Git 获取了以下变更文件：

git diff --name-only main HEAD
# 输出：
# libs/core/utils/helpers.ts
# libs/core/components/Button.tsx

我们写一个简单的映射函数：

function mapFilesToProjects(files: string[], projectMap: Record<string, string>): string[] {
  const projects = new Set<string>();
  for (const file of files) {
    for (const [project, root] of Object.entries(projectMap)) {
      if (file.startsWith(root)) {
        projects.add(project);
        break;
      }
    }
  }
  return Array.from(projects);
}

这里 projectMap 是类似：

{
  "web-app": "apps/web-app",
  "mobile-app": "apps/mobile-app",
  "core": "libs/core",
  "shared": "libs/shared"
}

执行结果：

mapFilesToProjects(['libs/core/utils/helpers.ts', 'libs/core/components/Button.tsx'], projectMap)
// 返回 ['core']

步骤 3：传播受影响状态（拓扑排序 + BFS）

现在我们知道 core 被修改了，我们需要找出所有可能受影响的下游项目。

function getAffectedProjects(modifiedProjects: string[], dependencyGraph: Record<string, string[]>): string[] {
  const affected = new Set([...modifiedProjects]);
  const queue = [...modifiedProjects];

  while (queue.length > 0) {
    const current = queue.shift();
    const dependents = dependencyGraph[current] || [];

    for (const dependent of dependents) {
      if (!affected.has(dependent)) {
        affected.add(dependent);
        queue.push(dependent);
      }
    }
  }

  return Array.from(affected);
}

依赖图结构应为：

{
  "web-app": ["core"],
  "mobile-app": ["core"],
  "core": [],
  "shared": []
}

调用：

getAffectedProjects(['core'], dependencyGraph)
// 返回 ['core', 'web-app', 'mobile-app']

✅ 完美匹配预期行为！

五、常见场景与优化建议

场景	是否受影响	说明
修改公共工具函数（如 utils/helpers.ts）	✅ 只有依赖它的项目	不会影响其他无关项目
修改 UI 组件（如 Button.tsx）	✅ 所有引用它的项目	包括 App、Libs、Shared
删除某个文件	✅ 所有依赖该文件的项目	即使只是类型定义也要考虑
修改 `.env` 或配置文件	❌ 通常不受影响	除非配置被硬编码进代码逻辑中
修改测试文件（test/*.spec.ts）	❌ 一般不影响构建	除非测试覆盖了生产逻辑

💡 优化建议：

合理拆分项目：避免大而全的 lib，让每个项目职责清晰。
使用 --parallel 参数：并行构建受影响项目，加速 CI。
缓存中间产物：结合 Nx Cache（local or remote）进一步提速。
定期清理依赖图：防止死循环或冗余依赖导致误判。

六、如何验证 Affected Analysis 是否生效？

你可以通过以下方式验证：

方法 1：查看输出日志

nx affected:build --base=main --head=HEAD --verbose

你会看到类似输出：

✔ Running build for projects:
  - core
  - web-app
  - mobile-app

而不是全部项目！

方法 2：对比完整构建 vs 受影响构建时间

# 完整构建（慢）
nx build

# 受影响构建（快）
nx affected:build --base=main --head=HEAD

实测案例：某大型项目中，完整构建需 15 分钟，受影响构建仅需 2 分钟。

方法 3：检查 `.nx/cache` 目录

Nx 会记录每次构建的结果，如果你发现某些项目没有重新构建，说明 Affected Analysis 成功跳过了它们。

七、高级技巧：自定义 Affected 规则

有时默认的文件到项目的映射不够精细，比如你想让某个特定文件（如 config/app-config.json）触发所有应用的重建。

可以这样做：

1. 在 `project.json` 中添加 `affected` 属性

{
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": { ... },
      "dependsOn": ["^build"]
    }
  },
  "affected": {
    "files": ["config/**/*"]
  }
}

这样，任何对 config/ 下文件的修改都会触发所有依赖该项目的下游项目重建。

2. 使用 `nx affected:lint` 或 `nx affected:test`

nx affected:lint --base=main --head=HEAD
nx affected:test --base=main --head=HEAD

这比跑整个项目测试快得多！

八、总结：为什么你应该拥抱 Affected Analysis？

✅ 性能提升显著：减少无效构建，节省大量时间和资源。
✅ CI/CD 效率革命：不再因为一个小改动就触发整个流水线。
✅ 团队协作友好：每个人都能快速知道自己的修改是否会影响别人。
✅ 可扩展性强：随着项目增长，Affected Analysis 越发重要。

正如我在前面所说，这不是魔法，而是基于依赖图的精确推理。只要你的项目结构清晰、依赖明确，Nx 就能帮你做到“只构建必要的部分”。

最后送一句我的座右铭：

“不要让一个文件的改动拖垮整个系统的速度。”
—— Nx 的 Affected Analysis，就是你的救星。

希望这篇讲座式的文章让你对 Nx 的 Affected Analysis 有了全面而深入的理解。如果你正在使用 Nx，请立刻尝试 nx affected:build，你会发现开发效率真的不一样了！

欢迎留言讨论你的实际项目经验，我们一起进步！