build-engineer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Engineer

构建工程师

Purpose

目标

Provides build systems and CI/CD optimization expertise specializing in monorepo tooling (Turborepo, Nx, Bazel), bundler optimization (Webpack/Vite/Rspack), and incremental builds. Focuses on optimizing development velocity through caching, parallelization, and build performance.

提供专注于Monorepo工具（Turborepo、Nx、Bazel）、打包工具优化（Webpack/Vite/Rspack）和增量构建的构建系统与CI/CD优化专业支持。通过缓存、并行化和构建性能优化提升开发效率。

When to Use

适用场景

Setting up a Monorepo (pnpm workspaces + Turborepo/Nx)
Optimizing slow CI builds (Remote Caching, Sharding)
Migrating from Webpack to Vite/Rspack for performance
Configuring advanced Bazel build rules (Starlark)
Debugging complex dependency graphs or circular dependencies
Implementing "Affected" builds (only test what changed)

搭建Monorepo（pnpm workspaces + Turborepo/Nx）
优化缓慢的CI构建（远程缓存、分片）
从Webpack迁移到Vite/Rspack以提升性能
配置高级Bazel构建规则（Starlark）
调试复杂依赖图或循环依赖
实现「受影响」构建（仅测试变更内容）

2. Decision Framework

2. 决策框架

Monorepo Tool Selection

Monorepo工具选择

Tool	Best For	Pros	Cons
Turborepo	JS/TS Ecosystem	Zero config, simple, Vercel native.	JS only (mostly), less granular than Bazel.
Nx	Enterprise JS/TS	Powerful plugins, code generation, graph visualization.	heavier configuration, opinionated.
Bazel	Polyglot (Go/Java/JS)	Hermetic builds, infinite scale (Google style).	Massive learning curve, complex setup.
Pnpm Workspaces	Simple Projects	Native to Node.js, fast installation.	No task orchestration (needs Turbo/Nx).

工具	最佳适用场景	优势	劣势
Turborepo	JS/TS生态系统	零配置、简单易用、原生适配Vercel	主要支持JS，粒度不如Bazel精细
Nx	企业级JS/TS项目	强大的插件、代码生成、依赖图可视化	配置复杂、具有较强的约定式特性
Bazel	多语言项目（Go/Java/JS）	封闭构建、支持无限扩展（谷歌风格）	学习曲线陡峭、设置复杂
Pnpm Workspaces	简单项目	原生适配Node.js、安装速度快	无任务编排能力（需搭配Turbo/Nx）

Bundler Selection

打包工具选择

What is the priority?
│
├─ **Development Speed (HMR)**
│  ├─ Web App? → **Vite** (ESModules based, instant start)
│  └─ Legacy App? → **Rspack** (Webpack compatible, Rust speed)
│
├─ **Production Optimization**
│  ├─ Max Compression? → **Webpack** (Mature ecosystem of plugins)
│  └─ Speed? → **Rspack / Esbuild**
│
└─ **Library Authoring**
   └─ Dual Emit (CJS/ESM)? → **Rollup** (Tree-shaking standard)

Red Flags → Escalate to
devops-engineer
:

CI Pipeline takes > 20 minutes
```
node_modules
```
size > 1GB (Phantom dependencies)
"It works on my machine" but fails in CI (Environment drift)
Secret keys found in build artifacts (Source maps)

优先级是什么？
│
├─ **开发速度（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. Core Workflows

4. 核心工作流

Workflow 1: Turborepo Setup (Remote Caching)

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

Goal: Reduce CI time by 80% by reusing cache artifacts.

Steps:

Configuration (
turbo.json
)

json

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

Remote Cache

Link to Vercel Remote Cache:
```
npx turbo link
```
.

In CI (GitHub Actions):

yaml

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

Execution
- ```
turbo run build test lint
```
- First run: 5 mins. Second run: 100ms (FULL TURBO).

目标： 通过复用缓存产物将CI时间缩短80%。

步骤：

配置（
turbo.json
）

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）中配置：

yaml

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

执行
- ```
turbo run build test lint
```
- 首次运行：5分钟。二次运行：100ms（完全复用缓存）。

Workflow 3: Nx Affected Commands

工作流3：Nx受影响命令

Goal: Only run tests for changed projects in a monorepo.

Steps:

Analyze Graph
- ```
nx graph
```
  (Visualizes dependencies: App A depends on Lib B).

CI Pipeline

bash

# Only test projects affected by PR
npx nx affected -t test --base=origin/main --head=HEAD

# Only lint affected
npx nx affected -t lint --base=origin/main

目标： 仅测试Monorepo中变更的项目。

步骤：

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

CI流水线配置

bash

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

# 仅检查受影响项目的代码规范
npx nx affected -t lint --base=origin/main

Workflow 5: Bazel Concepts for JS Developers

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

Goal: Understand

BUILD

files vs

package.json

Mapping:

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

Code Example (
BUILD.bazel
):

starlark

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

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

目标： 理解

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
）：

starlark

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

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

5. Anti-Patterns & Gotchas

5. 反模式与注意事项

❌ Anti-Pattern 1: Phantom Dependencies

❌ 反模式1：幽灵依赖

What it looks like:

```
import foo from 'foo'
```
works locally but fails in CI.

Why it fails:

'foo' is hoisted by the package manager but not listed in
```
package.json
```
.

Correct approach:

Use pnpm (Strict mode). It prevents accessing undeclared dependencies via symlinks.

表现：

```
import foo from 'foo'
```
本地运行正常，但CI构建失败。

失败原因：

'foo'被包管理器提升但未在
```
package.json
```
中声明。

正确做法：

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

❌ Anti-Pattern 2: Circular Dependencies

❌ 反模式2：循环依赖

What it looks like:

Lib A imports Lib B. Lib B imports Lib A.
Build fails with "Maximum call stack exceeded" or "Undefined symbol".

Why it fails:

Logic error in architecture.

Correct approach:

Extract Shared Code: Move common logic to Lib C.
A → C, B → C.
Use
```
madge
```
tool to detect circular deps:
```
npx madge --circular .
```

表现：

库A导入库B，库B导入库A。
构建失败并提示「Maximum call stack exceeded」或「Undefined symbol」。

失败原因：

架构设计中的逻辑错误。

正确做法：

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

❌ Anti-Pattern 3: Committing

node_modules

❌ 反模式3：提交

node_modules

What it looks like:

Git repo size is 2GB.

Why it fails:

Slow clones. Platform specific binaries break.

Correct approach:

.gitignore

must include

node_modules/

dist/

.turbo/

.next/

表现：

Git仓库体积达2GB。

失败原因：

克隆速度慢，平台特定二进制文件会导致构建失败。

正确做法：

.gitignore

必须包含

node_modules/

、

dist/

、

.turbo/

、

.next/

。

7. Quality Checklist

7. 质量检查清单

Performance:

Cache: Remote caching enabled and verified (Hit rate > 80%).
Parallelism: Tasks run in parallel where possible (Topology aware).
Size: Production artifacts minified and tree-shaken.

Reliability:

Lockfile:
```
pnpm-lock.yaml
```
/
```
package-lock.json
```
is consistent.
CI: Builds pass on clean runner (no cache).
Determinism: Same inputs = Same hash.

Maintainability:

Scripts:
```
package.json
```
scripts standardized (
```
dev
```
,
```
build
```
,
```
test
```
,
```
lint
```
).
Graph: Dependency graph is acyclic (DAG).
Scaffolding: Generators set up for new libraries/apps.

性能：

缓存： 已启用并验证远程缓存（命中率>80%）。
并行化： 尽可能并行执行任务（拓扑感知）。
体积： 生产产物已压缩并进行Tree-shaking。

可靠性：

锁文件：
```
pnpm-lock.yaml
```
/
```
package-lock.json
```
保持一致。
CI： 在干净的 runner（无缓存）上构建通过。
确定性： 相同输入生成相同哈希值。

可维护性：

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

Examples

案例

Example 1: Enterprise Monorepo Migration

案例1：企业级Monorepo迁移

Scenario: A 500-developer company with 4 React applications and 15 shared libraries wants to migrate from separate repos to a monorepo to improve code sharing and CI efficiency.

Migration Approach:

Tool Selection: Chose Nx for enterprise features and graph visualization
Dependency Mapping: Used madge to visualize current dependencies between projects
Module Boundaries: Defined clear layers (ui, utils, data-access, features)
Build Optimization: Configured remote caching with Nx Cloud

Migration Results:

CI build time reduced from 45 minutes to 8 minutes (82% improvement)
Code duplication reduced by 60% through shared libraries
Affected builds only test changed projects (often under 1 minute)
Clear architectural boundaries enforced by Nx project inference

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

迁移方案：

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

迁移结果：

CI构建时间从45分钟缩短至8分钟（提升82%）
通过共享库减少60%的代码重复
受影响构建仅测试变更项目（通常耗时不到1分钟）
Nx项目推断功能强制实施清晰的架构边界

Example 2: Webpack to Rspack Migration

案例2：Webpack到Rspack迁移

Scenario: A large e-commerce platform has slow production builds (12 minutes) due to complex Webpack configuration and wants to improve developer experience.

Migration Strategy:

Incremental Migration: Started with development builds, kept Webpack for production temporarily
Config Translation: Mapped Webpack loaders to Rspack equivalents
Plugin Compatibility: Used rspack-plugins for webpack-compatible plugins
Verification: Ran parallel builds to verify output equivalence

Performance Comparison:

Metric	Webpack	Rspack	Improvement
Dev server start	45s	2s	96%
HMR update	8s	0.5s	94%
Production build	12m	2m	83%
Bundle size	2.4MB	2.3MB	4%

场景： 某大型电商平台因复杂的Webpack配置导致生产构建缓慢（12分钟），希望提升开发体验。

迁移策略：

增量迁移：从开发构建开始迁移，暂时保留Webpack用于生产环境
配置转换：将Webpack loader映射为Rspack等效配置
插件兼容：使用rspack-plugins适配Webpack兼容插件
验证：运行并行构建以验证输出一致性

性能对比：

指标	Webpack	Rspack	提升幅度
开发服务器启动	45s	2s	96%
HMR更新	8s	0.5s	94%
生产构建	12m	2m	83%
产物体积	2.4MB	2.3MB	4%

Example 3: Distributed CI Pipeline with Sharding

案例3：分布式CI流水线分片

Scenario: A gaming company with 5,000 E2E tests needs to reduce CI time from 90 minutes to under 15 minutes for fast feedback.

Pipeline Design:

Test Analysis: Categorized tests by duration and parallelism potential
Shard Strategy: Split tests into 20 shards, each running ~250 tests
Smart Scheduling: Used Nx affected to only run tests for changed features
Resource Optimization: Configured auto-scaling runners for parallel execution

CI Pipeline Configuration:

yaml

undefined

场景： 某游戏公司拥有5000个E2E测试用例，需要将CI时间从90分钟缩短至15分钟以内以实现快速反馈。

流水线设计：

测试分析：按测试时长和并行潜力分类测试用例
分片策略：将测试分为20个分片，每个分片运行约250个测试
智能调度：使用Nx affected仅运行变更功能相关的测试
资源优化：配置自动扩缩容的runner以并行执行

CI流水线配置：

yaml

undefined

GitHub Actions with Playwright sharding

GitHub Actions搭配Playwright分片

name: Run E2E Tests run: | npx playwright test --shard=${{ matrix.shard }}/${{ matrix.total }}
--config=playwright.config.ts strategy: matrix: shard: [1, 2, ..., 20] max-parallel: 10


**Results:**
- E2E test time: 90m → 12m (87% improvement)
- Developer feedback loop under 15 minutes
- Reduced cloud CI costs by 30% through better parallelism

name: Run E2E Tests run: | npx playwright test --shard=${{ matrix.shard }}/${{ matrix.total }}
--config=playwright.config.ts strategy: matrix: shard: [1, 2, ..., 20] max-parallel: 10


**结果：**
- E2E测试时间：90m → 12m（提升87%）
- 开发者反馈周期缩短至15分钟以内
- 通过更优的并行化将云CI成本降低30%

Best Practices

最佳实践

Monorepo Architecture

Monorepo架构

Define Clear Boundaries: Establish and enforce project boundaries from day one
Use Strict Dependency Rules: Prevent circular dependencies and enforce directionality
Automate Project Creation: Use generators for consistent new project setup
Version Packages Together: Use Changesets or Lerna for coordinated releases
Document Dependencies: Maintain architecture decision records for changes

