run

运行 turbo.json 中指定的任务。

¥Run tasks specified in turbo.json.

turbo run [tasks] [options] [-- [args passed to tasks]]

• [tasks]：Turborepo 可以同时运行一个或多个任务。要通过 turbo 运行任务，必须在 turbo.json 中指定该任务。

  ¥[tasks]: Turborepo can run one or many tasks at the same time. To run a task through turbo, it must be specified in turbo.json.

• [options]：选项用于控制 turbo run 命令的行为。可用的标志选项如下所述。

  ¥[options]: Options are used to control the behavior of the turbo run command. Available flag options are described below.

• [-- [传递给任务的参数]]:你也可以将参数传递给底层脚本。请注意，所有参数都将传递给运行命令中指定的所有任务。

  ¥[-- [args passed to tasks]]: You may also pass arguments to the underlying scripts. Note that all arguments will be passed to all tasks that are named in the run command.

如果没有提供任何任务，turbo 将显示存储库中包可用的任务。

¥If no tasks are provided, turbo will display what tasks are available for the packages in the repository.

turbo run

选项

¥Options

--affected

仅过滤受当前分支更改影响的包。

¥Filter to only packages that are affected by changes on the current branch.

turbo run build lint test --affected

默认情况下，该标志等效于 --filter=...[main...HEAD]。这从 Git 的角度考虑了 main 和 HEAD 之间的变化。

¥By default, the flag is equivalent to --filter=...[main...HEAD]. This considers changes between main and HEAD from Git's perspective.

你可以使用各自的 系统环境变量 覆盖默认基础包和头包。

¥You can override the default base and head with their respective System Environment Variables.

# Override Git comparison base
TURBO_SCM_BASE=development turbo run build --affected
 
# Override Git comparison head
TURBO_SCM_HEAD=your-branch turbo run build --affected

--cache <options>

默认：local:rw,remote:rw

¥Default: local:rw,remote:rw

指定运行的缓存源。接受以逗号分隔的选项列表：

¥Specify caching sources for the run. Accepts a comma-separated list of options:

• local：使用本地文件系统缓存

  ¥local: Use the local filesystem cache

• remote：使用远程缓存

  ¥remote: Use the Remote Cache

当省略缓存源时，读取和写入都将被禁用。

¥When a caching source is omitted, reading and writing are both disabled.

缓存源使用以下值：

¥Cache sources use the following values:

• rw：阅读并写入

  ¥rw: Read and write

• r：只读

  ¥r: Read only

• w：只写

  ¥w: Write only

• 无 (local:)：不使用缓存。相当于省略缓存源选项。

  ¥None (local:) : Does not use cache. Equivalent to omitting the cache source option.

# Read from and write to local cache. Only read from Remote Cache.
turbo run build --cache=local:rw,remote:r
 
# Only read from local cache. Read from and write to Remote Cache.
turbo run build --cache=local:r,remote:rw
 
# Read from and write to local cache. No Remote Cache activity.
turbo run build --cache=local:rw
 
# Do not use local cache. Only read from Remote Cache.
turbo run build --cache=local:,remote:r

--cache-dir <path>

默认：.turbo/cache

¥Default: .turbo/cache

指定文件系统缓存目录。

¥Specify the filesystem cache directory.

turbo run build --cache-dir="./my-cache"

也可以通过 TURBO_CACHE_DIR=example/path 系统变量设置相同的行为。

¥The same behavior can also be set via the TURBO_CACHE_DIR=example/path system variable.

--concurrency <number | percentage>

默认：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.

turbo run build --concurrency=50%
turbo run test --concurrency=5

--continue[=<option>]

默认：never

¥Default: never

指定 turbo 在出现错误（例如，任务的退出代码为非零）时应如何处理当前和待处理的任务。

¥Specify how turbo should handle current and pending tasks in the presence of an error (e.g. non-zero exit code from a task).

• 当 --continue=never 发生错误时，turbo 将取消所有任务。

  ¥When --continue=never and an error occurs, turbo will cancel all tasks.

• 当 --continue=dependencies-successful 发生错误时，turbo 将取消依赖任务。依赖已成功的任务将继续运行。

  ¥When --continue=dependencies-successful and an error occurs, turbo will cancel dependent tasks. Tasks whose dependencies have succeeded will continue to run.

