配置 turbo.json

使用工作区根目录中的 turbo.json 文件配置 turbo 的行为。你还可以：

¥Configure the behavior of turbo by using a turbo.json file in your Workspace's root directory. You can also:

• 使用 软件包配置 进行更精细的控制。

  ¥Use Package Configurations for more granular control.

• 使用 turbo.jsonc 为你的配置添加注释，并借助 IDE 支持。

  ¥Use turbo.jsonc to add comments to your configuration with IDE support.

全局选项

¥Global options

extends

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

从根 turbo.json 扩展，使用 软件包配置 为包创建特定配置。

¥Extend from the root turbo.json to create specific configuration for a package using Package Configurations.

• extends 的唯一有效值是 ["//"]，用于从根目录 turbo.json 继承配置。

  ¥The only valid value for extends is ["//"] to inherit configuration from the root turbo.json.

• 如果在根 turbo.json 中使用 extends，它将被忽略。

  ¥If extends is used in the root turbo.json, it will be ignored.

globalDependencies

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

要包含在所有任务哈希中的全局变量列表。如果任何与这些全局变量匹配的文件发生更改，所有任务都将丢失缓存。Globs 是相对于 turbo.json 位置的。

¥A list of globs that you want to include in all task hashes. If any file matching these globs changes, all tasks will miss cache. Globs are relative to the location of turbo.json.

默认情况下，全局哈希 仅包含根 package.json 和 lockfile，并且不能忽略。任何添加的 globalDependencies 也将包含在全局哈希中。

¥By default, only the root package.json and lockfile are included in the global hash and can't be ignored. Any added globalDependencies will also be included in the global hash.

globalEnv

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

你希望影响所有任务哈希值的环境变量列表。对这些环境变量的任何更改都会导致所有任务缓存未命中。

¥A list of environment variables that you want to impact the hash of all tasks. Any change to these environment variables will cause all tasks to miss cache.

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

¥For more on wildcard and negation syntax, see the env section.

globalPassThroughEnv

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

你希望对任务可用的环境变量列表。使用此键会将所有任务添加到 严格环境变量模式 中。

¥A list of environment variables that you want to make available to tasks. Using this key opts all tasks into Strict Environment Variable Mode.

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

¥Additionally, Turborepo has a built-in set of global passthrough variables for common cases, like operating system environment variables. This includes variables like HOME, PATH, APPDATA, SHELL, PWD, and more. The full list can be found in the source code.

ui

默认："stream"

¥Default: "stream"

为存储库选择一个终端 UI。

¥Select a terminal UI for the repository.

"tui" 允许一次性查看每个日志并与任务交互。"stream" 会在日志输入时输出日志，并且不可交互。

¥"tui" allows for viewing each log at once and interacting with the task. "stream" outputs logs as they come in and is not interactive.

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

noUpdateNotifier

默认：false

¥Default: false

设置为 true 时，将禁用 turbo 新版本可用时显示的更新通知。

¥When set to true, disables the update notification that appears when a new version of turbo is available.

{
  "noUpdateNotifier": true
}

concurrency

默认："10"

¥Default: "10"

设置/限制任务执行的最大并发数。必须是大于或等于 1 的整数，或者像 50% 这样的百分比值。

¥Set/limit the maximum concurrency for task execution. Must be an integer greater than or equal to 1 or a percentage value like 50%.

• 使用 1 强制串行执行（一次执行一个任务）。

  ¥Use 1 to force serial execution (one task at a time).

• 使用 100% 使用所有可用的逻辑处理器。

  ¥Use 100% to use all available logical processors.

• 如果同时传递了 --parallel 标志，则此选项将被忽略。

  ¥This option is ignored if the --parallel flag is also passed.

{
  "concurrency": "1"
}

dangerouslyDisablePackageManagerCheck

默认：false

¥Default: false

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

¥Turborepo uses your repository's lockfile to determine caching behavior, Package Graphs, and more. Because of this, we use the packageManager field to help you stabilize your Turborepo.

为了帮助增量迁移或在无法使用 packageManager 字段的情况下，你可以使用 --dangerously-disable-package-manager-check 退出此检查，并承担不稳定的锁文件产生不可预测行为的风险。禁用后，Turborepo 将尽力查找适用于该存储库的包管理器。

¥To help with incremental migration or in situations where you can't use the packageManager field, you may use --dangerously-disable-package-manager-check to opt out of this check and assume the risks of unstable lockfiles producing unpredictable behavior. When disabled, Turborepo will attempt a best-effort discovery of the intended package manager meant for the repository.

{
  "dangerouslyDisablePackageManagerCheck": true
}

cacheDir

默认：".turbo/cache"

¥Default: ".turbo/cache"

指定文件系统缓存目录。

¥Specify the filesystem cache directory.

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

daemon

默认：true

¥Default: true

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

¥Turborepo runs a background process to pre-calculate some expensive operations. This standalone process (daemon) is a performance optimization, and not required for proper functioning of turbo.

{
  "daemon": true
}

envMode

默认："strict"

¥Default: "strict"

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

¥Turborepo's Environment Modes allow you to control which environment variables are available to a task at runtime:

• "strict"：将环境变量过滤为仅在 turbo.json 中的 env 和 globalEnv 键中指定的变量。

  ¥"strict": Filter environment variables to only those that are specified in the env and globalEnv keys in turbo.json.

• "loose"：允许进程的所有环境变量可用。

  ¥"loose": Allow all environment variables for the process to be available.

{
  "envMode": "strict"
}

了解更多关于 环境模式 的信息。

¥Read more about Environment Modes.

tags Experimental

{
  "tags": ["utils"]
}

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

¥Adds a tag to a package for use with Boundaries.

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

¥This key only works in Package Configurations. Using this key in a root turbo.json will result in an error.

定义任务

¥Defining tasks

tasks

tasks 对象中的每个键都是一个可以由 turbo run 执行的任务名称。Turborepo 将在你的 工作区配置 中描述的包中搜索 package.json 中与任务名称相同的脚本。

¥Each key in the tasks object is the name of a task that can be executed by turbo run. Turborepo will search the packages described in your Workspace's configuration for scripts in package.json with the name of the task.

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

¥Using the rest of the configuration described in the task, Turborepo will run the scripts in the described order, caching logs and file outputs in the outputs key when provided.

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

¥In the example below, we've defined three tasks under the tasks key: build, test, and dev.

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

任务选项

¥Task options

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

¥Using the options available in the tasks you define in tasks, you can describe how turbo will run your tasks.

dependsOn

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

¥A list of tasks that are required to complete before the task begins running.

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

¥There are three types of dependsOn relationships: dependency relationships, same-package relationships, and arbitrary task relationships.

依赖

¥Dependency relationships

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

¥Prefixing a string in dependsOn with a ^ tells turbo that the task must wait for tasks in the package's dependencies to complete first. For example, in the turbo.json below:

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

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

¥turbo starts at the "bottom" of the package graph and recursively visits each package until it finds a package with no internal dependencies. It will then run the build task at the end of the dependency chain first, working its way back to the "top" until all build tasks are completed in order.

相同的包关系

¥Same package relationships

不带 ^ 前缀的任务名称描述依赖于同一包中其他任务的任务。例如，在下面的 turbo.json 中：

¥Task names without the ^ prefix describe a task that depends on a different task within the same package. For example, in the turbo.json below:

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

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

¥The test task will only run after the lint and build tasks have completed in the same package.

任意任务关系

¥Arbitrary task relationships

指定特定软件包任务之间的任务依赖。

¥Specify a task dependency between specific package tasks.

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

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

¥In this turbo.json, the web#lint task will wait for the utils#build task to complete.

env

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

¥The list of environment variables a task depends on.

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

通配符

¥Wildcards

Turborepo 支持环境变量的通配符，因此你可以轻松地使用给定前缀来解释所有环境变量。例如，下面的 turbo.json 将所有以 MY_API_ 开头的环境变量都包含在哈希值中：

¥Turborepo supports wildcards for environment variables so you can easily account for all environment variables with a given prefix. For example, the turbo.json below include all environment variables that start with MY_API_ into the hash:

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

否决

¥Negation

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

¥A leading ! means that the entire pattern will be negated. For instance, the turbo.json below will ignore the MY_API_URL variable.

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

示例

¥Examples

passThroughEnv

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

¥An allowlist of environment variables that should be made available to this task's runtime, even when in Strict Environment Mode.

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

outputs

与包的 package.json 相关的文件通配符模式列表，用于在任务成功完成后进行缓存。

¥A list of file glob patterns relative to the package's package.json to cache when the task is successfully completed.

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

¥See $TURBO_ROOT$ if output paths need to be relative to the repository root.

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

省略此键或传递一个空数组将告知 turbo 不缓存任何内容（日志除外，启用缓存后日志始终会被缓存）。

¥Omitting this key or passing an empty array tells turbo to cache nothing (except logs, which are always cached when caching is enabled).

cache

默认：true

¥Default: true

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

¥Defines if task outputs should be cached. Setting cache to false is useful for long-running development tasks and ensuring that a task always runs when it is in the task's execution graph.

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

inputs

默认：[]，软件包中所有已签入源代码管理的文件

¥Default: [], all files in the package that are checked into source control

与包的 package.json 相关的文件通配符模式列表，用于在确定包是否已更改时考虑。以下文件始终被视为输入，即使你尝试明确忽略它们：

¥A list of file glob patterns relative to the package's package.json to consider when determining if a package has changed. The following files are always considered inputs, even if you try to explicitly ignore them:

• package.json

• turbo.json

• 包管理器锁文件

  ¥Package manager lockfiles

访问 文件全局规范 了解有关通配符语法的更多信息。

¥Visit the file glob specification for more information on globbing syntax.

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

$TURBO_DEFAULT$

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

¥Because specifying an inputs key immediately opts out of the default behavior, you may use the special string $TURBO_DEFAULT$ within the inputs array to restore turbo's default behavior. This allows you to tweak the default behavior for more granularity.

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

$TURBO_ROOT$

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

¥Tasks might reference a file that lies outside of their directory.

