配置 turbo.json

通过在你的 Workspace 根目录下使用 turbo.json 文件来配置 turbo 的行为。你也可以

• 使用 包配置 来进行更精细的控制。
• 使用 turbo.jsonc 在你的配置中添加注释，并获得 IDE 支持。

全局选项

extends

{
  "extends": ["//"]
}

从根目录的 turbo.json 扩展，使用 包配置 为包创建特定的配置。

• extends 的唯一有效值是 ["//"]，用于从根目录的 turbo.json 继承配置。
• 如果在根目录的 turbo.json 中使用 extends，它将被忽略。

globalDependencies

{
  "globalDependencies": [".env", "tsconfig.json"]
}

你希望包含在所有任务哈希中的 glob 列表。 如果任何匹配这些 glob 的文件发生更改，所有任务都将错过缓存。 Glob 相对于 turbo.json 的位置。

默认情况下，Workspace 根目录中源代码控制中的所有文件都包含在全局哈希中。

globalEnv

{
  "globalEnv": ["GITHUB_TOKEN", "PACKAGE_VERSION", "NODE_ENV"]
}

你希望影响所有任务哈希的环境变量列表。 对这些环境变量的任何更改都将导致所有任务错过缓存。

有关通配符和否定语法的更多信息，请参阅 env 部分。

globalPassThroughEnv

{
  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
}

你希望提供给任务的环境变量列表。 使用此键会将所有任务选择加入 严格环境变量模式。

此外，Turborepo 具有一组内置的全局传递变量，用于常见情况，例如操作系统环境变量。 这包括诸如 HOME、PATH、APPDATA、SHELL、PWD 等变量。 完整的列表可以在 源代码 中找到。

ui

默认值："stream"

为仓库选择终端 UI。

"tui" 允许一次查看每个日志并与任务交互。 "stream" 按日志到达的顺序输出日志，并且不可交互。

{
  "ui": "tui" | "stream"
}

dangerouslyDisablePackageManagerCheck

默认值：false

Turborepo 使用仓库的 lockfile 来确定缓存行为、包图 等。 因此，我们使用 packageManager 字段 来帮助你稳定你的 Turborepo。

为了帮助增量迁移或在你无法使用 packageManager 字段的情况下，你可以使用 --dangerously-disable-package-manager-check 来选择退出此检查，并承担不稳定的 lockfile 产生不可预测行为的风险。 禁用后，Turborepo 将尝试尽最大努力发现仓库的预期包管理器。

{
  "dangerouslyDisablePackageManagerCheck": true
}

cacheDir

默认值：".turbo/cache"

指定文件系统缓存目录。

{
  "cacheDir": ".turbo/cache"
}

daemon

默认值：true

Turborepo 运行一个后台进程来预先计算一些开销大的操作。 此独立进程（守护进程）是一种性能优化，并非 turbo 正常运行所必需。

{
  "daemon": true
}

envMode

默认值："strict"

Turborepo 的环境变量模式允许你控制哪些环境变量在运行时可用于任务

• "strict"： 过滤环境变量，仅保留在 turbo.json 的 env 和 globalEnv 键中指定的那些。
• "loose"： 允许进程的所有环境变量都可用。

{
  "envMode": "strict"
}

阅读更多关于 环境变量模式 的信息。

tags 实验性

{
  "tags": ["utils"]
}

为包添加标签，以便与 边界 一起使用。

此键仅在 包配置 中有效。 在根目录的 turbo.json 中使用此键将导致错误。

定义任务

tasks

tasks 对象中的每个键都是一个任务的名称，可以通过 turbo run 执行。 Turborepo 将在你的 Workspace 配置 中描述的包中搜索 package.json 中具有任务名称的脚本。

使用任务中描述的其余配置，Turborepo 将按描述的顺序运行脚本，并在提供时将日志和文件输出缓存在 outputs 键 中。

在下面的示例中，我们在 tasks 键下定义了三个任务：build、test 和 dev。

