Monorepo 构建与部署：Turborepo、Nx 与 pnpm workspace 实战

apps/
  web/        # Next.js 前端
  api/        # Node API
  worker/     # 边缘函数
packages/
  ui/         # 共享组件库
  utils/      # 共享工具
  types/      # 共享类型
configs/
  eslint/     # 共享配置
  tsconfig/   # 共享 TS 配置

适合：多包共享代码、前后端联动频繁、需要原子发布
不适合：团队大且耦合低、各包独立发布节奏、权限隔离要求高

pnpm 三大特性：
  1. 内容寻址存储（硬链接）→ 省磁盘、省安装
  2. 严格依赖隔离（非扁平 node_modules）→ 不会「幽灵依赖」
  3. workspace 原生支持 → 跨包引用直接 link

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

# 常用命令
pnpm install                      # 安装全部
pnpm --filter web dev             # 只跑 web
pnpm --filter ui build            # 只构建 ui
pnpm -r run test                  # 所有包跑 test

// apps/web/package.json 引用本地包
{
  "dependencies": {
    "@repo/ui": "workspace:*",    // 本地 link
    "@repo/utils": "workspace:*"
  }
}

1. peer 依赖重复（React 多副本）→ 用 catalog / overrides 统一版本
2. 循环依赖（ui 依赖 utils，utils 依赖 ui）→ 拆包消除
3. 版本漂移（不同包用不同 React 版本）→ 统一 catalog

# pnpm-workspace.yaml 支持 catalog 统一版本
catalog:
  react: ^19.0.0
  typescript: ^5.5.0

多包 → 每个包都 build/lint/test → 全量跑很慢
解法：任务编排（只跑受影响）+ 缓存（重复任务秒回）

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],   // 先构建依赖
      "outputs": [".next/**", "dist/**"],
      "cache": true
    },
    "lint": {},
    "test": {}
  }
}

pnpm turbo build            # 全量（首次）
pnpm turbo build --filter=web   # 只构建 web 及依赖
pnpm turbo ls                # 查看任务图

缓存键 = 代码哈希 + 配置 + 依赖 → 未变则命中缓存
命中 = 直接从缓存拿产物（秒级），不重新执行
远程缓存（Turborepo Remote Cache / Vercel）→ CI 与本地共享缓存

# 开启远程缓存（Turborepo + Vercel）
pnpm dlx turbo login
pnpm turbo build --remote-cache

Nx 额外能力：
  1. Affected 分析（git 变更 → 只跑相关任务）
  2. 图可视化（nx graph）
  3. 代码生成（nx generate）
Turborepo 更轻量、聚焦缓存；Nx 功能全、学习成本高

改动 packages/utils → 只需构建依赖 utils 的包，无关包跳过
实现：
  Turborepo：缓存自动处理（未变的包命中缓存）
  Nx：nx affected:build --base=main

# Nx Affected
npx nx affected:build --base=origin/main   # 对比 main 的变更影响
npx nx affected:test --base=origin/main

# Turborepo：缓存天然实现「未变即命中」
pnpm turbo build --filter=[origin/main...HEAD]   # 变更范围

# 示例：CI 用 affected 缩短构建时间
jobs:
  build:
    steps:
      - checkout
      - run: pnpm install
      - run: npx nx affected:build --base=origin/main   # 只构建受影响
      - run: npx nx affected:test --base=origin/main

1. 小改动不再全量构建 → CI 快 10 倍
2. 只部署受影响的 app → 发布快、风险小
3. 全量构建作为 main 的定期兜底

# Vercel 自动识别 Monorepo，按目录部署
# 根目录/目录配置
vercel.json:
{
  "buildCommand": "pnpm --filter web build",
  "outputDirectory": "apps/web/.next"
}

// 多个应用各自部署
// 每个 app 有独立 vercel.json，或用 workspace 自动探测
{
  "projectSettings": {
    "framework": "nextjs",
    "rootDirectory": "apps/web"
  }
}

# 在 apps/worker 内
cd apps/worker
wrangler deploy

# CI 中按 affected 决定部署哪些子应用
if [ "$(git diff --name-only origin/main...HEAD | grep -c '^apps/worker/')" -gt 0 ]; then
  pnpm --filter worker deploy
fi

1. 只部署受影响的 app（affected）
2. 每个 app 独立 preview URL（Vercel 自动）
3. 构建产物缓存共享（远程缓存）
4. 环境变量按 app 维度管理
5. 依赖安装一次（根目录 pnpm install）→ 各 app 复用

单版本（Turborepo 风格）：所有包同一版本 → 简单，联动发布
独立版本：各包独立 → 灵活，但协调复杂

# 1. 提交变更说明
pnpm changeset add          # 选择受影响包 + 版本类型（major/minor/patch）

# 2. 合并后 CI 生成 changelog + 升版本
pnpm changeset version      # 根据 changesets 更新版本与 CHANGELOG

# 3. 发布
pnpm changeset publish      # npm publish + 打 tag

// .changeset/config.json
{
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "access": "public",
  "baseBranch": "main"
}

PR（带 changeset）→ 合并 main → CI 检查 changeset
→ changeset version（生成 changelog）→ 发布 → 打 tag → 通知

1. 团队独立、发布节奏完全独立
2. 代码共享需求低
3. 仓库规模过大导致工具链卡顿
4. 权限隔离要求严格（多租户/外包）

不一定要一步到位：
  先 2-3 个强耦合包合并 → 建立 workspace
  → 引入 Turborepo 缓存 → 再引入 affected/发布流水线
从「共享代码」起步，逐步演进