定义清晰边界：从第一天开始建立并强制执行项目边界
使用严格依赖规则：禁止循环依赖并强制依赖方向性
自动化项目创建：使用生成器确保新项目配置一致
统一版本发布：使用Changesets或Lerna进行协同发布
文档化依赖关系：维护架构决策记录以追踪变更

Build Performance

构建性能

Profile Before Optimizing: Use tools like speed-measure-webpack-plugin to identify bottlenecks
Incremental Builds: Configure build tools to only rebuild what's necessary
Parallel Execution: Use available CPU cores for parallel task execution
Caching Strategies: Implement aggressive caching at every layer
Dependency Optimization: Prune unused dependencies regularly (bundlephobia)

先分析再优化：使用speed-measure-webpack-plugin等工具识别瓶颈
增量构建：配置构建工具仅重建必要内容
并行执行：利用可用CPU核心并行执行任务
缓存策略：在每一层实现激进的缓存
依赖优化：定期清理未使用的依赖（使用bundlephobia）

CI/CD Excellence

CI/CD最佳实践

Fail Fast: Order tests to run fast tests first, catch failures quickly
Sharding Strategy: Distribute tests across multiple runners intelligently
Cache Everything: Dependencies, build outputs, test results
Conditional Execution: Only run jobs that are affected by the change
Pipeline as Code: Version control CI configuration alongside code

快速失败：优先运行快速测试，尽早发现问题
分片策略：智能地将测试分布到多个runner执行
全面缓存：缓存依赖、构建产物、测试结果
条件执行：仅运行受变更影响的任务
流水线即代码：将CI配置与代码一起版本控制

Tool Selection

工具选择

Match Tool to Ecosystem: Don't force tools that don't fit your stack
Evaluate Migration Cost: Consider total cost, not just performance gains
Community Health: Choose tools with active maintenance and community support
Plugin Ecosystem: Ensure required integrations are available
Team Familiarity: Consider learning curve and team adoption

匹配工具与生态：不要强行使用不符合技术栈的工具
评估迁移成本：考虑总成本而非仅性能收益
社区活跃度：选择维护活跃、社区支持好的工具
插件生态：确保所需集成可用
团队熟悉度：考虑学习曲线和团队接受度

Security and Compliance

安全与合规

Secret Scanning: Never commit secrets; use automated scanning
Dependency Auditing: Regular vulnerability scans with automated fixes
Access Control: Limit CI credentials to minimum required permissions
Build Reproducibility: Ensure builds can be reproduced from source
Audit Logging: Maintain logs of all build and deployment activities

密钥扫描：绝不提交密钥；使用自动化扫描工具
依赖审计：定期进行漏洞扫描并自动修复
访问控制：将CI凭证权限限制为最小必要范围
构建可复现性：确保从源码可复现构建结果
审计日志：保留所有构建和部署活动的日志

build-engineer

Original

Translation

Build Engineer

构建工程师

Purpose

目标

When to Use

适用场景

2. Decision Framework

2. 决策框架

Monorepo Tool Selection

Monorepo工具选择

Bundler Selection

打包工具选择

4. Core Workflows

4. 核心工作流

Workflow 1: Turborepo Setup (Remote Caching)

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

Workflow 3: Nx Affected Commands

工作流3：Nx受影响命令

Workflow 5: Bazel Concepts for JS Developers

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

5. Anti-Patterns & Gotchas

5. 反模式与注意事项

❌ Anti-Pattern 1: Phantom Dependencies

❌ 反模式1：幽灵依赖

❌ Anti-Pattern 2: Circular Dependencies

❌ 反模式2：循环依赖

❌ Anti-Pattern 3: Committing node_modules

❌ 反模式3：提交node_modules

7. Quality Checklist

7. 质量检查清单

Examples

案例

Example 1: Enterprise Monorepo Migration

案例1：企业级Monorepo迁移

Example 2: Webpack to Rspack Migration

案例2：Webpack到Rspack迁移

Example 3: Distributed CI Pipeline with Sharding

案例3：分布式CI流水线分片

GitHub Actions with Playwright sharding

GitHub Actions搭配Playwright分片

Best Practices

最佳实践

Monorepo Architecture

Monorepo架构

Build Performance

构建性能

CI/CD Excellence

CI/CD最佳实践

Tool Selection

工具选择

Security and Compliance

安全与合规

❌ Anti-Pattern 3: Committing
`node_modules`

❌ 反模式3：提交
`node_modules`