配置选项 (`turbo.json`)

你可以通过在你的单仓库的根目录中添加一个 turbo.json 文件来配置 turbo 的行为。

`globalDependencies`

类型：string[]

用于全局哈希依赖项的文件 glob 列表。这些文件的内容将包含在全局哈希算法中，并影响所有任务的哈希值。这对于根据 .env 文件（不在 Git 中）或任何影响工作区任务的根级文件（但不在传统的依赖关系图中表示（例如根 tsconfig.json、jest.config.js、.eslintrc 等））来清除缓存非常有用。

这些必须是相对于 turbo.json 位置的路径，并且它们应该对任何可能使用此配置的机器有效。例如，引用一个用户主目录中的文件不是一个好主意。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    // ... omitted for brevity
  },
 
  "globalDependencies": [
    ".env", // contents will impact hashes of all tasks
    "tsconfig.json" // contents will impact hashes of all tasks
  ]
}

`globalEnv`

类型：string[]

用于隐式全局哈希依赖项的环境变量列表。这些环境变量的内容将包含在全局哈希算法中，并影响所有任务的哈希值。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    // ... omitted for brevity
  },
 
  "globalEnv": ["GITHUB_TOKEN"] // value will impact the hashes of all tasks
}

`globalPassThroughEnv`

这在你的配置的根部。

类型：string[]

应该对所有任务可用但不会影响任务缓存键的环境变量的白名单。使用此键将所有任务选择到 strict 环境变量模式。

更改此列表将影响全局缓存键，但每个变量的值不会。

示例

AWS_SECRET_KEY 和 GITHUB_TOKEN 在 strict env 模式中对所有任务可用。

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"],
  "pipeline": {
    // ...task definitions...
  }
}

`globalDotEnv`

type: null | string[] default: null

要包含到全局哈希键的文件哈希中的 .env 文件的有序列表。

注意：这不会将文件加载到环境中。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "globalDotEnv": [".env.local", ".env"],
  "pipeline": {
    "build": {}
  }
}

`extends类型：string[]`

`extends` 键仅在工作区配置中有效。它将在根目录的 `turbo.json` 中被忽略。阅读 文档以了解更多信息。

`experimentalUI`

type: bool

启用 turbo 的新 UI。可以通过 TURBO_EXPERIMENTAL_UI 环境变量覆盖。

`pipeline`

一个表示项目任务依赖关系图的对象。 turbo 解释这些约定以正确地调度、执行和缓存项目中任务的输出。

pipeline 对象中的每个键都是一个任务的名称，可以由 turbo run 执行。如果 turbo 找到一个工作区，该工作区具有一个 package.json scripts 对象，该对象具有匹配的键，它将在执行期间将管道任务配置应用于该 npm 脚本。这使您可以使用 pipeline 在整个 Turborepo 中设置约定。

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "outputs": ["coverage/**"],
      "dependsOn": ["build"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"],
      "outputMode": "full"
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

`dependsOn`

类型：string[]

此任务依赖的任务列表。

在 dependsOn 中用 ^ 为前缀的项目告诉 turbo 此管道任务依赖于工作区的拓扑依赖关系，首先完成带有 ^ 前缀的任务（例如，“工作区的 build 任务应该只在所有 dependencies 和 devDependencies 完成其自己的 build 命令后运行”）。

在 dependsOn 中没有 ^ 前缀的项目，表示工作区级别任务之间的关系（例如，“工作区的 test 和 lint 命令依赖于 build 首先完成”）。

从 1.5 版本开始，使用 $ 在 dependsOn 配置中声明环境变量已弃用。请改用 env 键。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      // "A workspace's `build` command depends on its dependencies'
      // or devDependencies' `build` command being completed first"
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      // "A workspace's `test` command depends on its own `lint` and
      // `build` commands first being completed"
      "dependsOn": ["lint", "build"]
    },
    "deploy": {
      // "A workspace's `deploy` command, depends on its own `build`
      // and `test` commands first being completed"
      "dependsOn": ["build", "test"]
    },
    // A workspace's `lint` command has no dependencies
    "lint": {}
  }
}

`dotEnv`

type: null | string[] default: null