• 当 --continue=always 发生错误时，turbo 将继续运行所有任务，即使是依赖失败的任务。

  ¥When --continue=always and an error occurs, turbo will continue running all tasks, even those whose dependencies have failed.

• 当 --continue 未指定值时，它将默认为 always。

  ¥When --continue is specified without a value, it will default to always.

在所有情况下，turbo 都将以执行期间遇到的最高退出代码值退出。

¥In all cases, turbo will exit with the highest exit code value encountered during execution.

turbo run build --continue

--cwd <path>

默认：根目录 turbo.json

¥Default: Directory of root turbo.json

设置命令的工作目录。

¥Set the working directory of the command.

turbo run build --cwd=./somewhere/else/in/your/repo

--dangerously-disable-package-manager-check

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 cannot 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.

--dry / --dry-run

显示将要运行的包和任务的详细信息，而不是执行任务。

¥Instead of executing tasks, display details about the packages and tasks that would be run.

指定 --dry=json 以获取 JSON 格式的输出。

¥Specify --dry=json to get the output in JSON format.

任务详细信息包含以下有用信息（列表并非详尽）：

¥Task details include useful information like (list is non-exhaustive):

--env-mode <option>

type: string

控制任务运行时可用的环境变量。

¥Controls the available environment variables in the task's runtime.

turbo run build --env-mode=loose

也可以通过 TURBO_ENV_MODE=strict 系统变量设置相同的行为。

¥The same behavior can also be set via the TURBO_ENV_MODE=strict system variable.

strict

只有以下键中指定的环境变量才可用于任务：

¥Only environment variables specified in the following keys are available to the task:

• env

• passThroughEnv

• globalEnv

• globalPassThroughEnv

如果指定或推断了严格模式，则所有任务都将以 strict 模式运行，无论其配置如何。

¥If Strict Mode is specified or inferred, all tasks are run in strict mode, regardless of their configuration.

loose

计算机上的所有环境变量都可供任务运行时使用。

¥All environment variables on the machine are made available to the task's runtime.

--filter <string>

从你的代码库图中指定要执行的目标。可以组合多个过滤器来选择不同的目标集。

¥Specify targets to execute from your repository's graph. Multiple filters can be combined to select distinct sets of targets.

可以组合使用过滤器来创建包、目录和 Git 提交的组合。

¥Filters can be combined to create combinations of packages, directories, and git commits.

用于过滤的微语法

¥Microsyntaxes for filtering

• !：从选择中取反目标。

  ¥!: Negate targets from the selection.

• ... 使用包：选择 软件包图表 中相对于目标的所有包。在包名称前使用 ... 将选择目标的依赖，而在包名称后使用 ... 将选择目标的依赖。

  ¥... using packages: Select all packages in the Package Graph relative to the target. Using ... before the package name will select dependents of the target while using ... after the package name will select dependencies of the target.

• ... 使用 Git 提交：使用 [<from commit>]...[<to commit>] 选择一个范围。

  ¥... using Git commits: Select a range using [<from commit>]...[<to commit>].

• ^：使用 ... 时，请从选择中省略目标。

  ¥^: Omit the target from the selection when using ....

有关过滤的深入讨论和实际用例，请访问 正在运行的任务页面。

¥For in-depth discussion and practical use cases of filtering, visit the Running Tasks page.

使用任务标识符

¥Using a task identifier

你还可以以 package-name#task-name 的格式为特定包运行特定任务。

¥You can also run a specific task for a specific package in the format of package-name#task-name.

turbo run web#lint

高级过滤示例

¥Advanced filtering examples

你可以组合多个过滤器以进一步优化你的目标。多个过滤器组合成一个联合体，取反的过滤器会从联合体的结果中删除相应的包。

¥You can combine multiple filters to further refine your targets. Multiple filters are combined as a union, with negated filters removing packages from the result of the union.

