Configuration

配置 turbo.json

通过在工作空间根目录中使用 turbo.json 文件来配置 turbo 的行为

通过在工作空间根目录中使用 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 的位置。

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

Glob 必须在仓库的源代码控制根目录中。不支持仓库外的 Glob。

`globalEnv`

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

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

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

`globalPassThroughEnv`

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

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

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

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

`ui`

默认值："stream"

为仓库选择终端 UI。

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

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

`noUpdateNotifier`

默认值：false

当设置为 true 时，禁用当有新版本的 turbo 可用时出现的更新通知。

{
  "noUpdateNotifier": true
}

`concurrency`

默认值："10"

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

使用 1 强制串行执行（一次一个任务）。
使用 100% 使用所有可用的逻辑处理器。
如果还传递了 --parallel 标志，则忽略此选项。

{
  "concurrency": "1"
}

`dangerouslyDisablePackageManagerCheck`

默认值：false

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

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

{
  "dangerouslyDisablePackageManagerCheck": true
}

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

`cacheDir`

默认值：".turbo/cache"

指定文件系统缓存目录。

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

`daemon`

默认值：true

Turborepo 运行后台进程来预计算一些昂贵的操作。这个独立进程（守护进程）是性能优化，不是 turbo 正常运行所必需的。

{
  "daemon": true
}

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

`envMode`

默认值："strict"

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

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

{
  "envMode": "strict"
}

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

`tags` ::badge实验性

{
  "tags": ["utils"]
}

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

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

定义任务

`tasks`

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

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

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

{
  "$schema": "https://turborepo.com/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"] // 影响所有构建任务的哈希
    },
    "web#build": {
      "env": ["API_SERVICE_KEY"] // 影响 web 的构建任务的哈希
    }
  }
}

Turborepo 通过框架推断自动包含由常见框架前缀的环境变量。例如，如果您的包是 Next.js 项目，您不需要指定任何以 NEXT_PUBLIC_ 开头的环境变量。

通配符

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

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

否定

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

{
  "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!` 的单个环境变量。

`passThroughEnv`

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

{
  "tasks": {
    "build": {
      // 值将在 `build` 脚本中可用
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    }
  }
}

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

`outputs`

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

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

{
  "tasks": {
    "build": {
      // 缓存发出到包的 `dist` 目录的所有文件
      "outputs": ["dist/**"]
    }
  }
}

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

`cache`

默认值：true

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

{
  "tasks": {
    "build": {
      "outputs": [".svelte-kit/**", "dist/**"] // 文件输出将被缓存
    },
    "dev": {
      "cache": false, // 不会缓存输出
      "persistent": true
    }
  }
}

`inputs`

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

在确定包是否已更改时要考虑的相对于包的 package.json 的文件 glob 模式列表。以下文件始终被视为输入，即使您尝试显式忽略它们：

package.json
turbo.json
包管理器锁文件

访问文件 glob 规范了解更多关于 globbing 语法的信息。

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

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

$TURBO_DEFAULT$

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

{
  "tasks": {
    "check-types": {
      // 考虑除包的 README 之外的所有默认输入
      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
    }
  }
}

$TURBO_ROOT$

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

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

{
  "tasks": {
    "check-types": {
      // 将 `src/` 中的所有 Typescript 文件和根 tsconfig.json 视为输入
      "inputs": ["$TURBO_ROOT$/tsconfig.json", "src/**/*.ts"]
    }
  }
}

`outputLogs`

默认值：full

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

选项	描述
`full`	显示所有日志
`hash-only`	仅显示任务的哈希
`new-only`	仅显示缓存错过的日志
`errors-only`	仅显示任务失败的日志
`none`	隐藏所有任务日志

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

`persistent`

默认值：false

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

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

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

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

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

`interactive`

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

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

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

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

`interruptible`

默认值：false

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

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

`with`

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

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

边界

boundaries 对象允许您为包之间的依赖关系定义规则。

{
  "boundaries": {}
}

`tags`

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

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

`dependencies` 和 `dependents`

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

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

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // 仅允许具有 `ui` 标签的包
        "allow": ["ui"],
        // 并禁止具有 `unsafe` 标签的包
        "deny": ["unsafe"]
      }
    }
  }
}

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

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // 仅禁止具有 `unsafe` 标签的包，允许所有其他包
        "deny": ["unsafe"]
      }
    }
  }
}

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

{
  "boundaries": {
    "utils": {
      "dependents": {
        // 只有具有 `web` 标签的包可以导入具有 `utils` 标签的包
        "allow": ["web"]
      }
    }
  }
}

远程缓存

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

{
  "remoteCache": {}
}

`enabled`

默认值：true

启用远程缓存。

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

了解如何将 Turborepo 从 1.x 升级到 2.0，包括配置更新、包管理器字段添加和行为变更。

包配置

使用包配置为 monorepo 中的特定包自定义 turbo.json 配置