Turborepo
API 参考

配置 turbo.json

通过在工作区的根目录中添加 turbo.json 文件来配置 turbo 的行为。

更改根目录的 turbo.json 文件将使所有任务的缓存失效，因为它被视为 全局哈希 的一部分。如果您希望在不影响全局哈希的情况下灵活更改配置，请使用 包配置。

全局选项

extends

./apps/web/turbo.json
{
  "extends": ["//"]
}

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

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

globalDependencies

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

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

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

glob 必须位于仓库的源代码控制根目录中。不支持仓库之外的 glob。

globalEnv

./turbo.json
{
  "globalEnv": ["GITHUB_TOKEN", "PACKAGE_VERSION", "NODE_ENV"]
}

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

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

globalPassThroughEnv

./turbo.json
{
  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
}

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

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

传递的值不会影响缓存的哈希值

如果您希望这些变量中的更改导致缓存未命中，则需要将它们包含在 env 或 globalEnv 中。

ui

默认值："stream"

选择仓库的终端 UI。

"tui" 允许一次查看每个日志并与任务进行交互。"stream" 输出日志，因为它们是进入的，并且不是交互式的。

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

dangerouslyDisablePackageManagerCheck

默认值：false

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

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

./turbo.json
{
  "dangerouslyDisablePackageManagerCheck": true
}

您也可以通过 flag 或 TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK 环境变量退出此检查。

cacheDir

默认值：".turbo/cache"

指定文件系统缓存目录。

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

daemon

默认值：true

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

./turbo.json
{
  "daemon": true
}

须知

在 CI 环境中运行时，无论此设置如何，守护进程始终处于禁用状态。

envMode

默认值："strict"

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

  • "strict"：筛选环境变量，使其仅限于 turbo.json 中 env 和 globalEnv 键中指定的那些。
  • "loose"：允许该进程的所有环境变量都可用。

阅读更多关于环境模式。

./turbo.json
{
  "envMode": "strict"
}

定义任务

tasks

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

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

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

./turbo.json
{
  "$schema": "https://turbo.rust-lang.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 中

./turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

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

同一包关系

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

./turbo.json
{
  "tasks": {
    "test": {
      "dependsOn": ["lint", "build"]
    }
  }
}

只有在同一包中 lint 和 build 任务完成后，才会运行 test 任务。

任意任务关系

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

./turbo.json
{
  "tasks": {
    "web#lint": {
      "dependsOn": ["utils#build"]
    }
  }
}

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

env

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

./turbo.json
{
  "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 通过 框架推断自动包含以常见框架为前缀的环境变量。例如，如果您的包是一个 Next.js 项目，则无需指定任何以 NEXT_PUBLIC_ 开头的环境变量。

通配符

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

./turbo.json
{
  "tasks": {
    "build": {
      "env": ["MY_API_*"]
    }
  }
}

否定

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

./turbo.json
{
  "tasks": {
    "build": {
      "env": ["!MY_API_URL"]
    }
  }
}

示例

模式描述
"*""*"
"!*"匹配每个环境变量。
"!*"排除每个环境变量。
"FOO*"匹配 FOO、FOOD、FOO_FIGHTERS 等。
"FOO\*"解析为 "FOO*" 并匹配 FOO、FOOD 和 FOO_FIGHTERS。
"FOO\\*"匹配名为 FOO* 的单个环境变量。
"!FOO*"排除所有以 FOO 开头的环境变量。
"\!FOO"解析为 "!FOO"，并排除名为 !FOO 的单个环境变量。
"\\!FOO"匹配名为 !FOO 的单个环境变量。

"FOO!"

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

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

passThroughEnv

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

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

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

outputs

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

默认值：true

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

./turbo.json
{
  "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

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

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

在确定包是否已更改时，要考虑的相对于包的 package.json 的文件 glob 模式列表。turbo.json 始终被视为输入。

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

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

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

outputLogs

默认值: full

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

选项描述
full显示所有日志
hash-only仅显示任务的哈希值
new-only仅显示缓存未命中时的日志
errors-only仅显示任务失败时的日志
none隐藏所有任务日志
./turbo.json
{
  "tasks": {
    "build": {
      "outputLogs": "new-only"
    }
  }
}

persistent

默认值：false

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

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

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

./turbo.json
{
  "tasks": {
    "dev": {
      "persistent": true
    }
  }
}

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

interactive

默认值: false (对于标记为 persistent 的任务，默认值为 true)

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

此任务最适用于可以在运行时操作的脚本，例如 Jest 或 Vitest。

./turbo.json
{
  "tasks": {
    "test:watch": {
      "interactive": true,
      "persistent": true
    }
  }
}

interruptible

默认值：false

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

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

远程缓存

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

./turbo.json
{
  "remoteCache": {}
}

enabled

默认值：true

启用远程缓存。

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

signature

默认值：false

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

preflight

默认值：false

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

timeout

默认值: 30

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

uploadTimeout

默认值: 60

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

apiUrl

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

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

loginUrl

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

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

上一个

Turborepo API 参考

下一个

软件包配置

小时

节省的计算总时间
开始使用
远程缓存 →

本页内容

全局选项extendsglobalDependenciesglobalEnvglobalPassThroughEnvuidangerouslyDisablePackageManagerCheckcacheDirdaemonenvMode定义任务任务任务选项dependsOn依赖关系同一软件包的关系任意任务关系env通配符否定示例passThroughEnvoutputscacheinputs$TURBO_DEFAULT$outputLogspersistentinteractiveinterruptible远程缓存enabledsignaturepreflighttimeoutuploadTimeoutapiUrlloginUrl