要包含到任务文件哈希中的 .env 文件的有序列表。这些文件将被包含到哈希中，无论它们是否包含在 git 索引中。

注意：这不会将文件加载到环境中。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      "dotEnv": [".env.local", ".env"]
    }
  }
}

`env`

类型：string[]

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

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["SOMETHING_ELSE"], // value will impact the hashes of all build tasks
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "web#build": {
      "dependsOn": ["^build"],
      "env": ["STRIPE_SECRET_KEY"], // value will impact hash of only web's build task
      "outputs": [".next/**", "!.next/cache/**"]
    }
  },
  "globalEnv": [
    "GITHUB_TOKEN" // value will impact the hashes of all tasks
  ]
}

当 Turborepo 在工作区中检测到常见的前端框架时，它将自动依赖于将在构建中内联的环境变量。例如，如果 web 工作区包含一个 Next.js 项目，则您无需在 dependsOn 配置中指定任何以 NEXT_PUBLIC_ (opens in a new tab) 开头的环境变量。Turborepo 已经知道构建输出将在这些环境变量的值发生变化时发生变化，因此它将自动依赖于它们。在缓存文档中了解更多信息。

`passThroughEnv`

类型：string[]

此配置位于 pipeline 中的每个任务定义内。

应该使此任务可用的环境变量的白名单，但不应影响任务的缓存键。使用此键将此任务选择到 strict 环境变量模式。

更改此列表将影响任务的缓存键，但每个变量的值不会。

示例

AWS_SECRET_KEY 和 GITHUB_TOKEN 可用于 build 任务，但不可用于 lint 任务，在 strict env 模式中。

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    },
    "lint": {}
  }
}

`outputs`

类型：string[]

任务可缓存的文件系统输出的 glob 模式集。

注意： turbo 会自动将 stderr/stdout 记录到 .turbo/run-<task>.log。此文件始终被视为可缓存的工件，无需指定。

省略此键或传递空数组可用于告诉 turbo 任务是一个副作用，因此不会发出任何文件系统工件（例如，像 linter 一样），但您仍然希望缓存其日志（并将它们视为工件）。

outputs glob 必须指定为相对于工作区目录的路径。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      // "Cache all files emitted to workspace's dist/** or .next
      // directories by a `build` task"
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      // "Don't cache any artifacts of `test` tasks (aside from
      // logs)"
      "dependsOn": ["build"]
    },
    "test:ci": {
      // "Cache the coverage report of a `test:ci` command"
      "outputs": ["coverage/**"],
      "dependsOn": ["build"]
    },
    "dev": {
      // Never cache anything (including logs) emitted by a
      // `dev` task
      "cache": false,
      "persistent": true
    }
  }
}

`cache`

类型: boolean

默认值为 true。是否缓存任务 outputs。将 cache 设置为 false 对守护进程或长时间运行的“监视”或开发模式任务很有用，您不希望缓存这些任务。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      "outputs": [".svelte-kit/**", "dist/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

`inputs`

类型：string[]

告诉 turbo 在确定特定任务的包是否已更改时要考虑的文件集。将其设置为 glob 列表将导致仅在与这些 glob 匹配的文件更改时才运行任务。这在您想要的情况下很有用，例如，除非源文件更改，否则跳过运行测试，或者显式依赖于 .gitignored 文件。

了解一下： - inputs 的默认值为 []，以便在包中的任何文件更改时运行任务。 - inputs glob 必须指定为相对于包目录的相对路径。 - turbo.json 始终被视为输入。如果您修改了 turbo.json，所有缓存都将失效。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "test": {
      // A package's `test` task should only be ran when
      // either a `.tsx` or `.ts` file has changed.
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
    }
  }
}

由于指定 inputs 键会立即选择退出默认行为，您可以在 inputs 数组中指定特殊字符串 $TURBO_DEFAULT$ 以从默认输入开始。当您想要从默认集中添加或删除其他输入时，这很有用。

示例使用 $TURBO_DEFAULT$

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "check-types": {
      // Consider all default inputs except the README.md
      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
    }
  }
}

`outputMode`

类型: "full" | "hash-only" | "new-only" | "errors-only" | "none"

设置输出日志的类型。可以通过 --output-logs CLI 选项覆盖。

