turborepo

Turborepo 技能

为使用 Turborepo 的 JavaScript 和 TypeScript 单体仓库提供构建系统指导。

核心规则

1. 创建包级任务，而不是根级任务。
2. 在 turbo.json 中注册任务行为。
3. 让根目录 package.json 通过 turbo run <task> 进行委派。
4. 仅在交互式的一次性终端命令中使用 turbo <task>，不要在提交的代码中使用。
5. 在 package.json 中声明工作区依赖，以便 dependsOn: ["^build"] 能解析实际的包关系。

基本模式

// apps/web/package.json
{
  "scripts": {
    "build": "next build",
    "lint": "eslint .",
    "test": "vitest"
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

// root package.json
{
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test"
  }
}

快速查阅

只阅读任务所需的参考文件：

需求	阅读
任务定义、dependsOn、outputs、persistent、包级覆盖	references/configuration/RULE.md、references/configuration/tasks.md
全局选项、守护进程、cacheDir、环境模式	references/configuration/global-options.md
缓存未命中或远程缓存	references/caching/RULE.md、references/caching/gotchas.md、references/caching/remote-cache.md
环境变量、.env、严格模式与宽松模式	references/environment/RULE.md、references/environment/modes.md、references/environment/gotchas.md
--affected、--filter、包选择	references/filtering/RULE.md、references/filtering/patterns.md
CI、GitHub Actions、Vercel、turbo-ignore	references/ci/RULE.md、references/ci/github-actions.md、references/ci/vercel.md、references/ci/patterns.md、references/cli/commands.md
仓库结构、创建包、依赖管理	references/best-practices/RULE.md、references/best-practices/structure.md、references/best-practices/packages.md、references/best-practices/dependencies.md
监视模式和长时间运行的开发任务	references/watch/RULE.md、references/configuration/tasks.md
包边界与隔离	references/boundaries/RULE.md

决策树

配置任务

Configure a task?
├─ Define dependencies or outputs → configuration/tasks.md
├─ Handle environment variables → environment/RULE.md
├─ Set package-specific overrides → configuration/RULE.md#package-configurations
├─ Add persistent/watch behavior → configuration/tasks.md + watch/RULE.md
└─ Tune global options → configuration/global-options.md

调试缓存

Cache issue?
├─ Outputs not restored → add or fix `outputs`
├─ Unexpected misses → caching/gotchas.md
├─ Remote cache issue → caching/remote-cache.md
└─ Env or .env drift → environment/gotchas.md

仅运行变更部分

Need changed packages only?
├─ Default path → `turbo run <task> --affected`
├─ Custom comparison base → add `--affected-base=...`
└─ Custom package selection → filtering/RULE.md + filtering/patterns.md

设置 CI

CI setup?
├─ GitHub Actions → ci/github-actions.md
├─ Vercel deployment → ci/vercel.md
├─ Remote cache in CI → caching/remote-cache.md
└─ Skip unchanged work → ci/patterns.md + cli/commands.md

组织单体仓库结构

Repo/package structure?
├─ apps/ vs packages/ layout → best-practices/RULE.md
├─ Create internal package → best-practices/packages.md
├─ Workspace dependency management → best-practices/dependencies.md
└─ Enforce package boundaries → boundaries/RULE.md

高风险反模式

• 完全绕过 Turborepo 的根目录脚本。根目录脚本应使用 turbo run 进行委派，而不是嵌入特定应用的任务逻辑。
• 在 package.json、CI 或脚本中提交 turbo build 或 turbo lint 命令。在提交的代码中使用 turbo run ...。
• 手动使用 prebuild 链编译同级包，而不是声明工作区依赖并使用 ^build。
• 对会写入文件的任务未设置 outputs。确定任务是否可缓存前，先查看实际脚本。
• 环境变量未列入 env，或 .env 文件未列入 inputs，导致缓存命中结果过期。
• 在单体仓库中使用根目录级 .env 文件，导致包之间产生隐式耦合。
• 跨包边界使用相对导入或遍历文件，而不是通过包 API 导入。
• 在根目录 turbo.json 中堆积特定包的覆盖配置，而不是使用各包自己的 turbo.json 文件。

详细示例见：

• references/configuration/gotchas.md
• references/caching/gotchas.md
• references/environment/gotchas.md
• references/best-practices/structure.md
• references/best-practices/packages.md

常见配置

标准构建与开发

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

用于并行任务并确保正确缓存失效的传递节点

{
  "tasks": {
    "transit": {
      "dependsOn": ["^transit"]
    },
    "lint": {
      "dependsOn": ["transit"]
    }
  }
}

当任务可以并行运行，但仍需在依赖项源代码变更时使其缓存失效，请使用此配置。

监视模式模式

文件变更循环应使用 turbo watch，不要在脚本中自行拼凑 turbo run ... --watch 模式。配置 persistent、interruptible 或 with 之前，请阅读 references/watch/RULE.md。

验证清单

• 所有已提交的代码或 CI 命令都使用 turbo run ...。
• 任务定义在软件包脚本中；根目录脚本只负责委派。
• dependsOn 与实际依赖关系一致：上游软件包使用 ^task，同一软件包的前置任务使用 task。
• 可缓存且会生成文件的任务声明了 outputs。
• 相关环境变量列在 env 或 globalEnv 中。
• 相关 .env 文件列在 inputs 中。
• 工作区软件包通过软件包名称互相导入，而非使用相对源代码路径。
• CI 在适当情况下使用 --affected 或筛选器，而不是默认重新构建所有内容。

源文档

基于 Turborepo 官方文档（library v2.9.7-canary.12）：apps/docs/content/docs/ — https://turborepo.dev/docs