turborepo

用途

Turborepo 是针对 JavaScript/TypeScript monorepo 的构建系统。它会缓存任务输出，并基于依赖图并行运行任务。本技能提供 Turborepo 的使用与配置指导，触发场景包括：turbo.json、任务管道、dependsOn、缓存、远程缓存、turbo CLI、--filter、--affected、CI 等。

核心原则：包任务，而非根任务

不要创建根任务，始终创建包任务。创建任务/脚本/管道时必须：

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

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

主要能力

任务配置

在 turbo.json 的 tasks 中注册任务，可指定依赖与输出，例如：

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

根任务（//#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> 仅用于人类或代理直接在终端输入的一次性命令。

依赖关键字

• ^build：先在依赖包中运行 build
• build（无 ^）：先在本包中运行 build
• pkg#task：指定某个包的任务

缓存与环境变量

• 任务产生文件时需声明 outputs 才能被缓存，例如 Next.js 用 [".next/**", "!.next/cache/**"]，Vite/Rollup 用 ["dist/**"]。
• TypeScript：若 tsconfig 启用 incremental，tsc --noEmit 仍会写入 .tsbuildinfo 缓存文件，需据此设置 outputs。
• 环境变量需写入 env 才会影响缓存哈希：未声明时变量变化不会触发重建。
• Turbo 不加载 .env 文件（由框架加载），但需将 .env 加入 inputs 才能使文件变化使缓存失效。
• 环境问题可查 references/environment/gotchas.md。

只运行变更的包

主要方式是 turbo run build --affected，它会自动与默认分支比较并包含依赖方。也可自定义基线分支 --affected --affected-base=origin/develop，或手动 git 比较 --filter=...[origin/main]。

过滤

• 按包名：--filter=web
• 按目录：--filter=./apps/*
• 包及其依赖：--filter=web...
• 包及其依赖方：--filter=...web

监听模式

• 变更后重新运行任务：turbo watch
• 带依赖的 dev server：使用 with 键
• 依赖变化时重启 dev server：interruptible: true
• 持久化 dev 任务：persistent: true

CI

支持 GitHub Actions、Vercel 部署、CI 中远程缓存、--affected 只构建变更包，以及用 turbo-ignore 跳过不必要的构建。

仓库结构与包管理

覆盖标准布局（apps/、packages/）、包类型（应用 vs 库）、创建内部包、TypeScript/ESLint 配置、依赖管理、JIT 与编译型包策略。

架构边界

用 turbo boundaries 检查违规，通过 tags 标记包，限制哪些包可导入其他包，防止跨包文件导入。

常见反模式

• 在 package.json 或 CI 中使用 turbo 简写而非 turbo run
• 根脚本绕过 turbo 直接运行任务
• 用 && 串联 turbo 任务，而非让 turbo 编排
• prebuild 脚本手动构建依赖：若依赖已在 package.json 声明，删除 prebuild，由 dependsOn: ["^build"] 处理；若未声明，先添加 "@repo/types": "workspace:*" 再删除
• 过度宽泛的 globalDependencies：应移入任务级 inputs
• 重复的任务配置：用 globalEnv / globalDependencies 共享
• 使用 --parallel 绕过依赖图：应正确配置 dependsOn
• 在根 turbo.json 堆叠包级覆盖：应使用每个包的 turbo.json（Package Configurations）
• 在 inputs 中用 ../ 越出包：应使用 $TURBO_ROOT$
• 遗漏 outputs 或 env 导致缓存失效

说明

大量 env 数组（甚至 50+ 变量）不是问题，通常表示用户完整声明了构建的环境依赖，不应标记为缺陷。

限制

本资料为 Turborepo 技能的使用指导内容，未提供具体产品功能清单、收费与价格、平台支持范围、性能数据或官方基准；这些信息暂未提供。