{
  "$schema": "https://turbo.net.cn/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "outputs": ["coverage/**"],
      "dependsOn": ["build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

任务选项

使用你在 tasks 中定义的任务中可用的选项，你可以描述 turbo 将如何运行你的任务。

dependsOn

在任务开始运行之前需要完成的任务列表。

dependsOn 关系有三种类型：依赖关系、同包关系 和 任意任务关系。

依赖关系

在 dependsOn 中以 ^ 为前缀的字符串告诉 turbo，该任务必须等待包的依赖项中的任务首先完成。 例如，在下面的 turbo.json 中

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

turbo 从包图的“底部”开始，递归访问每个包，直到找到没有内部依赖项的包。 然后，它将首先在依赖链的末尾运行 build 任务，然后返回到“顶部”，直到按顺序完成所有 build 任务。

同包关系

没有 ^ 前缀的任务名称描述了一个任务，该任务依赖于同一包中的不同任务。 例如，在下面的 turbo.json 中

{
  "tasks": {
    "test": {
      "dependsOn": ["lint", "build"]
    }
  }
}

test 任务仅在 同一包中 的 lint 和 build 任务完成后才会运行。

任意任务关系

指定特定包任务之间的任务依赖关系。

{
  "tasks": {
    "web#lint": {
      "dependsOn": ["utils#build"]
    }
  }
}

在此 turbo.json 中，web#lint 任务将等待 utils#build 任务完成。

env

任务依赖的环境变量列表。

{
  "tasks": {
    "build": {
      "env": ["DATABASE_URL"] // Impacts hash of all build tasks
    },
    "web#build": {
      "env": ["API_SERVICE_KEY"] // Impacts hash of web's build task
    }
  }
}

通配符

Turborepo 支持环境变量的通配符，因此你可以轻松地考虑所有具有给定前缀的环境变量。 例如，下面的 turbo.json 将所有以 MY_API_ 开头的环境变量包含到哈希中

{
  "tasks": {
    "build": {
      "env": ["MY_API_*"]
    }
  }
}

否定

前导 ! 表示将否定整个模式。 例如，下面的 turbo.json 将忽略 MY_API_URL 变量。

{
  "tasks": {
    "build": {
      "env": ["!MY_API_URL"]
    }
  }
}

示例

"FOO!"

匹配名为 FOO! 的单个环境变量。

{
  "tasks": {
    "build": {
      // Values will be available within `build` scripts
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    }
  }
}

应在此任务运行时可用的环境变量的允许列表，即使在 严格环境变量模式 下也是如此。

passThroughEnv 中提供的值不会影响任务的缓存键。 如果你希望这些变量的更改导致缓存未命中，则需要将它们包含在 env 或 globalEnv 中。

outputs

{
  "tasks": {
    "build": {
      // Cache all files emitted to the packages's `dist` directory
      "outputs": ["dist/**"]
    }
  }
}

相对于包的 package.json 的文件 glob 模式列表，用于在任务成功完成后缓存。

如果输出路径需要相对于仓库根目录，请参阅 $TURBO_ROOT$。

默认值：true

省略此键或传递空数组会告诉 turbo 不缓存任何内容（除了日志，在启用缓存时始终缓存日志）。

{
  "tasks": {
    "build": {
      "outputs": [".svelte-kit/**", "dist/**"] // File outputs will be cached
    },
    "dev": {
      "cache": false, // No outputs will be cached
      "persistent": true
    }
  }
}

cache

定义是否应缓存任务输出。 将 cache 设置为 false 对于长时间运行的开发任务以及确保任务始终在其任务执行图中运行时非常有用。

inputs

默认值：[]，包中所有已检入源代码控制的文件

{
  "tasks": {
    "test": {
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
    }
  }
}

有关 glob 语法的更多信息，请访问 文件 glob 规范。

使用 inputs 键会使你退出 turbo 的默认行为，即考虑 .gitignore。 你必须根据需要从 .gitignore 重建 glob，或使用 $TURBO_DEFAULT$ 基于默认行为构建。

{
  "tasks": {
    "check-types": {
      // Consider all default inputs except the package's README
      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
    }
  }
}

$TURBO_DEFAULT$

由于指定 inputs 键会立即退出默认行为，你可以在 inputs 数组中使用特殊字符串 $TURBO_DEFAULT$ 来恢复 turbo 的默认行为。 这允许你调整默认行为以获得更精细的粒度。

$TURBO_ROOT$

{
  "tasks": {
    "check-types": {
      // Consider all Typescript files in `src/` and the root tsconfig.json as inputs
      "inputs": ["$TURBO_ROOT$/tsconfig.json", "src/**/*.ts"]
    }
  }
}

任务可能引用位于其目录之外的文件。

以 $TURBO_ROOT$ 开头的文件 glob 将更改 glob，使其相对于仓库的根目录而不是包目录。

