配置 turbo.json

通过在你的 Workspace 的根目录中添加 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 的位置。

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

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 使用你的仓库的 lockfile 来确定缓存行为、包图等。因此，我们使用packageManager 字段来帮助你稳定你的 Turborepo。

为了帮助增量迁移或在你无法使用 packageManager 字段的情况下，你可以使用 --dangerously-disable-package-manager-check 来选择退出此检查并承担不稳定的 lockfile 产生不可预测行为的风险。禁用后，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"
}

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

`tags` 实验性

./apps/web/turbo.json

{
  "tags": ["utils"]
}

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

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

定义任务

`tasks`

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

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

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

./turbo.json

{
  "$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 中

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

`passThroughEnv`

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

./turbo.json

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

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

`outputs`

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

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

./turbo.json

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

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

`cache`

默认值: true

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

./turbo.json

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

`inputs`

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

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

访问文件 glob 规范以获取有关 glob 语法的更多信息。

./turbo.json

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

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

$TURBO_DEFAULT$

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

./turbo.json

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

$TURBO_ROOT$

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

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

./turbo.json

{
  "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

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

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

./turbo.json

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

`persistent`

默认值: false

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

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

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

./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。

边界

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

./turbo.json

{
  "boundaries": {}
}

`tags`

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

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

`dependencies` 和 `dependents`

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

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

./turbo.json

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

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

./turbo.json

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

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

./turbo.json

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

远程缓存

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

./turbo.json

{
  "remoteCache": {}
}

`enabled`

默认值: true

启用远程缓存。

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

配置 turbo.json

本页内容