turborepo

Turborepo 技能

用于 JavaScript/TypeScript 单体仓库的构建系统。Turborepo 会缓存任务输出，并根据依赖关系图并行运行任务。

更改 Turbo 配置或命令之前，请从仓库根目录阅读 node_modules/turbo/docs/README.md，并遵循相关页面中的说明。这些已安装的文档与当前运行的版本一致；有关受支持的选项和默认值，请优先参考这些文档，而非本技能中附带的参考资料。

重要：创建包任务，而非根任务

不要创建根任务。始终创建包任务。

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

1. 将脚本添加到每个相关包的 package.json
2. 在根目录的 turbo.json 中注册任务
3. 根目录的 package.json 只通过 turbo run <task> 委派任务

不要在根目录的 package.json 中编写任务逻辑。这会破坏 Turborepo 的并行执行能力。

// DO THIS: Scripts in each package
// 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 - register tasks
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "lint": {},
    "test": { "dependsOn": ["build"] }
  }
}

// Root package.json - ONLY delegates, no task logic
{
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test"
  }
}

// DO NOT DO THIS - defeats parallelization
// Root package.json
{
  "scripts": {
    "build": "cd apps/web && next build && cd ../api && tsc",
    "lint": "eslint apps/ packages/",
    "test": "vitest"
  }
}

根任务（//#taskname）仅用于确实无法放在包中的任务（很少见）。

次要规则：turbo run 与 turbo

命令写入代码时，始终使用 turbo run：

// package.json - ALWAYS "turbo run"
{
  "scripts": {
    "build": "turbo run build"
  }
}

# CI workflows - ALWAYS "turbo run"
- run: turbo run build --affected

简写 turbo <tasks> 仅用于人类或 Agent 直接输入的一次性终端命令。不要在 package.json、CI 或脚本中写入 turbo build。

快速决策树

“我需要配置任务”

Configure a task?
├─ Define task dependencies → references/configuration/tasks.md
├─ Lint/check-types (parallel + caching) → Use Transit Nodes pattern (see below)
├─ Specify build outputs → references/configuration/tasks.md#outputs
├─ Handle environment variables → references/environment/RULE.md
├─ Set up dev/watch tasks → references/configuration/tasks.md#persistent
├─ Package-specific config → references/configuration/RULE.md#package-configurations
└─ Global settings (cacheDir, daemon) → references/configuration/global-options.md

“我的缓存无法正常工作”

Cache problems?
├─ Tasks run but outputs not restored → Missing `outputs` key
├─ Cache misses unexpectedly → references/caching/gotchas.md
├─ Need to debug hash inputs → Use --summarize or --dry
├─ Want to skip cache entirely → Use --force or cache: false
├─ Remote cache not working → references/caching/remote-cache.md
└─ Environment causing misses → references/environment/gotchas.md

“我只想运行有更改的包”

Run only what changed?
├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected
├─ Custom base branch → --affected --affected-base=origin/develop
├─ Manual git comparison → --filter=...[origin/main]
└─ See all filter options → references/filtering/RULE.md

**--affected 是仅运行有更改的包的主要方式。**它会自动与默认分支进行比较，并包含依赖这些包的其他包。

“我想筛选包”

