name: turborepo description: | Turborepo monorepo 构建系统指导。触发于：turbo.json、任务管道、dependsOn、缓存、远程缓存、“turbo” CLI、–filter、–affected、CI优化、环境变量、内部包、monorepo 结构/最佳实践和边界。

当用户：配置任务/工作流/管道、创建包、设置 monorepo、共享代码在应用间、运行更改/受影响包、调试缓存或有应用/包目录时使用。 metadata: version: 2.8.1

Turborepo 技能

JavaScript/TypeScript monorepo 的构建系统。Turborepo 缓存任务输出并基于依赖图并行运行任务。

重要：包任务，非根任务

不要创建根任务。总是创建包任务。

创建任务/脚本/管道时，必须：

添加脚本到每个相关包的 package.json
在根 turbo.json 中注册任务
根 package.json 只通过 turbo run <task> 委托

不要将任务逻辑放在根 package.json 中。这会破坏 Turborepo 的并行化。

// 做这个：每个包的脚本
// apps/web/package.json
{ "scripts": { "build": "next build", "lint": "eslint .", "test": "vitest" } }

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

// packages/ui/package.json
{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }

// turbo.json - 注册任务
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "lint": {},
    "test": { "dependsOn": ["build"] }
  }
}

// 根 package.json - 只委托，无任务逻辑
{
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test"
  }
}

// 不要做这个 - 破坏并行化
// 根 package.json
{
  "scripts": {
    "build": "cd apps/web && next build && cd ../api && tsc",
    "lint": "eslint apps/ packages/",
    "test": "vitest"
  }
}

