turborepo

Turborepo 开发

你精通 Turborepo，这是一个面向 JavaScript 和 TypeScript 单体仓库的高性能构建系统。

项目结构

• 按照标准 Turborepo 结构组织工作区：
  • apps/ - 应用工作区（Web 应用、API、移动应用）
  • packages/ - 共享包（UI 组件、实用工具、配置）
  • tooling/ - 构建工具和配置（可选）
• 让根目录的 package.json 保持精简，仅包含工作区配置
• 在所有工作区中采用一致的命名约定

工作区配置

• 在根目录的 package.json 中定义工作区：

  {
    "workspaces": ["apps/*", "packages/*"]
  }
  

• 每个工作区都应有自己的 package.json，并正确声明依赖
• 使用工作区协议引用内部包："@repo/ui": "workspace:*"

turbo.json 配置

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

• 使用 ^ 前缀定义拓扑依赖（优先构建依赖项）
• 正确设置 outputs，以实现缓存
• 将开发任务标记为 cache: false 和 persistent: true

缓存策略

• 使用 Vercel 或可自托管的解决方案配置 CI/CD 远程缓存
• 准确设置 outputs 数组，确保正确命中缓存
• 使用 inputs 指定会影响任务缓存的文件
• 从输出中排除缓存目录（例如 !.next/cache/**）

任务依赖

• 使用 dependsOn 定义任务关系：
  • "^build" - 先在依赖项中运行构建
  • "lint" - 在同一包中运行 lint
  • "@repo/ui#build" - 在指定包中运行构建
• 为复杂构建流水线定义正确的任务顺序

共享配置

• 创建共享配置包：
  • @repo/typescript-config - 共享 TypeScript 配置
  • @repo/eslint-config - 共享 ESLint 配置
  • @repo/tailwind-config - 共享 Tailwind 配置
• 在工作区配置中使用 extends 或导入来引用配置

开发工作流

• 使用 turbo dev 在各个工作区运行开发服务器
• 使用筛选参数将命令限定到特定工作区：turbo build --filter=web
• 使用带模式的 --filter：turbo build --filter=./apps/*
• 使用 turbo watch 进入监视模式，持续构建

CI/CD 集成

• 在 CI 中启用远程缓存，以加快构建速度
• 使用 --dry-run 预览将要执行的操作
• 使用 globalEnv 和 env 正确处理环境变量
• 使用 Turborepo 缓存配置 GitHub Actions 或其他 CI

最佳实践

• 在相似工作区中保持任务定义一致
• 使用工作区级别的 turbo.json 设置包专属的覆盖配置
• 尽量减少根目录级别的依赖；在需要它们的工作区中安装
• 在 README 文件中说明工作区的用途及相互关系
• 使用 TypeScript 项目引用，加快类型检查
• 为大型代码库实现增量构建