run

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

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

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

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

turbo run

选项

--affected

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

turbo run build lint test --affected

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

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

# 覆盖 Git 比较基础
TURBO_SCM_BASE=development turbo run build --affected

# 覆盖 Git 比较头部
TURBO_SCM_HEAD=your-branch turbo run build --affected

--cache <options>

默认值: local:rw,remote:rw

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

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

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

缓存源使用以下值：

• rw: 读取和写入
• r: 只读
• w: 只写
• 无 (local:): 不使用缓存。等同于省略缓存源选项。

# 从本地缓存读取和写入。仅从远程缓存读取。
turbo run build --cache=local:rw,remote:r

# 仅从本地缓存读取。从远程缓存读取和写入。
turbo run build --cache=local:r,remote:rw

# 从本地缓存读取和写入。无远程缓存活动。
turbo run build --cache=local:rw

# 不使用本地缓存。仅从远程缓存读取。
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>

type: string

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

turbo run build --env-mode=loose

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

strict

仅在以下键中指定的环境变量对任务可用：

• env
• passThroughEnv
• globalEnv
• globalPassThroughEnv

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

loose

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

--filter <string>

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

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

过滤的微语法

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

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

使用任务标识符

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

turbo run web#lint

高级过滤示例

您可以组合多个过滤器来进一步细化您的目标。多个过滤器作为联合组合，否定过滤器从联合结果中删除包。

# apps 子目录中自上次提交以来已更改的任何包
turbo run build --filter={.apps/*}[HEAD^1]

# apps 子目录中除 ./apps/admin 之外的任何包
turbo run build --filter=./apps/* --filter=!./apps/admin

# 为 docs 和 web 包运行构建任务
turbo run build --filter=docs --filter=web

# 构建依赖于 'my-feature' 分支中更改的所有内容
turbo run build --filter=...[origin/my-feature]

# 构建依赖于两个 Git SHA 之间更改的所有内容
turbo run build --filter=[a1b2c3d...e4f5g6h]

# 如果满足以下条件，构建 '@acme/ui'：
# - 它或其任何依赖项自上次提交以来已更改
turbo run build --filter=@acme/ui...[HEAD^1]

# 测试每个满足以下条件的包：
# - 在 '@acme' 范围内
# - 或者，在 'packages' 目录中
# - 或者，自上次提交以来已更改
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，或未提供文件名，此命令将 dot 图打印到 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://turborepo.com/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 格式的运行跟踪，您可以使用它来分析性能。

您必须提供详细程度标志（-v、-vv 或 -vvv）与 --profile 一起使用以产生跟踪。

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