Filter packages?
├─ Only changed packages → --affected (see above)
├─ By package name → --filter=web
├─ By directory → --filter=./apps/*
├─ Package + dependencies → --filter=web...
├─ Package + dependents → --filter=...web
└─ Complex combinations → references/filtering/patterns.md

“环境变量无法正常工作”

Environment issues?
├─ Vars not available at runtime → Strict mode filtering (default)
├─ Cache hits with wrong env → Var not in `env` key
├─ .env changes not causing rebuilds → .env not in `inputs`
├─ CI variables missing → references/environment/gotchas.md
└─ Framework vars (NEXT_PUBLIC_*) → Auto-included via inference

“我需要设置 CI”

CI setup?
├─ GitHub Actions → references/ci/github-actions.md
├─ Vercel deployment → references/ci/vercel.md
├─ Remote cache in CI → references/caching/remote-cache.md
├─ Only build changed packages → --affected flag
├─ Skip unnecessary builds → turbo-ignore (references/cli/commands.md)
└─ Skip container setup when no changes → turbo-ignore

“我想在开发期间监听更改”

Watch mode?
├─ Re-run tasks on change → turbo watch (references/watch/RULE.md)
├─ Dev servers with dependencies → Use `with` key (references/configuration/tasks.md#with)
├─ Restart dev server on dep change → Use `interruptible: true`
└─ Persistent dev tasks → Use `persistent: true`

“我需要创建/组织一个包”

Package creation/structure?
├─ Create an internal package → references/best-practices/packages.md
├─ Repository structure → references/best-practices/structure.md
├─ Dependency management → references/best-practices/dependencies.md
├─ Best practices overview → references/best-practices/RULE.md
├─ JIT vs Compiled packages → references/best-practices/packages.md#compilation-strategies
└─ Sharing code between apps → references/best-practices/RULE.md#package-types

“我的单体仓库应该如何组织？”

Monorepo structure?
├─ Standard layout (apps/, packages/) → references/best-practices/RULE.md
├─ Package types (apps vs libraries) → references/best-practices/RULE.md#package-types
├─ Creating internal packages → references/best-practices/packages.md
├─ TypeScript configuration → references/best-practices/structure.md#typescript-configuration
├─ ESLint configuration → references/best-practices/structure.md#eslint-configuration
├─ Dependency management → references/best-practices/dependencies.md
└─ Enforce package boundaries → references/boundaries/RULE.md

“我想强制执行架构边界”

Enforce boundaries?
├─ Check for violations → turbo boundaries
├─ Tag packages → references/boundaries/RULE.md#tags
├─ Restrict which packages can import others → references/boundaries/RULE.md#rule-types
└─ Prevent cross-package file imports → references/boundaries/RULE.md

关键反模式

在代码中使用 turbo 简写

**建议在 package.json 脚本和 CI 管道中使用 turbo run。**简写 turbo <task> 用于交互式终端操作。

// WRONG - using shorthand in package.json
{
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev"
  }
}

// CORRECT
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev"
  }
}

# WRONG - using shorthand in CI
- run: turbo build --affected

# CORRECT
- run: turbo run build --affected

根脚本绕过 Turbo

根目录的 package.json 脚本必须委派给 turbo run，而不是直接运行任务。

// WRONG - bypasses turbo entirely
{
  "scripts": {
    "build": "bun build",
    "dev": "bun dev"
  }
}

// CORRECT - delegates to turbo
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev"
  }
}

使用 && 串联 Turbo 任务

不要使用 && 串联 Turbo 任务。让 Turbo 负责编排。

// WRONG - turbo task not using turbo run
{
  "scripts": {
    "changeset:publish": "bun build && changeset publish"
  }
}

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

手动构建依赖项的 prebuild 脚本

prebuild 等手动构建其他包的脚本会绕过 Turborepo 的依赖关系图。

// WRONG - manually building dependencies
{
  "scripts": {
    "prebuild": "cd ../../packages/types && bun run build && cd ../utils && bun run build",
    "build": "next build"
  }
}

不过，具体修复方式取决于是否已声明工作区依赖项：

1. 如果已声明依赖项（例如，package.json 中的 "@repo/types": "workspace:*"），请移除 prebuild 脚本。Turbo 的 dependsOn: ["^build"] 会自动处理。

2. 如果未声明依赖项，则需要 prebuild，因为没有依赖关系时不会触发 ^build。修复方法：

   • 在 package.json 中添加依赖项："@repo/types": "workspace:*"
   • 然后移除 prebuild 脚本

// CORRECT - declare dependency, let turbo handle build order
// package.json
{
  "dependencies": {
    "@repo/types": "workspace:*",
    "@repo/utils": "workspace:*"
  },
  "scripts": {
    "build": "next build"
  }
}

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

关键要点：^build 只会在列为依赖项的包中运行 build。未声明依赖项 = 不会自动确定构建顺序。

过于宽泛的 globalDependencies

globalDependencies 会通过全局哈希影响所有包中的所有任务——即使在 inputs 中使用否定 glob，任务也无法排除特定文件。请精确指定。

// WRONG - heavy hammer, affects all hashes
{
  "globalDependencies": ["**/.env.*local"]
}