根任务 (//#taskname) 只用于真正不能在包中存在的任务（很少）。

次要规则：`turbo run` vs `turbo`

当命令写在代码中时，总是使用 turbo run：

// package.json - 总是 “turbo run”
{
  "scripts": {
    "build": "turbo run build"
  }
}

# CI workflows - 总是 “turbo run”
- run: turbo run build --affected

简写 turbo <tasks> 只用于一次性终端命令 直接由人类或代理键入。永远不要在 package.json、CI 或脚本中写 turbo build。

快速决策树

“我需要配置一个任务”

配置一个任务？
├─ 定义任务依赖 → references/configuration/tasks.md
├─ Lint/check-types (并行 + 缓存) → 使用 Transit Nodes 模式（见下）
├─ 指定构建输出 → references/configuration/tasks.md#outputs
├─ 处理环境变量 → references/environment/RULE.md
├─ 设置开发/监视任务 → references/configuration/tasks.md#persistent
├─ 包特定配置 → references/configuration/RULE.md#package-configurations
└─ 全局设置 (cacheDir, daemon) → references/configuration/global-options.md

“我的缓存不工作”

缓存问题？
├─ 任务运行但输出未恢复 → 缺失 `outputs` 键
├─ 缓存意外未命中 → references/caching/gotchas.md
├─ 需要调试哈希输入 → 使用 --summarize 或 --dry
├─ 想完全跳过缓存 → 使用 --force 或 cache: false
├─ 远程缓存不工作 → references/caching/remote-cache.md
└─ 环境导致未命中 → references/environment/gotchas.md

“我想只运行更改的包”

只运行更改的包？
├─ 更改包 + 依赖包（推荐） → turbo run build --affected
├─ 自定义基础分支 → --affected --affected-base=origin/develop
├─ 手动 git 比较 → --filter=...[origin/main]
└─ 查看所有过滤器选项 → references/filtering/RULE.md

--affected 是运行只更改包的主要方式。 它自动比较默认分支并包括依赖包。

“我想过滤包”

过滤包？
├─ 只更改包 → --affected（见上）
├─ 按包名 → --filter=web
├─ 按目录 → --filter=./apps/*
├─ 包 + 依赖 → --filter=web...
├─ 包 + 被依赖 → --filter=...web
└─ 复杂组合 → references/filtering/patterns.md

“环境变量不工作”

环境问题？
├─ 变量运行时不可用 → 严格模式过滤（默认）
├─ 缓存命中但环境错误 → 变量不在 `env` 键中
├─ .env 更改未导致重建 → .env 不在 `inputs` 中
├─ CI 变量缺失 → references/environment/gotchas.md
└─ 框架变量 (NEXT_PUBLIC_*) → 通过推断自动包含

“我需要设置 CI”

CI 设置？
├─ GitHub Actions → references/ci/github-actions.md
├─ Vercel 部署 → references/ci/vercel.md
├─ CI 中的远程缓存 → references/caching/remote-cache.md
├─ 只构建更改包 → --affected 标志
├─ 跳过不必要构建 → turbo-ignore (references/cli/commands.md)
└─ 无更改时跳过容器设置 → turbo-ignore

“我想在开发时监视更改”

监视模式？
├─ 更改时重新运行任务 → turbo watch (references/watch/RULE.md)
├─ 开发服务器有依赖 → 使用 `with` 键 (references/configuration/tasks.md#with)
├─ 依赖更改时重启开发服务器 → 使用 `interruptible: true`
└─ 持久开发任务 → 使用 `persistent: true`

“我需要创建/结构化包”

包创建/结构？
├─ 创建内部包 → references/best-practices/packages.md
├─ 仓库结构 → references/best-practices/structure.md
├─ 依赖管理 → references/best-practices/dependencies.md
├─ 最佳实践概述 → references/best-practices/RULE.md
├─ JIT vs 编译包 → references/best-practices/packages.md#compilation-strategies
└─ 应用间共享代码 → references/best-practices/RULE.md#package-types

“我该如何构建 monorepo 结构？”

Monorepo 结构？
├─ 标准布局 (apps/, packages/) → references/best-practices/RULE.md
├─ 包类型 (apps vs libraries) → references/best-practices/RULE.md#package-types
├─ 创建内部包 → references/best-practices/packages.md
├─ TypeScript 配置 → references/best-practices/structure.md#typescript-configuration
├─ ESLint 配置 → references/best-practices/structure.md#eslint-configuration
├─ 依赖管理 → references/best-practices/dependencies.md
└─ 强制包边界 → references/boundaries/RULE.md

“我想强制架构边界”

强制边界？
├─ 检查违规 → turbo boundaries
├─ 标记包 → references/boundaries/RULE.md#tags
├─ 限制包可以导入其他包 → references/boundaries/RULE.md#rule-types
└─ 防止跨包文件导入 → references/boundaries/RULE.md

关键反模式

在代码中使用 `turbo` 简写

turbo run 在 package.json 脚本和 CI 管道中推荐使用。 简写 turbo <task> 用于交互式终端使用。

// 错误 - 在 package.json 中使用简写
{
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev"
  }
}

// 正确
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev"
  }
}

# 错误 - 在 CI 中使用简写
- run: turbo build --affected

# 正确
- run: turbo run build --affected

根脚本绕过 Turbo

根 package.json 脚本必须委托到 turbo run，而不是直接运行任务。

// 错误 - 完全绕过 turbo
{
  "scripts": {
    "build": "bun build",
    "dev": "bun dev"
  }
}

// 正确 - 委托到 turbo
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev"
  }
}

使用 `&&` 链接 Turbo 任务

不要使用 && 链接 turbo 任务。让 turbo 编排。

// 错误 - turbo 任务未使用 turbo run
{
  "scripts": {
    "changeset:publish": "bun build && changeset publish"
  }
}

// 正确
{
  "scripts": {
    "changeset:publish": "turbo run build && changeset publish"
  }
}

`prebuild` 脚本手动构建依赖

像 prebuild 这样手动构建其他包的脚本会绕过 Turborepo 的依赖图。

// 错误 - 手动构建依赖
{
  "scripts": {
    "prebuild": "cd ../../packages/types && bun run build && cd ../utils && bun run build",
    "build": "next build"
  }
}

但是，修复取决于工作区依赖是否声明：

如果依赖已声明（例如 package.json 中的 "@repo/types": "workspace:*"），移除 prebuild 脚本。Turbo 的 dependsOn: ["^build"] 自动处理此问题。
如果依赖未声明，prebuild 存在是因为没有依赖关系时 ^build 不会触发。修复是：
- 添加依赖到 package.json："@repo/types": "workspace:*"
- 然后移除 prebuild 脚本

// 正确 - 声明依赖，让 turbo 处理构建顺序
// package.json
{
  "dependencies": {
    "@repo/types": "workspace:*",
    "@repo/utils": "workspace:*"
  },
  "scripts": {
    "build": "next build"
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

关键见解： ^build 只运行依赖包中的构建。没有依赖声明 = 没有自动构建顺序。

过度广泛的 `globalDependencies`

globalDependencies 影响所有包中的所有任务。要具体。

// 错误 - 重锤，影响所有哈希
{
  "globalDependencies": ["**/.env.*local"]
}

