run

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

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

• [任务]：Turborepo 可以同时运行一个或多个任务。要通过 turbo 运行任务，必须在 turbo.json 中指定该任务。
• [选项]：选项用于控制 turbo run 命令的行为。下面描述了可用的标志选项。
• [-- [传递给任务的参数]]：您也可以将参数传递给底层脚本。请注意，所有参数都将传递给运行命令中命名的所有任务。

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

turbo run

选项

--affected

仅筛选受当前分支更改影响的软件包。

turbo run build lint test --affected

默认情况下，该标志等同于 --filter=...[main...HEAD]。这会从 Git 的角度考虑 main 和 HEAD 之间的更改。

您可以使用各自的系统环境变量覆盖默认的 base 和 head。

# 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

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

• local：使用本地文件系统缓存。
• remote：使用远程缓存。

如果省略缓存源，则禁用读写。

缓存源使用以下值：

• rw：读写
• r：只读
• w：只写
• 无（local:）：不使用缓存。等同于省略缓存源选项。

# 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

指定文件系统缓存目录。

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

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

--concurrency <number | percentage>

默认值：10

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

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

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

--continue[=<option>]

默认值：never

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

• 当 --continue=never 且发生错误时，turbo 将取消所有任务。
• 当 --continue=dependencies-successful 且发生错误时，turbo 将取消依赖任务。依赖项已成功的任务将继续运行。
• 当 --continue=always 且发生错误时，turbo 将继续运行所有任务，即使是依赖项已失败的任务。
• 当未指定值时指定 --continue，它将默认为 always。

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

turbo run build --continue

--cwd <path>

默认值：根 turbo.json 的目录

设置命令的工作目录。

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

--dangerously-disable-package-manager-check

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

为了帮助增量迁移或在无法使用 packageManager 字段的情况下，您可以使用 --dangerously-disable-package-manager-check 选项跳过此检查，并承担不稳定锁文件导致不可预测行为的风险。禁用后，Turborepo 将尽力发现存储库所需的包管理器。

--dry / --dry-run

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

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

任务详细信息包括有用信息（列表不详尽）

--env-mode <option>

类型：字符串

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

turbo run build --env-mode=loose

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

strict

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

• env
• passThroughEnv
• globalEnv
• globalPassThroughEnv

如果指定或推断出 Strict Mode，所有任务都将在 strict 模式下运行，无论其配置如何。

loose

机器上的所有环境变量都可用于任务的运行时。

--filter <string>

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

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

过滤的微语法

• !：从选择中否定目标。
• ... 使用包：选择包图中相对于目标的所有包。在包名称之前使用 ... 将选择目标的依赖项，而在包名称之后使用 ... 将选择目标的被依赖项。
• ... 使用 Git 提交：使用 [<from commit>]...[<to commit>] 选择范围。
• ^：使用 ... 时从选择中省略目标。

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

使用任务标识符

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

turbo run web#lint

高级过滤示例

您可以组合多个过滤器以进一步优化目标。多个过滤器以并集的形式组合，而否定过滤器从并集结果中移除包。

# 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

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

turbo run build --force

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

--framework-inference

默认值：true

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

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

turbo run build --framework-inference=false

--global-deps <file glob>

指定要进行哈希的全局文件系统依赖项的 glob。对于 .env 和影响多个包的根目录中的文件很有用。

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

--graph <file name>

默认值：dot

此命令可以输出图形文件：svg、png、jpg、pdf、json、html、mermaid 或 dot。

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

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

--log-order <option>

默认值：auto

设置日志输出的排序。

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

turbo run build --log-order=stream

--log-prefix <option>

默认值：auto

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

turbo run dev --log-prefix=none

--no-cache

默认 false

不缓存任务结果。

turbo run dev --no-cache

--daemon 和 --no-daemon

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

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

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

--output-logs <option>

默认值：full

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

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

--only

默认值：false

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

示例

给定此 turbo.json

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

turbo run test --only

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

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

--parallel

默认值：false

跨包并行运行命令，忽略任务依赖图。

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

--preflight

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

turbo run build --preflight

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

--profile

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

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

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

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

--remote-cache-timeout

默认值：30

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

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

--remote-only

默认值：false

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

turbo run build --remote-only

--summarize

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

• 受影响的包
• 已执行的任务（包括其时间安排和哈希）
• 缓存工件中包含的所有文件

turbo run build --summarize

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

• turbo 如何解释您的 inputs 和 outputs 的 glob 语法
• 两次任务运行之间哪些输入发生了变化导致缓存未命中
• 任务时间如何随时间变化

--token

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

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

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

--team

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

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

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

--ui

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

--verbosity

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

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