shared-monorepo-turborepo

使用 Turborepo 进行单体仓库编排

快速指南： 使用 Turborepo 2.x 进行单体仓库编排。通过任务流水线管理依赖顺序。利用本地和远程缓存大幅提升速度。使用工作区链接软件包。使用 Syncpack 确保依赖版本一致。内部软件包采用 @repo/* 命名、显式 exports 字段和 workspace:* 协议。

---

<critical_requirements>

重要：使用此技能前

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入顺序、import type、命名常量）

（必须在 turbo.json 中使用 dependsOn: ["^build"] 定义任务依赖，以确保拓扑排序）

（必须在 turbo.json 任务的 env 数组中声明所有环境变量，以便正确地使缓存失效）

（对于开发服务器和代码生成等具有副作用的任务，必须设置 cache: false）

（内部软件包依赖必须使用 workspace:* 协议）

（所有内部软件包必须采用 @repo/* 命名约定）

（必须在 package.json 中定义显式的 exports 字段，绝不允许导入内部路径）

（组件软件包必须将 React 标记为 peerDependencies，而不是 dependencies）

</critical_requirements>

---

自动检测： Turborepo 配置、turbo.json、单体仓库设置、工作区、Bun 工作区、syncpack、任务流水线、@repo/* 软件包、package.json exports、工作区依赖、共享配置

适用场景：

• 配置 Turborepo 任务流水线和缓存策略
• 设置工作区，以便链接单体仓库中的软件包
• 启用远程缓存，以便团队和 CI 共享缓存
• 在工作区软件包之间同步依赖版本
• 在 packages/ 中创建新的内部软件包
• 配置 package.json exports，以便进行 tree-shaking
• 设置共享配置软件包（@repo/eslint-config、@repo/typescript-config）

不适用场景：

• 单应用项目（直接使用标准构建工具）
• 没有共享软件包的项目（无法获得单体仓库的优势）
• 设置开销超过缓存收益的超小型项目
• 更倾向于采用多仓库架构的项目
• 已使用 Nx 或 Lerna 的项目（不要混用单体仓库工具）
• 不会共享的特定应用代码（保留在应用目录中）

涵盖的关键模式：

• Turborepo 2.x 任务流水线（dependsOn、outputs、inputs、cache）
• 本地和远程缓存策略
• 用于软件包链接的工作区
• 使用 Syncpack 保持依赖版本一致
• 在 turbo.json 中处理环境变量
• 软件包结构和 @repo/* 命名约定
• 用于 tree-shaking 的 package.json exports
• 命名导出和 barrel 文件模式
• 使用工作区协议管理内部依赖

详细资源：

• 代码示例见 examples/core.md（始终从这里开始）
  • examples/caching.md - 远程缓存、CI/CD 集成
  • examples/workspaces.md - 工作区协议、syncpack、依赖边界
  • examples/packages.md - 内部软件包约定、exports、创建软件包
• 决策框架和反模式见 reference.md

---

理念

Turborepo 是一款高性能构建系统，专为 JavaScript/TypeScript 单体仓库设计。它提供智能任务调度、缓存和远程缓存共享功能，可大幅缩短构建时间。结合工作区，它还能通过自动链接依赖项实现高效的软件包管理。

---

核心模式

模式 1：按依赖顺序执行的 Turborepo 任务流水线

在 turbo.json 中定义任务依赖和缓存行为，以实现智能的构建编排与缓存。

核心概念

• dependsOn: ["^build"] - 先运行依赖任务（按拓扑顺序）
• outputs - 定义要缓存的文件
• inputs - 指定哪些文件会触发缓存失效
• cache: false - 对有副作用的任务禁用缓存
• persistent: true - 让开发服务器持续运行

最小示例

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["DATABASE_URL", "NODE_ENV"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": { "cache": false, "persistent": true }
  }
}

要点： dependsOn: ["^build"] 可确保按拓扑顺序执行，env 用于声明会触发缓存失效的变量，cache: false 适用于有副作用的任务。

有关完整的正反示例对比，请参阅 examples/core.md。

---

模式 2：缓存策略

Turborepo 的缓存系统会在输入未发生变化时复用之前的任务输出，大幅加快构建速度。

缓存内容

• 构建输出（dist/、.next/、框架专用目录）
• 测试结果（当 cache: true 时）
• Lint 结果

不缓存的内容

• 开发服务器（cache: false）
• 代码生成（cache: false - 会生成文件）
• 有副作用的任务

缓存失效触发条件

• 源文件变更
• 依赖项变更
• 环境变量变更（当变量位于 env 数组中时）
• 全局依赖项变更（.env、tsconfig.json）

设置： 关联 Vercel 账户（或使用可自托管的缓存），然后设置 TURBO_TOKEN 和 TURBO_TEAM 环境变量，以启用远程缓存共享。

有关远程缓存配置和 CI 集成示例，请参阅 examples/caching.md。

---

模式 3：用于包管理的工作区

配置工作区，以便在 monorepo 包之间启用包链接和依赖共享。

核心概念

• 根目录的 package.json 声明 "workspaces": ["apps/*", "packages/*"]
• 内部依赖项使用 "@repo/ui": "workspace:*" 协议实现自动链接
• 标准结构：apps/ 用于可部署的应用，packages/ 用于共享代码

有关完整的正反示例对比和 syncpack 配置，请参阅 examples/workspaces.md。

---

性能优化

缓存命中指标：

• 首次构建：约 45s（5 个包，无缓存）
• 缓存构建：约 1s（使用本地缓存，快 97%）
• 受影响的构建：约 12s（快 73%，仅重新构建变更的包）
• 团队节省时间：启用远程缓存后，每周可节省数小时

优化策略：

• 设置 globalDependencies，指定会影响所有包的文件（.env、tsconfig.json），以避免不必要的缓存失效
• 使用 inputs 数组，精细调整特定任务的缓存失效触发条件
• 启用远程缓存，在团队和 CI 之间共享构建产物
• 结合受影响项检测使用 --filter（--filter=...[HEAD^]），仅运行变更包的任务
• 谨慎设置 outputs，排除缓存目录（例如 !.next/cache/**）

强制绕过缓存：

# Ignore cache when needed
bun run build --force

# Only build affected packages
bun run build --filter=...[HEAD^1]

---

<decision_framework>

决策框架

New code? → Shared across 2+ apps? → packages/ (else keep in app)
Monorepo? → Builds > 30s or caching matters? → Use Turborepo

有关完整的决策树和创建包的标准，请参阅 reference.md。

</decision_framework>

---

<red_flags>

危险信号

高优先级问题：

• 构建任务缺少 dependsOn: ["^build"]（会破坏拓扑排序）
• turbo.json 中缺少 env 数组（会导致不同环境之间缓存未命中）
• 缓存开发服务器或代码生成任务（会复用错误的输出）
• 库包使用默认导出（会破坏摇树优化）
• package.json 中缺少 exports 字段（允许导入内部路径）

常见错误：

• 内部依赖使用硬编码版本，而不是 workspace:*
• 将 React 放在 dependencies 中，而不是 peerDependencies
• 使用大型 barrel 文件重新导出所有内容（会抵消摇树优化的效果）
• 运行完整测试套件，却不使用 --filter=...[HEAD^] 检测受影响的项目

注意事项：

• dependsOn: ["^task"] 会运行依赖项的任务；dependsOn: ["task"] 会运行同一软件包的任务
• --filter=...[HEAD^] 在 GitHub Actions 中要求设置 fetch-depth: 2
• 在输出中排除缓存目录：!.next/cache/**

有关反模式和检查清单的详细信息，请参阅 reference.md。

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循 CLAUDE.md 中的项目约定

（必须在 turbo.json 中使用 dependsOn: ["^build"] 定义任务依赖关系，以确保拓扑排序）

（必须在 turbo.json 任务的 env 数组中声明所有环境变量，以便正确使缓存失效）

（对于开发服务器和代码生成等具有副作用的任务，必须设置 cache: false）

（内部软件包依赖必须使用 workspace:* 协议）

（所有内部软件包必须采用 @repo/* 命名约定）

（必须在 package.json 中显式定义 exports 字段，绝不允许导入内部路径）

（组件软件包必须将 React 标记为 peerDependencies，而不是 dependencies）

不遵循这些规则会导致构建错误、缓存未命中、依赖解析失败以及摇树优化失效。

</critical_reminders>