turborepo

Turborepo

概述

用于 JavaScript/TypeScript 单体仓库的构建系统。缓存任务输出，并根据依赖关系图并行运行任务。始终创建包级任务（而非根任务），在脚本中使用 turbo run，并让 dependsOn 管理执行顺序。配置使用 turbo.json（或支持注释的 turbo.jsonc）。

适用场景： 单体仓库任务编排、构建缓存、CI 优化、工作区依赖管理、包边界强制执行。

不适用场景： 单包项目、非 JavaScript 单体仓库、没有构建步骤的项目。

快速参考

模式	语法	要点
Schema	"$schema": "https://turborepo.dev/schema.json"	始终在 turbo.json 中包含
依赖构建	"dependsOn": ["^build"]	先构建依赖项
同包任务	"dependsOn": ["codegen"]	先在同一包中运行
指定包	"dependsOn": ["pkg#task"]	指定包的任务
并行 lint/typecheck	Transit Nodes 模式	缓存失效，但不按顺序执行
开发服务器	"persistent": true, "cache": false	长时间运行，无法缓存
Sidecar 任务	"with": ["api#dev"]	并行运行其他任务
监视模式	turbo watch dev	文件变更时重新运行
按包筛选	--filter=web	单个包
连同依赖项一起筛选	--filter=web...	包及其依赖项
已变更的包	--affected	已变更的包及其依赖项
调试缓存	--summarize 或 --dry	查看哈希输入
包配置	turbo.json，其中包含 "extends": ["//"]	按包覆盖配置
可组合配置	"extends": ["@repo/config"]	从任意工作区包扩展
扩展数组	数组中的 "$TURBO_EXTENDS$"	追加到继承的配置，而非替换
哈希中的环境变量	"env": ["API_URL"]	变更时使缓存失效
边界	turbo boundaries	强制执行包隔离和导入规则
查询关系图	turbo query	用于查询包和任务关系图的 GraphQL 接口
代码生成	turbo generate	搭建新包和组件的初始结构
列出包	turbo ls	列出单体仓库中的所有包
开发工具	turbo devtools	可视化包关系图和任务关系图的浏览器
Docker 精简工作区	turbo prune <pkg> --docker	用于容器构建的最小单体仓库切片

决策树

配置任务

Configure a task?
+-- Define task dependencies       -> dependsOn in turbo.json
+-- Lint/check-types (parallel)    -> Transit Nodes pattern
+-- Specify build outputs          -> outputs key
+-- Handle environment variables   -> env key or globalEnv
+-- Dev/watch tasks                -> persistent: true, cache: false
+-- Sidecar tasks (run alongside)  -> with key
+-- Package-specific config        -> Package turbo.json with extends: ["//"]
+-- Composable config              -> extends from any workspace package
+-- Global settings                -> globalEnv, globalDependencies, cacheDir

缓存问题

Cache problems?
+-- Outputs not restored           -> Missing outputs key
+-- Unexpected cache misses        -> Use --summarize or --dry to debug
+-- Skip cache entirely            -> --force or cache: false
+-- Remote cache not working       -> Check turbo login/link
+-- Environment causing misses     -> Var not in env key

筛选包

Filter packages?
+-- By package name                -> --filter=web
+-- By directory                   -> --filter=./apps/*
+-- Package + dependencies         -> --filter=web...
+-- Package + dependents           -> --filter=...web
+-- Changed + dependents           -> --affected

探索仓库

Explore repository?
+-- List all packages              -> turbo ls
+-- Query dependency graph         -> turbo query
+-- Visualize graphs               -> turbo devtools
+-- Check boundary violations      -> turbo boundaries
+-- Generate new package           -> turbo generate workspace
+-- Run custom generator           -> turbo generate run [name]

常见错误

错误	正确做法
将构建逻辑放在根目录的 package.json 脚本中，而不是各个包中	在每个包中定义脚本，并在根目录中使用 turbo run 进行委派
使用 ^build，但未声明 workspace:* 依赖	先在 package.json 中添加依赖；^build 只会对已声明的依赖触发
在包脚本中使用 && 串联 turbo 任务	在 turbo.json 中使用 dependsOn 声明任务顺序
未将环境变量添加到 turbo.json 的 env 键中	在 env 中声明所有会影响构建的环境变量，确保缓存哈希正确
使用 --parallel 标志绕过依赖顺序	正确配置 dependsOn，或使用中间节点执行并行任务，同时确保缓存失效处理正确
使用过时的 schema URL	在 $schema 字段中使用 https://turborepo.dev/schema.json
在包配置中覆盖继承的数组	在数组中使用 $TURBO_EXTENDS$ 进行追加，而不是替换
在根目录的 turbo.json 中定义属于特定包的任务	在包自己的 turbo.json 中定义任务，并设置 extends: ["//"]
在脚本或 CI 中使用 turbo <task> 简写	在 package.json 脚本和 CI 流水线中使用 turbo run <task>；简写仅用于交互式操作

委派

• 探索 Monorepo 结构：使用 Explore Agent 发现各个包、工作区布局和依赖关系
• 流水线配置与优化：使用 Task Agent 设置 turbo.json 任务、配置缓存并排查缓存未命中问题
• Monorepo 架构规划：使用 Plan Agent 设计包边界、共享库和 CI 优化策略

如果有 pnpm-workspace 技能，请将工作区设置、依赖链接、目录和 pnpm deploy 委派给它。 如果有 changesets 技能，请将版本管理、变更日志生成和 npm 发布委派给它。

参考资料

• 任务配置与 dependsOn 模式
• 缓存、输出和缓存问题调试
• 筛选、受影响的包和 CI 模式
• 工作区结构与包管理
• 环境变量与模式
• 监视模式、开发任务与反模式
• 边界、查询与代码生成