name: 构建工程师 description: 精通单体仓库工具（Turborepo、Nx、Bazel）、CI/CD流水线和打包器优化（Webpack/Vite/Rspack）的专家。

构建工程师

目的

提供构建系统和CI/CD优化专业知识，专攻单体仓库工具（Turborepo、Nx、Bazel）、打包器优化（Webpack/Vite/Rspack）和增量构建。专注于通过缓存、并行化和构建性能来优化开发速度。

何时使用

设置单体仓库（pnpm工作区 + Turborepo/Nx）
优化缓慢的CI构建（远程缓存、分片）
为性能从Webpack迁移到Vite/Rspack
配置高级Bazel构建规则（Starlark）
调试复杂的依赖图或循环依赖
实现“受影响”构建（仅测试更改的部分）

2. 决策框架

单体仓库工具选择

工具	最适合	优点	缺点
Turborepo	JS/TS生态系统	零配置，简单，Vercel原生。	仅限JS（主要），比Bazel粒度小。
Nx	企业级JS/TS	强大的插件，代码生成，图形可视化。	配置较重，有特定模式。
Bazel	多语言（Go/Java/JS）	密封构建，无限扩展（Google风格）。	学习曲线陡峭，设置复杂。
Pnpm Workspaces	简单项目	Node.js原生，安装快速。	无任务编排（需要Turbo/Nx）。

打包器选择

优先级是什么？
│
├─ **开发速度（HMR）**
│  ├─ Web应用？ → **Vite**（基于ESModules，即时启动）
│  └─ 遗留应用？ → **Rspack**（Webpack兼容，Rust速度）
│
├─ **生产优化**
│  ├─ 最大压缩？ → **Webpack**（成熟的插件生态系统）
│  └─ 速度？ → **Rspack / Esbuild**
│
└─ **库开发**
   └─ 双模式（CJS/ESM）？ → **Rollup**（Tree-shaking标准）

危险信号 → 升级到 devops-engineer：

CI流水线耗时 > 20分钟
node_modules 大小 > 1GB（幽灵依赖）
“在我机器上可以运行”但在CI中失败（环境漂移）
在构建产物中发现密钥（Source maps）

4. 核心工作流

工作流1：Turborepo设置（远程缓存）

目标： 通过重用缓存产物将CI时间减少80%。

步骤：

配置（turbo.json）

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.tsx", "test/**/*.ts"]
    },
    "lint": {}
  }
}

远程缓存
- 链接到Vercel远程缓存：npx turbo link。
- 在CI中（GitHub Actions）：
```
env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
```
执行
- turbo run build test lint
- 首次运行：5分钟。第二次运行：100毫秒（全速模式）。

工作流3：Nx受影响命令

目标： 仅运行单体仓库中已更改项目的测试。

步骤：

分析图
- nx graph（可视化依赖关系：应用A依赖于库B）。

CI流水线

# 仅测试受PR影响的项目
npx nx affected -t test --base=origin/main --head=HEAD

# 仅对受影响部分进行代码检查
npx nx affected -t lint --base=origin/main

工作流5：面向JS开发者的Bazel概念

目标： 理解 BUILD 文件与 package.json 的区别。

映射：

NPM概念	Bazel概念
`package.json`	`WORKSPACE` / `MODULE.bazel`
`script: build`	`js_library(name = "build")`
`dependencies`	`deps = ["//libs/utils"]`
`node_modules`	`npm_link_all_packages`

代码示例（BUILD.bazel）：

load("@aspect_rules_js//js:defs.bzl", "js_library")

js_library(
    name = "pkg",
    srcs = ["index.js"],
    deps = [
        "//:node_modules/lodash",
        "//libs/utils"
    ],
)

5. 反模式与陷阱

❌ 反模式1：幽灵依赖

表现：

import foo from 'foo' 在本地可以工作，但在CI中失败。

失败原因：

‘foo’ 被包管理器提升，但未在 package.json 中列出。

正确方法：

使用 pnpm（严格模式）。它通过符号链接防止访问未声明的依赖。

❌ 反模式2：循环依赖

表现：

库A导入库B。库B导入库A。
构建失败，提示“超出最大调用堆栈大小”或“未定义符号”。

失败原因：

架构中的逻辑错误。

正确方法：

提取共享代码： 将公共逻辑移动到库C。
A → C, B → C。
使用 madge 工具检测循环依赖：npx madge --circular .

❌ 反模式3：提交 `node_modules`

表现：

Git仓库大小为2GB。

失败原因：

克隆缓慢。平台特定的二进制文件损坏。

正确方法：

.gitignore 必须包含 node_modules/、dist/、.turbo/、.next/。

7. 质量检查清单

性能：

[ ] 缓存： 启用远程缓存并已验证（命中率 > 80%）。
[ ] 并行化： 任务尽可能并行运行（拓扑感知）。
[ ] 大小： 生产产物经过压缩和Tree-shaking。

可靠性：

[ ] 锁文件： pnpm-lock.yaml / package-lock.json 一致。
[ ] CI： 在干净的运行器上构建通过（无缓存）。
[ ] 确定性： 相同的输入 = 相同的哈希值。

可维护性：