// BETTER - move to task-level inputs
{
  "globalDependencies": [".env"],
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**"]
    }
  }
}

使用 futureFlags.globalConfiguration 后，此问题会有所缓解，因为 global.inputs 中的文件会合并到每个任务的输入中（而不是全局哈希中）。任务可以排除特定文件：

// BEST - global.inputs with per-task exclusion
{
  "futureFlags": { "globalConfiguration": true },
  "global": {
    "inputs": [".env"]
  },
  "tasks": {
    "build": { "outputs": ["dist/**"] },
    "lint": {
      "inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/.env"]
    }
  }
}

重复的任务配置

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

// WRONG - repetitive env and inputs across tasks
{
  "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
    }
  }
}

// BETTER - use globalEnv and globalDependencies for shared config
{
  "globalEnv": ["API_URL", "DATABASE_URL"],
  "globalDependencies": [".env*"],
  "tasks": {
    "build": {},
    "test": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

何时使用全局配置与任务级配置：

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

并非反模式：大型 env 数组

大型 env 数组（即使包含 50 多个变量）也不是问题。这通常说明用户认真声明了构建所依赖的环境变量。不要将其标记为问题。

使用 --parallel 标志

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

# WRONG - bypasses dependency graph
turbo run lint --parallel

# CORRECT - configure tasks to allow parallel execution
# In turbo.json, set dependsOn appropriately (or use transit nodes)
turbo run lint

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

当多个包需要不同的任务配置时，应使用包配置（每个包中的 turbo.json），而不是在根目录 turbo.json 中堆积 package#task 覆盖项。

// WRONG - root turbo.json with many package-specific overrides
{
  "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": [] }
  }
}

// CORRECT - use Package Configurations
// Root turbo.json - base config only
{
  "tasks": {
    "test": { "dependsOn": ["build"] }
  }
}

// packages/web/turbo.json - package-specific override
{
  "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$。

// WRONG - traversing out of package
{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "../shared-config.json"]
    }
  }
}

// CORRECT - use $TURBO_ROOT$ for repo root
{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/shared-config.json"]
    }
  }
}

生成文件的任务缺少 outputs

标记缺少 outputs 之前，请先检查任务实际生成的内容：

1. 阅读包的脚本（例如，"build": "tsc"、"test": "vitest"）
2. 确定它是否会将文件写入磁盘，还是只输出到标准输出
3. 仅当任务生成了应缓存的文件时才标记

// WRONG: build produces files but they're not cached
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

// CORRECT: build outputs are cached
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

各框架的常见输出：

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

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

当 tsconfig.json 中的 incremental: true 时，即使不生成 JS，tsc --noEmit 也会写入 .tsbuildinfo 文件。不要贸然认定没有输出，请先检查 tsconfig：

// If tsconfig has incremental: true, tsc --noEmit produces cache files
{
  "tasks": {
    "typecheck": {
      "outputs": ["node_modules/.cache/tsbuildinfo.json"] // or wherever tsBuildInfoFile points
    }
  }
}

确定 TypeScript 任务的正确输出：

1. 检查 tsconfig 中是否启用了 incremental 或 composite
2. 检查 tsBuildInfoFile 是否指定了自定义缓存位置（默认：与 outDir 同级，或位于项目根目录）
3. 如果未启用增量模式，tsc --noEmit 不会生成文件

混淆 ^build 与 build

{
  "tasks": {
    // ^build = run build in DEPENDENCIES first (other packages this one imports)
    "build": {
      "dependsOn": ["^build"]
    },
    // build (no ^) = run build in SAME PACKAGE first
    "test": {
      "dependsOn": ["build"]
    },
    // pkg#task = specific package's task
    "deploy": {
      "dependsOn": ["web#build"]
    }
  }
}

环境变量未纳入哈希计算

// WRONG: API_URL changes won't cause rebuilds
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"]
    }
  }
}

// CORRECT: API_URL changes invalidate cache
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "env": ["API_URL", "API_KEY"]
    }
  }
}

.env 文件未列入 inputs

Turbo 不会加载 .env 文件，负责加载的是你的框架。但 Turbo 需要知道这些文件的变更：

// WRONG: .env changes don't invalidate cache
{
  "tasks": {
    "build": {
      "env": ["API_URL"]
    }
  }
}