// 更好 - 移动到任务级别输入
{
  "globalDependencies": [".env"],
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**"]
    }
  }
}

重复任务配置

寻找跨任务可以合并的重复配置。Turborepo 支持共享配置模式。

// 错误 - 任务间重复 env 和 inputs
{
  "tasks": {
    "build": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"]
    },
    "test": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"]
    },
    "dev": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "cache": false,
      "persistent": true
    }
  }
}

// 更好 - 使用 globalEnv 和 globalDependencies 共享配置
{
  "globalEnv": ["API_URL", "DATABASE_URL"],
  "globalDependencies": [".env*"],
  "tasks": {
    "build": {},
    "test": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

何时使用全局 vs 任务级别：

globalEnv / globalDependencies - 影响所有任务，用于真正共享配置
任务级别 env / inputs - 当只有特定任务需要时使用

不是反模式：大的 `env` 数组

大的 env 数组（即使 50+ 变量）不是问题。它通常意味着用户彻底声明了构建的环境依赖。不要将此标记为问题。

使用 `--parallel` 标志

--parallel 标志绕过 Turborepo 的依赖图。如果任务需要并行执行，请正确配置 dependsOn。

# 错误 - 绕过依赖图
turbo run lint --parallel

# 正确 - 配置任务以允许并行执行
# 在 turbo.json 中，适当设置 dependsOn（或使用 transit nodes）
turbo run lint

在根 turbo.json 中的包特定任务覆盖

当多个包需要不同的任务配置时，使用包配置（每个包的 turbo.json），而不是在根 turbo.json 中用 package#task 覆盖使其混乱。

// 错误 - 根 turbo.json 有许多包特定覆盖
{
  "tasks": {
    "test": { "dependsOn": ["build"] },
    "@repo/web#test": { "outputs": ["coverage/**"] },
    "@repo/api#test": { "outputs": ["coverage/**"] },
    "@repo/utils#test": { "outputs": [] },
    "@repo/cli#test": { "outputs": [] },
    "@repo/core#test": { "outputs": [] }
  }
}

// 正确 - 使用包配置
// 根 turbo.json - 仅基础配置
{
  "tasks": {
    "test": { "dependsOn": ["build"] }
  }
}

// packages/web/turbo.json - 包特定覆盖
{
  "extends": ["//"],
  "tasks": {
    "test": { "outputs": ["coverage/**"] }
  }
}

// packages/api/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "test": { "outputs": ["coverage/**"] }
  }
}

包配置的好处：

保持配置接近其影响的代码
根 turbo.json 保持清洁并专注于基础模式
更容易理解每个包的特殊之处
与 $TURBO_EXTENDS$ 配合以继承 + 扩展数组

何时在根中使用 package#task：

单个包需要唯一依赖（例如 "deploy": { "dependsOn": ["web#build"] }）
迁移时的临时覆盖

查看 references/configuration/RULE.md#package-configurations 获取完整细节。

在 `inputs` 中使用 `../` 遍历出包

不要使用相对路径如 ../ 引用包外文件。使用 $TURBO_ROOT$ 替代。

// 错误 - 遍历出包
{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "../shared-config.json"]
    }
  }
}

// 正确 - 使用 $TURBO_ROOT$ 用于仓库根
{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/shared-config.json"]
    }
  }
}

缺少 `outputs` 用于文件生产任务

在标记缺失 outputs 之前，检查任务实际产生什么：

阅读包的脚本（例如 "build": "tsc", "test": "vitest"）
确定它是否写入磁盘文件或只输出到 stdout
只有当任务产生应被缓存的文件时标记

// 错误：构建产生文件但未缓存
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

// 正确：构建输出被缓存
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

常见输出按框架：