选项	描述
full	显示所有输出（默认）
hash-only	仅显示任务的哈希值
new-only	仅显示来自缓存未命中的输出
errors-only	仅显示来自任务失败的输出
none	隐藏所有任务输出

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".svelte-kit/**", "dist/**"],
      "outputMode": "new-only"
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

`persistent`

类型: boolean

如果任务是长时间运行的进程（例如开发服务器或 --watch 模式），则将其标记为 persistent。Turbo 将阻止其他任务依赖于持久性任务。如果不设置此配置，如果任何其他任务依赖于 dev，它将永远不会运行，因为 dev 永远不会退出。使用此选项，turbo 可以警告您有关无效配置的信息。

示例

{
  "$schema": "https://turbo.rust-lang.net.cn/schema.json",
  "pipeline": {
    "dev": {
      "persistent": true
    }
  }
}

`interactive`

类型: boolean

将任务标记为 interactive，使其能够接收来自 stdin 的输入。交互式任务必须标记为 "cache": false，因为它们从 stdin 接收的输入可能会改变任务的结果。

turbo 仅在连接到 TTY 且使用实验性 UI 时才会运行交互式任务。

路径的 Glob 规范

Turborepo 的 glob 实现允许您专门定义您希望 turbo 与之交互的文件。您将需要的最有用模式在下面的表格中

模式	描述
`*`	/
`**`	匹配目录中的所有文件
`/`	递归匹配所有文件和子目录
`some-dir/`	匹配 `some-dir` 目录，但不匹配其内容
`some-dir*`	匹配以 `some-dir` 开头的文件和目录
`*.js`	匹配目录中的所有 `.js` 文件
`*.{js,ts,tsx,jsx}`	匹配目录中以提供的扩展名结尾的所有文件
`!`	*.{js?x}

匹配目录中具有 js 和 jsx 扩展名的所有文件

模式	描述
`!`	否定整个 glob（自动将 `/**` 应用到定义的 glob 的末尾）
`以下是一些关于如何使用这些模式的示例`	dist/**
`匹配 dist 目录及其所有子目录中的所有文件`	dist/some-dir/**
`匹配当前目录中 dist/some-dir 目录及其所有子目录中的所有文件`	dist/some-dir/**
`dist/`	匹配 `dist` 目录，但不匹配其内容
`dist`	!dist
`忽略 dist 目录及其所有内容`	dist*
`匹配以 dist 开头的文件和目录`	dist/*.js
`匹配 dist 目录中的所有 .js 文件`	!dist/*.js
`忽略 dist 目录中的所有 .js 文件`	dist/*/.js

配置工作区 CLI 使用

配置选项 (`turbo.json`)

`globalDependencies`

`globalEnv`

`globalPassThroughEnv`

`globalDotEnv`

`extends类型：string[]`

`extends` 键仅在工作区配置中有效。它将在根目录的 `turbo.json` 中被忽略。阅读 文档以了解更多信息。

`experimentalUI`

`pipeline`

`dependsOn`

`dotEnv`

`env`

`passThroughEnv`

`outputs`

`cache`

`inputs`

`outputMode`

`persistent`

`interactive`

路径的 Glob 规范

资源

Turborepo

Turbopack

公司

法律

支持

配置选项 (turbo.json)

globalDependencies

globalEnv

globalPassThroughEnv

globalDotEnv

extends类型：string[] extends 键仅在工作区配置中有效。它将在根目录的 turbo.json 中被忽略。阅读 文档以了解更多信息。

experimentalUI

pipeline

dependsOn

dotEnv

env

passThroughEnv

outputs

cache

inputs

outputMode

persistent

interactive

路径的 Glob 规范

配置选项 (`turbo.json`)

`globalDependencies`

`globalEnv`

`globalPassThroughEnv`

`globalDotEnv`

`extends类型：string[]`

`extends` 键仅在工作区配置中有效。它将在根目录的 `turbo.json` 中被忽略。阅读文档以了解更多信息。

`experimentalUI`

`pipeline`

`dependsOn`

`dotEnv`

`env`

`passThroughEnv`

`outputs`

`cache`

`inputs`

`outputMode`

`persistent`

`interactive`