turborepo

Turborepo

当工作涉及 Turborepo 任务编排、缓存、单体仓库结构、筛选器／受影响范围 CI、prune／Docker、watch／dev 图，或迁移到 turbo 时，请使用此技能。

快照：[email protected]、[email protected]（2026-10-01）。如果版本不同，请从 source-map.md 更新。

工作流

1. 修改代码前，检查本地 Turborepo 环境：
   • turbo / create-turbo 的包版本（2.x 系列；快照版本为 2.11.6）。以下许多功能需要 2.10+（延迟哈希、缓存淘汰），或需要 2.11 版本（devEngines.packageManager、nub/aube、prune --production — 首次在 2.10.1–2.10.3 补丁版本中发布；原生 Rust/Python/Go 需要 2.11；任务标签需要 2.11.6）。
   • 根目录的 turbo.json / turbo.jsonc、包级 turbo.json、工作区 glob、锁文件、devEngines.packageManager / packageManager。
   • turbo 会调用的根目录和各包 package.json 脚本。
   • CI 远程缓存环境变量（TURBO_TOKEN、TURBO_TEAM）、prune/Docker 用法、--affected / 筛选器，以及根目录 turbo.json 中的 futureFlags。
2. 关于设置、日常运行、渐进式采用、基线和故障排除，请先遵循完整指南：usage-guide.md。
3. 如果版本与快照不同，或工作涉及缓存、环境变量哈希、prune 或 future flags，请更新并查阅当前官方文档。从 source-map.md 开始。
4. 深入了解相关内容：
   • 任务图、dependsOn/with、输入／输出、包配置：turbo-json-tasks.md。
   • turbo run、筛选器、--affected、watch、生成器：cli-filtering-watch.md。
   • 本地／远程缓存、淘汰、环境变量模式、框架推断：caching-env-remote.md。
   • CI 服务商、prune、Docker：ci-docker-prune.md。
   • 内部包、框架／工具图、边界、包管理器、Rust/Python/Go 工具链、迁移：packages-integrations.md。
5. 除非用户要求迁移，否则保留仓库现有的包管理器和脚本名称。
6. 使用范围最小且有用的 bunx turbo run …（--dry、--filter 或 --affected）进行验证。

核心判断

• Turborepo 用于编排已有的 package.json 脚本。它不是包管理器，也不能替代工作区。
• 在 CI 中优先使用 turbo run <tasks>（而不是直接运行 turbo build），以免将来 CLI 子命令与任务名称冲突。
• 为每个可缓存的构建任务声明 outputs。缺少 outputs → 缓存命中时不会恢复任何有用内容。
• 依赖项构建使用 "dependsOn": ["^build"]；同一包内的执行顺序使用 "dependsOn": ["build"]。不要混淆二者。
• 默认 envMode 为 strict。将会影响哈希的变量列在 env / globalEnv 中；仅当变量值不应导致缓存失效时才使用 passThroughEnv。
• 绝不递归：包脚本不得为 turbo 正在运行的同一任务再次调用 turbo run。
• 将 dev / 监视 / 服务设置为 "cache": false 和 "persistent": true。使用 "with" 并行运行相关的持久化任务。
• 优先使用 --cache=local:…,remote:…，而非已弃用的 --no-cache / --remote-only。
• 在实际使用依赖项的位置安装它们（而非提升到根目录），以提高缓存和 prune 的准确性。
• 使用传递节点（topo / transit）实现并行类型检查，优先于将 TypeScript Project References 与 Turbo 搭配使用。
• lint / 格式化工具（例如 Oxlint 和 Oxfmt）通常适合作为根任务 //#lint / //#format。
• 对上游任务（代码生成）写入的文件或依赖项输出（.d.ts），使用延迟 inputs 对象（{ "mode": "jit" } / { "mode": "dependencyOutputs" }），而非 cache: false。
• 使用 devEngines.packageManager 声明包管理器（2.10.1+，于 2.11 发布时宣布）。顶层 packageManager 仍可使用，但计划在未来的主版本中移除。
• 更改任何 futureFlags 条目都会使全局哈希失效（每个任务都会有一次缓存未命中）。仅在根目录的 turbo.json 中设置它们。
• 从 2.11.5 起，当 turbo 检测到编码 Agent 时，会在根目录的 AGENTS.md 中维护一个 Turborepo 管理区块（默认 agentGuidance: true）。预期会出现相应的 diff；如要选择退出，请在根目录设置 "agentGuidance": false。
• Rust（Cargo）、Python（uv）和 Go（go.work）工作区属于实验性 future flags——除非用户要求，否则不要在生产 CI 中启用。

验证

优先使用仓库自有命令。对于有实质影响的 Turborepo 工作，请覆盖相关子集：

• 使用 bunx turbo run <task> --dry=json 或 --graph，在执行耗时任务前验证 DAG。
• 先运行针对性的 bunx turbo run <task> --filter=<pkg>，再在符合 CI 场景时扩大到 --affected。
• 缓存正确性：更改输入 / 环境变量 → 预期未命中；保持不变 → 预期命中（哈希情况不明确时使用 --summarize）。
• 更改 TURBO_* 或 remoteCache 配置时，进行远程缓存冒烟测试。
• Prune / Docker：更改部署图时，运行 turbo prune <app> --docker，然后从 out/ 安装并构建。
• Watch / dev：确认长时间运行任务的 interruptible / with / persistent 行为。

报告已运行和未运行的检查，以及仍存在的 turbo 版本或远程缓存假设。