# Any packages in `apps` subdirectories that have changed since the last commit
turbo run build --filter={.apps/*}[HEAD^1]
 
# Any packages in `apps` subdirectories except ./apps/admin
turbo run build --filter=./apps/* --filter=!./apps/admin
 
# Run the build task for the docs and web packages
turbo run build --filter=docs --filter=web
 
# Build everything that depends on changes in branch 'my-feature'
turbo run build --filter=...[origin/my-feature]
 
# Build everything that depends on changes between two Git SHAs
turbo run build --filter=[a1b2c3d...e4f5g6h]
 
# Build '@acme/ui' if:
# - It or any of its dependencies have changed since the previous commit
turbo run build --filter=@acme/ui...[HEAD^1]
 
# Test each package that is:
# - In the '@acme' scope
# - Or, in the 'packages' directory
# - Or, changed since the previous commit
turbo run test --filter=@acme/*{./packages/*}[HEAD^1]

--force

忽略现有的缓存文件并重新执行所有任务。

¥Ignore existing cached artifacts and re-execute all tasks.

turbo run build --force

也可以通过 TURBO_FORCE 环境变量 设置相同的行为。

¥The same behavior can also be set via the TURBO_FORCE environment variable.

--framework-inference

默认：true

¥Default: true

指定是否对任务执行 框架推断。

¥Specify whether or not to do Framework Inference for tasks.

当 false 匹配时，自动环境变量包含 被禁用。

¥When false, automatic environment variable inclusion is disabled.

turbo run build --framework-inference=false

--global-deps <file glob>

指定要进行哈希处理的全局文件系统依赖。适用于 .env 以及根目录中影响多个包的文件。

¥Specify glob of global filesystem dependencies to be hashed. Useful for .env and files in the root directory that impact multiple packages.

turbo run build --global-deps=".env"
turbo run build --global-deps=".env.*" --global-deps=".eslintrc" --global-deps="jest.config.ts"

--graph <file type>

默认：jpg

¥Default: jpg

此命令将生成当前任务图的 svg、png、jpg、pdf、json、html 或 其他支持的输出格式。

¥This command will generate an svg, png, jpg, pdf, json, html, or other supported output formats of the current task graph.

如果未安装 Graphviz 或未提供文件名，此命令会将点图打印到 stdout。

¥If Graphviz is not installed, or no filename is provided, this command prints the dot graph to stdout.

turbo run build --graph
turbo run build test lint --graph=my-graph.svg

--log-order <option>

默认：auto

¥Default: auto

设置日志输出的顺序。

¥Set the ordering for log output.

默认情况下，turbo 将在 CI 环境中使用 grouped 日志，在其他地方使用 stream 日志。使用 终端 UI 时，此标志不适用。

¥By default, turbo will use grouped logs in CI environments and stream logs everywhere else. This flag is not applicable when using the terminal UI.

turbo run build --log-order=stream

--log-prefix <option>

默认：auto

¥Default: auto

控制运行任务时生成的日志行的 <package>:<task>: 前缀。

¥Control the <package>:<task>: prefix for log lines produced when running tasks.

turbo run dev --log-prefix=none

--no-cache

默认 false

¥Default false

不要缓存任务结果。

¥Do not cache results of the task.

turbo run dev --no-cache

--daemon 和 --no-daemon

¥--daemon and --no-daemon

turbo 可以运行后台进程，预先计算用于确定需要完成的工作的值。此独立进程（守护进程）是一种优化，并非 turbo 正常运行所必需的。

¥turbo can run a background process to pre-calculate values used for determining work that needs to be done. This standalone process (daemon) is an optimization, and not required for proper functioning of turbo.

使用 turbo.json 中的 daemon 字段 为你的存储库设置默认守护进程用法。传递 --daemon 要求 turbo 使用独立进程，而 --no-daemon 指示 turbo 避免使用或创建独立进程。

¥The default daemon usage is set for your repository using the daemon field in turbo.json. Passing --daemon requires turbo to use the standalone process, while --no-daemon instructs turbo to avoid using or creating the standalone process.

也可以通过 TURBO_DAEMON=true 系统变量设置相同的行为。

¥The same behavior can also be set via the TURBO_DAEMON=true system variable.

--output-logs <option>

默认：full

¥Default: full

设置输出日志类型，如果 turbo.json 中已定义，则覆盖 outputLogs。

¥Set type of output logging, overriding outputLogs if it's defined in turbo.json.

turbo run build --output-logs=errors-only

--only

默认：false

¥Default: false

限制执行仅包含指定的任务。

¥Restricts execution to include specified tasks only.

示例

¥Example

给定以下 turbo.json：

¥Given this turbo.json:

{
  "$schema": "https://turbo.nodejs.cn/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}

turbo run test --only

该命令将仅执行每个包中的 test 任务。它不会运行 build。

¥The command will only execute the test tasks in each package. It will not run build.

此外，--only 将仅运行指定包中的任务，不包括依赖。例如，turbo run build --filter=web --only 将仅运行 web 包中的 build 脚本。

¥Additionally, --only will only run tasks in specified packages, excluding dependencies. For example, turbo run build --filter=web --only, will only run the build script in the web package.

--parallel

默认：false

¥Default: false

在包之间并行运行命令，忽略任务依赖图。

¥Run commands in parallel across packages, ignoring the task dependency graph.

turbo run lint --parallel
turbo run dev --parallel

--preflight

仅在配置了远程缓存时适用。允许在每个缓存工件和分析请求之前发送预检请求。后续的上传和下载将遵循重定向。

¥Only applicable when Remote Caching is configured. Enables sending a preflight request before every cache artifact and analytics request. The follow-up upload and download will follow redirects.

turbo run build --preflight

也可以通过 TURBO_PREFLIGHT=true 系统变量设置相同的行为。

¥The same behavior can also be set via the TURBO_PREFLIGHT=true system variable.

--profile

以 Chrome Tracing 格式生成运行跟踪，你可以使用它来分析性能。

¥Generates a trace of the run in Chrome Tracing format that you can use to analyze performance.

你必须使用 --profile 提供详细程度标志（-v、-vv 或 -vvv）才能生成跟踪。

¥You must provide a verbosity flag (-v, -vv, or -vvv) with --profile to produce a trace.

turbo run build --profile=profile.json -vvv

配置文件可以在 Perfetto 等工具中查看。

¥Profiles can be viewed in a tool like Perfetto.

--remote-cache-timeout

默认：30

¥Default: 30

设置远程缓存操作的超时时间（以秒为单位）。

¥Set the timeout for Remote Cache operations in seconds.

turbo run build --remote-cache-timeout=60

--remote-only

默认：false

¥Default: false

忽略所有任务的本地文件系统缓存，使用远程缓存读取和缓存任务输出。

¥Ignore the local filesystem cache for all tasks, using Remote Cache for reading and caching task outputs.

turbo run build --remote-only

--summarize

在 .turbo/runs 中生成一个包含运行元数据的 JSON 文件，其中包括：

¥Generates a JSON file in .turbo/runs containing metadata about the run, including:

• 受影响的软件包

  ¥Affected packages

• 已执行的任务（包括其时间和哈希值）

  ¥Executed tasks (including their timings and hashes)

• 缓存的 artifact 中包含的所有文件

  ¥All the files included in the cached artifact

turbo run build --summarize

此标志有助于调试以确定以下事项：

¥This flag can be helpful for debugging to determine things like:

• turbo 如何解释 inputs 和 outputs 的 glob 语法

  ¥How turbo interpreted your glob syntax for inputs and outputs

• 两次任务运行之间哪些输入发生了变化会导致缓存未命中？

  ¥What inputs changed between two task runs to produce a cache miss

• 任务时间如何随时间变化

  ¥How task timings changed over time

--token

用于远程缓存的承载令牌。与 --team 标志结合使用，在非交互式 shell 中运行非常有用。

¥A bearer token for Remote Caching. Useful for running in non-interactive shells in combination with the --team flag.

turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx

此值也可以使用 TURBO_TOKEN 系统变量 设置。如果两者都存在，则标志值将覆盖系统变量。

¥This value can also be set using the TURBO_TOKEN system variable. If both are present, the flag value will override the system variable.

--team

远程缓存团队的 slug。与 --token 标志结合使用，在非交互式 shell 中运行非常有用。

¥The slug of the Remote Cache team. Useful for running in non-interactive shells in combination with the --token flag.

turbo run build --team=my-team
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx

此值也可以使用 TURBO_TEAM 系统变量 设置。如果两者都存在，则标志值将覆盖系统变量。

¥This value can also be set using the TURBO_TEAM system variable. If both are present, the flag value will override the system variable.

--ui

指定用于输出的 UI。接受 stream 或 tui。

¥Specify the UI to use for output. Accepts stream or tui.

--verbosity

要指定日志级别，请使用 --verbosity=<num> 或 -v, -vv, -vvv。

¥To specify log level, use --verbosity=<num> or -v, -vv, -vvv.

turbo run build --verbosity=2
turbo run build -vvv