outputLogs

{
  "tasks": {
    "build": {
      "outputLogs": "new-only"
    }
  }
}

none

默认值：false

隐藏所有任务日志

persistent

将任务标记为 persistent 以防止其他任务依赖于长时间运行的进程。 默认情况下，持久任务是 交互式 的。

{
  "tasks": {
    "dev": {
      "persistent": true
    }
  }
}

由于长时间运行的进程不会退出，因此依赖于它的任务永远不会运行。 一旦你将任务标记为持久，如果其他任务依赖于它，turbo 将抛出错误。

此选项对于开发服务器或其他“watch”任务最有用。

标记为 persistent 的任务默认也是 interactive 的。

interactive

默认值：false（对于标记为 persistent 的任务，默认为 true）

{
  "tasks": {
    "test:watch": {
      "interactive": true,
      "persistent": true
    }
  }
}

将任务标记为 interactive，使其在终端 UI 中接受来自 stdin 的输入。 必须与 persistent 一起使用。

默认值：false

此选项对于在运行时可以操作的脚本最有用，例如 Jest 或 Vitest。

interruptible

将 persistent 任务标记为 interruptible，以允许 turbo watch 重新启动它。

turbo watch 监视你的包的更改并自动重新启动受影响的任务。 但是，如果任务是持久的，则默认情况下不会重新启动。 要启用重新启动持久任务，请将 interruptible 设置为 true。

{
  "tasks": {
    "dev": {
      "with": ["api#dev"],
      "persistent": true,
      "cache": false
    }
  }
}

with

将与此任务并行运行的任务列表。 这对于你希望确保始终同时运行的长时间运行的任务最有用。

{
  "boundaries": {}
}

边界

boundaries 标签允许你为 boundaries 命令 定义规则。

tags

tags 对象中的每个键都是一个标签的名称，可以使用 turbo boundaries 进行检查。

在标签的配置对象中，你可以定义依赖项和被依赖项的规则。

dependencies 和 dependents

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // permit only packages with the `ui` tag
        "allow": ["ui"],
        // and ban packages with the `unsafe` tag
        "deny": ["unsafe"]
      }
    }
  }
}

标签的依赖项和被依赖项的规则。

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // only packages with the `unsafe` tag are banned, all other packages permitted
        "deny": ["unsafe"]
      }
    }
  }
}

你可以添加允许列表和拒绝列表

{
  "boundaries": {
    "utils": {
      "dependents": {
        // only packages with the `web` tag can import packages with the `utils` tag
        "allow": ["web"]
      }
    }
  }
}

允许列表和拒绝列表都可以省略。

也可以为标签的被依赖项添加规则，即导入此标签的包。

{
  "remoteCache": {}
}

远程缓存

默认值：true

全局 remoteCache 选项有多个字段用于配置远程缓存的使用

enabled

启用远程缓存。

默认值：false

当 false 时，Turborepo 将禁用所有远程缓存操作，即使仓库具有有效的令牌也是如此。 如果为 true，则启用远程缓存，但仍需要用户登录并将他们的仓库链接到远程缓存。

signature

默认值：false

为远程缓存的请求启用签名验证。 当 true 时，Turborepo 将使用环境变量 TURBO_REMOTE_CACHE_SIGNATURE_KEY 的值对每个上传的工件进行签名。 Turborepo 将拒绝任何具有无效签名或缺少签名的下载工件。

preflight

启用后，任何 HTTP 请求都将以 OPTIONS 请求开头，以确定端点是否支持该请求。

timeout

默认值：30

设置远程缓存操作的超时时间。 值以秒为单位给出，并且仅接受整数值。 如果传递 0，则任何缓存操作都没有超时时间。

uploadTimeout

默认值：60

设置远程缓存上传的超时时间。 值以秒为单位给出，并且仅接受整数值。 如果传递 0，则任何远程缓存上传都没有超时时间。

apiUrl

默认值："https://vercel.com"

设置远程缓存上传的超时时间。 值以秒为单位给出，并且仅接受整数值。 如果传递 0，则任何远程缓存上传都没有超时时间。

设置远程缓存 API 调用的端点。

loginUrl

设置在 turbo login 期间请求令牌的端点。

teamId

远程缓存团队的 ID。 该值将作为 teamId 在所有远程缓存 HTTP 调用的查询字符串中传递。 必须以 team_ 开头，否则将不会使用。