// CORRECT: .env file changes invalidate cache
{
  "tasks": {
    "build": {
      "env": ["API_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.*"]
    }
  }
}

Monorepo 根目录中的 .env 文件

仓库根目录中的 .env 文件是一种反模式，即使是小型 monorepo 或入门模板也不例外。它会造成包之间的隐式耦合，也让人难以判断哪些包依赖哪些变量。

// WRONG - root .env affects all packages implicitly
my-monorepo/
├── .env              # Which packages use this?
├── apps/
│   ├── web/
│   └── api/
└── packages/

// CORRECT - .env files in packages that need them
my-monorepo/
├── apps/
│   ├── web/
│   │   └── .env      # Clear: web needs DATABASE_URL
│   └── api/
│       └── .env      # Clear: api needs API_KEY
└── packages/

根目录 .env 的问题：

• 不清楚哪些包会使用哪些变量
• 所有包都会获得所有变量（包括用不到的变量）
• 缓存失效粒度过粗（根目录 .env 变更会使所有内容失效）
• 安全风险：包可能会意外访问原本供其他包使用的敏感变量
• 不良习惯会从小处开始——入门模板应示范正确模式

如果必须共享变量，请使用 globalEnv 明确声明共享的内容，并说明原因。

严格模式会过滤 CI 变量

默认情况下，Turborepo 只保留 env / globalEnv 中声明的环境变量。CI 变量可能因此缺失：

// If CI scripts need GITHUB_TOKEN but it's not in env:
{
  "globalPassThroughEnv": ["GITHUB_TOKEN", "CI"],
  "tasks": { ... }
}

也可以使用 --env-mode=loose（不建议用于生产环境）。

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

// WRONG: Shared code inside an app
apps/
  web/
    shared/          # This breaks monorepo principles!
      utils.ts

// CORRECT: Extract to a package
packages/
  utils/
    src/utils.ts

跨包访问文件

// WRONG: Reaching into another package's internals
import { Button } from "../../packages/ui/src/button";

// CORRECT: Install and import properly
import { Button } from "@repo/ui/button";

根依赖过多

// WRONG: App dependencies in root
{
  "dependencies": {
    "react": "^18",
    "next": "^14"
  }
}

// CORRECT: Only repo tools in root
{
  "devDependencies": {
    "turbo": "latest"
  }
}

常见任务配置

标准构建流水线

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

如果有需要并行执行且要在缓存失效时重新运行的任务，请添加 transit 任务（见下文）。

使用 ^dev 模式的 Dev 任务（用于 turbo watch）

根目录的 turbo.json 中，dev 任务使用 dependsOn: ["^dev"] 和 persistent: false 可能看起来不太寻常，但对于 turbo watch 工作流来说，这是正确的配置：

// Root turbo.json
{
  "tasks": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false,
      "persistent": false  // Packages have one-shot dev scripts
    }
  }
}

// Package turbo.json (apps/web/turbo.json)
{
  "extends": ["//"],
  "tasks": {
    "dev": {
      "persistent": true  // Apps run long-running dev servers
    }
  }
}

这样配置的原因：

• 包（例如 @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 节点

有些任务可以并行运行（不需要依赖项的构建产物），但依赖项源代码变更时必须使缓存失效。

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

• 强制串行执行（速度慢）

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

• 允许并行执行（速度快）
• 但缓存不正确——依赖项源代码变更不会使缓存失效

Transit 节点可以同时解决这两个问题：

{
  "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"]
    }
  }
}

使用 futureFlags.globalConfiguration 时，相同的配置会将全局设置移至 global 下，而 .env 会成为每个任务的输入，而非全局哈希输入：

{
  "futureFlags": { "globalConfiguration": true },
  "global": {
    "env": ["NODE_ENV"],
    "inputs": [".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、global 键、futureFlags、cacheDir、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	严格模式与宽松模式、框架推断
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/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 与编译产物、导出
best-practices/dependencies.md	依赖管理、安装、版本同步

监听模式

文件	用途
watch/RULE.md	turbo watch、可中断任务、开发工作流

边界（实验性）

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

源文档

本技能基于 Turborepo 官方文档：

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