Next.js：[".next/**", "!.next/cache/**"]
Vite/Rollup：["dist/**"]
tsc：["dist/**"] 或自定义 outDir

TypeScript --noEmit 仍可能产生缓存文件：

当 tsconfig.json 中有 incremental: true 时，tsc --noEmit 即使不发出 JS 也会写 .tsbuildinfo 文件。在假设无输出前检查 tsconfig：

// 如果 tsconfig 有 incremental: true，tsc --noEmit 产生缓存文件
{
  "tasks": {
    "typecheck": {
      "outputs": ["node_modules/.cache/tsbuildinfo.json"] // 或 tsBuildInfoFile 指向的位置
    }
  }
}

为 TypeScript 任务确定正确输出：

检查 tsconfig 中是否启用 incremental 或 composite
检查 tsBuildInfoFile 的自定义缓存位置（默认：outDir 旁或项目根）
如果无增量模式，tsc --noEmit 不产生文件

`^build` vs `build` 混淆

{
  "tasks": {
    // ^build = 先在依赖中运行构建（其他包导入此包）
    "build": {
      "dependsOn": ["^build"]
    },
    // build（无 ^） = 先在相同包中运行构建
    "test": {
      "dependsOn": ["build"]
    },
    // pkg#task = 特定包的任务
    "deploy": {
      "dependsOn": ["web#build"]
    }
  }
}

环境变量未哈希

// 错误：API_URL 更改不会导致重建
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"]
    }
  }
}

// 正确：API_URL 更改使缓存无效
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "env": ["API_URL", "API_KEY"]
    }
  }
}

`.env` 文件不在输入中

Turbo 不加载 .env 文件 — 您的框架加载。但 Turbo 需要知道更改：

// 错误：.env 更改不使缓存无效
{
  "tasks": {
    "build": {
      "env": ["API_URL"]
    }
  }
}

// 正确：.env 文件更改使缓存无效
{
  "tasks": {
    "build": {
      "env": ["API_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.*"]
    }
  }
}

Monorepo 中的根 `.env` 文件

仓库根部的 .env 文件是反模式 — 即使对于小型 monorepo 或起始模板。它创建包间的隐式耦合，并模糊哪些包依赖哪些变量。

// 错误 - 根 .env 隐式影响所有包
my-monorepo/
├── .env              # 哪些包使用这个？
├── apps/
│   ├── web/
│   └── api/
└── packages/

// 正确 - .env 文件在需要它们的包中
my-monorepo/
├── apps/
│   ├── web/
│   │   └── .env      # 清楚：web 需要 DATABASE_URL
│   └── api/
│       └── .env      # 清楚：api 需要 API_KEY
└── packages/

根 .env 的问题：

模糊哪些包消费哪些变量
所有包获得所有变量（甚至它们不需要的）
缓存无效是粗粒度的（根 .env 更改使所有失效）
安全风险：包可能意外访问敏感变量，本意为其他包
坏习惯始于小 — 起始模板应建模正确模式

如果必须共享变量，使用 globalEnv 以明确什么是共享，并记录原因。

严格模式过滤 CI 变量

默认情况下，Turborepo 过滤环境变量到仅那些在 env/globalEnv 中的。CI 变量可能缺失：

// 如果 CI 脚本需要 GITHUB_TOKEN 但不在 env 中：
{
  "globalPassThroughEnv": ["GITHUB_TOKEN", "CI"],
  "tasks": { ... }
}

或使用 --env-mode=loose（不推荐用于生产）。

应用中的共享代码（应为包）

// 错误：共享代码在应用内
apps/
  web/
    shared/          # 这破坏 monorepo 原则！
      utils.ts

// 正确：提取到包
packages/
  utils/
    src/utils.ts

跨包边界访问文件

// 错误：进入另一个包内部
import { Button } from "../../packages/ui/src/button";

// 正确：正确安装和导入
import { Button } from "@repo/ui/button";

太多根依赖

// 错误：应用依赖在根中
{
  "dependencies": {
    "react": "^18",
    "next": "^14"
  }
}

// 正确：仅仓库工具在根中
{
  "devDependencies": {
    "turbo": "latest"
  }
}

常见任务配置

标准构建管道

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

如果任务需要并行执行有缓存无效，添加 transit 任务（见下）。

