turborepo

Turborepo 技能

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

重要：使用包任务，而不是根任务

优先使用包任务，而不是根任务。

创建任务/脚本/流水线时，必须默认使用包任务：

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）仅适用于确实无法放在包中的任务，例如 Vitest Projects 的 //#test、整个代码仓库范围内的发布脚本，或自身不会调用 turbo 的工具。

次要规则：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. 判断它是否会将文件写入磁盘，还是只将内容输出到 stdout
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/**", "!.next/dev/**"]
• 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.*"]
    }
  }
}

单体仓库根目录中的 .env 文件

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

// 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-9-19-canary-9.turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "!.next/dev/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

如果有需要并行执行并使缓存失效的任务，请添加 transit 任务（见下文）。

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

在根 turbo.json 中，一个带有 dependsOn: ["^dev"] 和 persistent: false 的 dev 任务可能看起来不寻常，但对于 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 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"]
    }
  }
}

使用 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 key、futureFlags、cacheDir、envMode
configuration/gotchas.md	常见配置错误

缓存

文件	用途
caching/RULE.md	缓存如何工作、哈希输入
caching/remote-cache.md	Vercel Remote Cache、可自托管、login/link
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