turbo 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>

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

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

--graph <file type>

默认值：jpg

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

如果未安装 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://turbo.build/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 的全局语法
• 两次任务运行之间的哪些输入发生了变化，从而产生缓存未命中
• 任务计时如何随时间变化

--token

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

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

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

--team

远程缓存团队的短名称。与 --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