使用 $TURBO_ROOT$ 启动文件 glob 会将 glob 更改为相对于仓库根目录，而不是包目录。

¥Starting a file glob with $TURBO_ROOT$ will change the glob to be relative to the root of the repository instead of the package directory.

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

outputLogs

默认：full

¥Default: full

设置输出日志详细程度。可以被 --output-logs CLI 选项覆盖。

¥Set output logging verbosity. Can be overridden by the --output-logs CLI option.

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

persistent

默认：false

¥Default: false

将任务标记为 persistent，以防止其他任务依赖于长时间运行的进程。持久任务默认为 interactive。

¥Label a task as persistent to prevent other tasks from depending on long-running processes. Persistent tasks are made interactive by default.

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

¥Because a long-running process won't exit, tasks that would depend on it would never run. Once you've labeled the task as persistent, turbo will throw an error if other tasks depend on it.

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

¥This option is most useful for development servers or other "watch" tasks.

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

默认情况下，标有 persistent 的任务也是 interactive。

¥Tasks marked with persistent are also interactive by default.

interactive

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

¥Default: false (Defaults to true for tasks marked as persistent)

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

¥Label a task as interactive to make it accept inputs from stdin in the terminal UI. Must be used with persistent.

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

¥This option is most useful for scripts that can be manipulated while they are running, like Jest or Vitest.

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

interruptible

默认：false

¥Default: false

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

¥Label a persistent task as interruptible to allow it to be restarted by turbo watch.

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

¥turbo watch watches for changes to your packages and automatically restarts tasks that are affected. However, if a task is persistent, it will not be restarted by default. To enable restarting persistent tasks, set interruptible to true.

with

将与此任务一起运行的任务列表。这对于需要确保始终同时运行的长时间运行任务非常有用。

¥A list of tasks that will be ran alongside this task. This is most useful for long-running tasks that you want to ensure always run at the same time.

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

边界

¥Boundaries

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

¥The boundaries tag allows you to define rules for the boundaries command.

{
  "boundaries": {}
}

tags

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

¥Each key in the tags object is the name of a tag that can be checked with turbo boundaries.

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

¥In the configuration object for a tag, you can define rules for dependencies and dependents.

dependencies 和 dependents

¥dependencies and dependents

标签依赖和依赖的规则。

¥Rules for a tag's dependencies and dependents.

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

¥You can add an allowlist and a denylist:

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

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

¥Both the allowlist and the denylist can be omitted.

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

还可以为标签的依赖（即导入此标签的包）添加规则。

¥Rules can also be added for a tag's dependents, i.e. packages that import this tag.

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

远程缓存

¥Remote caching

全局 remoteCache 选项包含各种字段，用于配置远程缓存的使用。

¥The global remoteCache option has a variety of fields for configuring remote cache usage

{
  "remoteCache": {}
}

enabled

默认：true

¥Default: true

启用远程缓存。

¥Enables remote caching.

当 false 匹配时，Turborepo 将禁用所有远程缓存操作，即使仓库拥有有效的令牌。如果为 true，则启用远程缓存，但仍需要用户登录并将其代码库链接到远程缓存。

¥When false, Turborepo will disable all remote cache operations, even if the repo has a valid token. If true, remote caching is enabled, but still requires the user to login and link their repo to a remote cache.

signature

默认：false

¥Default: false

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

¥Enables signature verification for requests to the remote cache. When true, Turborepo will sign every uploaded artifact using the value of the environment variable TURBO_REMOTE_CACHE_SIGNATURE_KEY. Turborepo will reject any downloaded artifacts that have an invalid signature or are missing a signature.

preflight

默认：false

¥Default: false

启用后，任何 HTTP 请求之前都会有一个 OPTIONS 请求，以确定端点是否支持该请求。

¥When enabled, any HTTP request will be preceded by an OPTIONS request to determine if the request is supported by the endpoint.

timeout

默认：30

¥Default: 30

设置远程缓存操作的超时时间。值以秒为单位，并且只接受整数。如果已传递 0，则任何缓存操作均不会超时。

¥Sets a timeout for remote cache operations. Value is given in seconds and only whole values are accepted. If 0 is passed, then there is no timeout for any cache operations.

uploadTimeout

默认：60

¥Default: 60

设置远程缓存上传的超时时间。值以秒为单位，并且只接受整数。如果已传递 0，则任何远程缓存上传均不会超时。

¥Sets a timeout for remote cache uploads. Value is given in seconds and only whole values are accepted. If 0 is passed, then there is no timeout for any remote cache uploads.

apiUrl

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

¥Default: "https://vercel.com"

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

¥Set endpoint for API calls to the remote cache.

loginUrl

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

¥Default: "https://vercel.com"

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

¥Set endpoint for requesting tokens during turbo login.

teamId

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

¥The ID of the Remote Cache team. Value will be passed as teamId in the querystring for all Remote Cache HTTP calls. Must start with team_ or it will not be used.

teamSlug

远程缓存团队的 slug。值将作为 slug 在所有远程缓存 HTTP 调用的查询字符串中传递。

¥The slug of the Remote Cache team. Value will be passed as slug in the querystring for all Remote Cache HTTP calls.