Back to Details

turborepo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Turborepo

Turborepo

Workflow

工作流程

  1. Confirm monorepo package boundaries and critical tasks.
  2. Define task graph dependencies (
    dependsOn
    ) by data flow, not habit.
  3. Set precise task inputs/outputs for cache correctness.
  4. Configure environment hashing and passthrough values intentionally.
  5. Enable and validate local and remote cache behavior.
  6. Harden CI execution strategy and change-based targeting.
  7. Monitor cache hit rate and task critical-path latency.
  1. 确认单体仓库的包边界和关键任务。
  2. 根据数据流而非习惯定义任务图依赖（
    dependsOn
    ）。
  3. 设置精确的任务输入/输出以确保缓存正确性。
  4. 有意配置环境变量哈希和透传值。
  5. 启用并验证本地和远程缓存行为。
  6. 强化CI执行策略和基于变更的目标定位。
  7. 监控缓存命中率和任务关键路径延迟。

Preflight (Ask / Check First)

预检（先询问/检查）

  • Turborepo version and package manager.
  • Build tools in use (Next.js, Vite, Jest, etc.).
  • CI provider and artifact/cache controls.
  • Environment variables affecting build output.
  • Existing cache miss or stale artifact incidents.
  • Turborepo版本和包管理器。
  • 当前使用的构建工具（Next.js、Vite、Jest等）。
  • CI提供商和制品/缓存控制机制。
  • 影响构建输出的环境变量。
  • 已发生的缓存未命中或过期制品事件。

Task Graph Design

任务图设计

  • Model dependencies explicitly with 
    ^task
    where upstream outputs matter.
  • Keep long-running dev tasks uncached.
  • Split large tasks into build/test/lint/typecheck for better reuse.
  • Avoid implicit cross-package side effects.
  • Keep task names consistent across packages.
  • 当上游输出至关重要时，使用
    ^task
    显式建模依赖。
  • 长期运行的开发任务不启用缓存。
  • 将大型任务拆分为构建/测试/lint/类型检查，以实现更好的复用。
  • 避免隐式的跨包副作用。
  • 保持各包之间的任务名称一致。

Example 
turbo.json

示例 
turbo.json