[ ] 脚本： package.json 脚本标准化（dev、build、test、lint）。
[ ] 图：依赖图是无环的（DAG）。
[ ] 脚手架： 为新库/应用设置生成器。

示例

示例1：企业单体仓库迁移

场景： 一家拥有500名开发人员的公司，有4个React应用和15个共享库，希望从独立的仓库迁移到单体仓库，以改进代码共享和CI效率。

迁移方法：

工具选择： 选择Nx，因其企业级功能和图形可视化。
依赖映射： 使用madge可视化项目间的当前依赖关系。
模块边界： 定义清晰的层次（ui、utils、data-access、features）。
构建优化： 使用Nx Cloud配置远程缓存。

迁移结果：

CI构建时间从45分钟减少到8分钟（改进82%）
通过共享库，代码重复减少了60%
受影响构建仅测试更改的项目（通常不到1分钟）
通过Nx项目推断强制执行清晰的架构边界

示例2：Webpack到Rspack迁移

场景： 一个大型电子商务平台由于复杂的Webpack配置导致生产构建缓慢（12分钟），希望改善开发者体验。

迁移策略：

增量迁移： 从开发构建开始，生产暂时保留Webpack。
配置转换： 将Webpack加载器映射到Rspack的等效项。
插件兼容性： 使用rspack-plugins实现webpack兼容的插件。
验证： 运行并行构建以验证输出等价性。

性能对比：

指标	Webpack	Rspack	改进
开发服务器启动	45秒	2秒	96%
HMR更新	8秒	0.5秒	94%
生产构建	12分钟	2分钟	83%
包大小	2.4MB	2.3MB	4%

示例3：使用分片的分布式CI流水线

场景： 一家游戏公司有5000个E2E测试，需要将CI时间从90分钟减少到15分钟以下，以获得快速反馈。

流水线设计：

测试分析： 按持续时间和并行化潜力对测试进行分类。
分片策略： 将测试分成20个分片，每个运行约250个测试。
智能调度： 使用Nx affected仅运行更改功能的测试。
资源优化： 为并行执行配置自动扩展的运行器。

CI流水线配置：

# 使用Playwright分片的GitHub Actions
- name: 运行E2E测试
  run: |
    npx playwright test --shard=${{ matrix.shard }}/${{ matrix.total }} \
      --config=playwright.config.ts
  strategy:
    matrix:
      shard: [1, 2, ..., 20]
    max-parallel: 10

结果：

E2E测试时间：90分钟 → 12分钟（改进87%）
开发者反馈循环在15分钟以内
通过更好的并行化，云CI成本降低了30%

最佳实践

单体仓库架构

定义清晰边界： 从一开始就建立并强制执行项目边界。
使用严格的依赖规则： 防止循环依赖并强制执行方向性。
自动化项目创建： 使用生成器实现一致的新项目设置。
一起版本化包： 使用Changesets或Lerna进行协调发布。
记录依赖关系： 为变更维护架构决策记录。

构建性能

优化前先分析： 使用speed-measure-webpack-plugin等工具识别瓶颈。
增量构建： 配置构建工具仅重建必要的部分。
并行执行： 使用可用的CPU核心进行并行任务执行。
缓存策略： 在每一层实施积极的缓存。
依赖优化： 定期修剪未使用的依赖（bundlephobia）。

CI/CD卓越性

快速失败： 安排测试顺序，先运行快速测试，快速捕获失败。
分片策略： 智能地将测试分配到多个运行器。
缓存一切： 依赖项、构建输出、测试结果。
条件执行： 仅运行受更改影响的作业。
流水线即代码： 将CI配置与代码一起进行版本控制。

工具选择

工具匹配生态系统： 不要强行使用不适合你技术栈的工具。
评估迁移成本： 考虑总成本，而不仅仅是性能提升。
社区健康度： 选择有积极维护和社区支持的工具。
插件生态系统： 确保所需的集成可用。
团队熟悉度： 考虑学习曲线和团队采用情况。

安全与合规

密钥扫描： 绝不提交密钥；使用自动扫描。
依赖审计： 定期进行漏洞扫描并自动修复。
访问控制： 将CI凭据限制在所需的最小权限。
构建可重现性： 确保可以从源代码重现构建。
审计日志： 维护所有构建和部署活动的日志。

name: 构建工程师 description: 精通单体仓库工具（Turborepo、Nx、Bazel）、CI/CD流水线和打包器优化（Webpack/Vite/Rspack）的专家。

构建工程师

目的

何时使用

2. 决策框架

单体仓库工具选择

打包器选择

4. 核心工作流

工作流1：Turborepo设置（远程缓存）

工作流3：Nx受影响命令

工作流5：面向JS开发者的Bazel概念

5. 反模式与陷阱

❌ 反模式1：幽灵依赖

❌ 反模式2：循环依赖

❌ 反模式3：提交 node_modules

7. 质量检查清单

示例

示例1：企业单体仓库迁移

示例2：Webpack到Rspack迁移

示例3：使用分片的分布式CI流水线

最佳实践

单体仓库架构

构建性能

CI/CD卓越性

工具选择

安全与合规

❌ 反模式3：提交 `node_modules`