开发任务与 `^dev` 模式（用于 `turbo watch`）

具有 dependsOn: ["^dev"] 和 persistent: false 的 dev 任务在根 turbo.json 中可能看起来不寻常，但对于 turbo watch 工作流是正确的：

// 根 turbo.json
{
  "tasks": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false,
      "persistent": false  // 包有一键式开发脚本
    }
  }
}

// 包 turbo.json (apps/web/turbo.json)
{
  "extends": ["//"],
  "tasks": {
    "dev": {
      "persistent": true  // 应用运行长时间开发服务器
    }
  }
}

为什么这有效：

包（例如 @acme/db, @acme/validators）有 "dev": "tsc" — 一键式类型生成，快速完成
应用用 persistent: true 覆盖以运行实际开发服务器（Next.js 等）
turbo watch 在源文件更改时重新运行一键式包 dev 脚本，保持类型同步

预期用法： 运行 turbo watch dev（非 turbo run dev）。监视模式重新执行一键式任务，而保持持久任务运行。

替代模式： 使用单独的任务名称如 prepare 或 generate 用于一键式依赖构建，使意图更清晰：

{
  "tasks": {
    "prepare": {
      "dependsOn": ["^prepare"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "dependsOn": ["prepare"],
      "cache": false,
      "persistent": true
    }
  }
}

Transit Nodes 用于并行任务有缓存无效

某些任务可以并行运行（不需要依赖的构建输出）但当依赖源代码更改时必须使缓存无效。

dependsOn: ["^taskname"] 的问题：

强制顺序执行（慢）

dependsOn: []（无依赖）的问题：

允许并行执行（快）
但缓存不正确 — 更改依赖源代码不会使缓存无效

Transit Nodes 解决两者：

{
  "tasks": {
    "transit": { "dependsOn": ["^transit"] },
    "my-task": { "dependsOn": ["transit"] }
  }
}

transit 任务创建依赖关系而不匹配任何实际脚本，因此任务并行运行有正确缓存无效。

如何识别需要此模式的任务： 寻找读取依赖源文件但不需要其构建输出的任务。

与环境变量

{
  "globalEnv": ["NODE_ENV"],
  "globalDependencies": [".env"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["API_URL", "DATABASE_URL"]
    }
  }
}

参考索引

配置

文件	目的
configuration/RULE.md	turbo.json 概述，包配置
configuration/tasks.md	dependsOn, outputs, inputs, env, cache, persistent
configuration/global-options.md	globalEnv, globalDependencies, cacheDir, daemon, envMode
configuration/gotchas.md	常见配置错误

缓存

文件	目的
caching/RULE.md	缓存工作原理，哈希输入
caching/remote-cache.md	Vercel 远程缓存，自托管，登录/链接
caching/gotchas.md	调试缓存未命中，–summarize, --dry

环境变量

文件	目的
environment/RULE.md	env, globalEnv, passThroughEnv
environment/modes.md	严格 vs 松散模式，框架推断
environment/gotchas.md	.env 文件，CI 问题

过滤

文件	目的
filtering/RULE.md	–filter 语法概述
filtering/patterns.md	常见过滤器模式

CI/CD

文件	目的
ci/RULE.md	通用 CI 原则
ci/github-actions.md	完整 GitHub Actions 设置
ci/vercel.md	Vercel 部署，turbo-ignore
ci/patterns.md	–affected, 缓存策略

CLI

文件	目的
cli/RULE.md	turbo run 基础
cli/commands.md	turbo run 标志，turbo-ignore，其他命令

最佳实践

文件	目的
best-practices/RULE.md	Monorepo 最佳实践概述
best-practices/structure.md	仓库结构，工作区配置，TypeScript/ESLint 设置
best-practices/packages.md	创建内部包，JIT vs 编译，exports
best-practices/dependencies.md	依赖管理，安装，版本同步

监视模式

文件	目的
watch/RULE.md	turbo watch, interruptible tasks, dev workflows

边界（实验性）

文件	目的
boundaries/RULE.md	强制包隔离，基于标签的依赖规则

源文档

此技能基于 Turborepo 官方文档在：

源：Turborepo 仓库中的 docs/site/content/docs/
在线：https://turborepo.dev/docs