json
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**", "!.next/cache/**"] },
    "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] },
    "lint": {},
    "dev": { "cache": false }
  }
}
json
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**", "!.next/cache/**"] },
    "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] },
    "lint": {},
    "dev": { "cache": false }
  }
}

Cache Correctness Rules

缓存正确性规则

  • Declare outputs narrowly so stale files do not masquerade as hits.
  • Add non-default inputs when config files drive results.
  • Include environment variables that affect task output in 
    env
    .
  • Keep secrets out of cache keys unless required for correctness.
  • Validate cache correctness before enabling remote cache broadly.
  • 精确声明输出，防止过期文件被误判为缓存命中。
  • 当配置文件影响结果时，添加非默认输入。
  • 将影响任务输出的环境变量纳入
    env
    配置。
  • 除非正确性要求，否则不要将密钥纳入缓存键。
  • 在广泛启用远程缓存之前，先验证缓存正确性。

Environment and Global Dependencies

环境与全局依赖

  • Use 
    globalDependencies
    for root configs that impact many tasks.
  • Use 
    globalEnv
    only for variables with broad task impact.
  • Use task 
    inputs
    for 
    .env
    files; do not rely on removed 
    dotEnv
    /
    globalDotEnv
    keys.
  • Keep per-task env lists minimal and explicit.
  • Avoid broad wildcard env strategies that over-invalidate cache.
  • 对影响多个任务的根配置使用
    globalDependencies
    。
  • 仅对影响广泛任务的变量使用
    globalEnv
    。
  • 对
    .env
    文件使用任务
    inputs
    ；不要依赖已移除的
    dotEnv
    /
    globalDotEnv
    键。
  • 保持每个任务的环境变量列表最小化且明确。
  • 避免使用宽泛的通配符环境变量策略，以免过度使缓存失效。

CI Strategy

CI策略

  • Use change-aware filters to limit execution scope.
  • Fail fast on cache/config mismatch signals.
  • Export remote cache credentials securely via CI secrets.
  • Ensure cold-start path remains acceptable when cache is unavailable.
  • Record task timings and hit rates for regression analysis.
  • For Turborepo 2.x+, use 
    tasks
    instead of 
    pipeline
    , expect cache at 
    .turbo/cache
    , and replace 
    outputMode
    with 
    outputLogs
    during upgrades.
  • 使用感知变更的过滤器来限制执行范围。
  • 当出现缓存/配置不匹配信号时快速失败。
  • 通过CI密钥安全导出远程缓存凭证。
  • 确保缓存不可用时，冷启动路径仍可接受。
  • 记录任务耗时和命中率以进行回归分析。
  • 对于Turborepo 2.x+版本，使用
    tasks
    替代
    pipeline
    ，缓存存储在
    .turbo/cache
    ，升级时用
    outputLogs
    替换
    outputMode
    。

Typical Commands

常用命令

bash
pnpm turbo run build test lint
pnpm turbo run build --filter=...[origin/main]
pnpm turbo run test --filter=./packages/api...
pnpm turbo run build --summarize
bash
pnpm turbo run build test lint
pnpm turbo run build --filter=...[origin/main]
pnpm turbo run test --filter=./packages/api...
pnpm turbo run build --summarize

Security and Operations

安全与运维

  • Treat remote cache as shared infrastructure with access controls.
  • Scope cache tokens to minimal required permissions.
  • Rotate cache credentials and audit usage patterns.
  • Keep rollback path for cache incidents documented.
  • 将远程缓存视为带有访问控制的共享基础设施。
  • 将缓存令牌的权限范围限制为最小必要权限。
  • 轮换缓存凭证并审计使用模式。
  • 记录缓存事件的回滚路径。

Validation Commands

验证命令

bash
pnpm turbo run build
pnpm turbo run test
pnpm turbo run lint
pnpm turbo run build --filter=...[origin/main]
bash
pnpm turbo run build
pnpm turbo run test
pnpm turbo run lint
pnpm turbo run build --filter=...[origin/main]

Common Failure Modes

常见故障模式

  • Missing outputs causing false cache hits.
  • Overly broad env hashing causing cache thrash.
  • Hidden dependency edges not captured in 
    dependsOn
    .
  • Caching non-deterministic tasks.
  • CI using different toolchain versions than local.
  • 输出缺失导致虚假缓存命中。
  • 过于宽泛的环境变量哈希导致缓存频繁失效。
  • 未被
    dependsOn
    捕获的隐藏依赖关系。
  • 对非确定性任务启用缓存。
  • CI使用与本地不同的工具链版本。

Definition of Done

完成标准

  • Task graph reflects real dependency flow.
  • Cache hits are correct and reproducible.
  • CI and local runs use aligned toolchains.
  • Remote cache is secure, observable, and recoverable.
  • Critical-path timing and hit-rate baselines are documented.
  • 任务图反映真实的依赖流。
  • 缓存命中是正确且可复现的。
  • CI和本地运行使用一致的工具链。
  • 远程缓存安全、可观测且可恢复。
  • 关键路径耗时和命中率基线已记录。

References

参考资料

  • references/turborepo-2026-02-18.md
  • references/turborepo-2026-02-18.md

Reference Index

参考索引

  • rg -n "tasks|dependsOn|outputs" references/turborepo-2026-02-18.md
  • rg -n "inputs|env|globalDependencies" references/turborepo-2026-02-18.md
  • rg -n "remote cache|CI|filter" references/turborepo-2026-02-18.md
  • rg -n "failure modes|debug" references/turborepo-2026-02-18.md
  • rg -n "tasks|dependsOn|outputs" references/turborepo-2026-02-18.md
  • rg -n "inputs|env|globalDependencies" references/turborepo-2026-02-18.md
  • rg -n "remote cache|CI|filter" references/turborepo-2026-02-18.md
  • rg -n "failure modes|debug" references/turborepo-2026-02-18.md