run

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

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

• [tasks]: Turborepo 可以同时运行一个或多个任务。要通过 turbo 运行任务，必须在 turbo.json 中指定。
• [options]: 选项用于控制 turbo run 命令的行为。可用标志选项在下面描述。
• [-- [args passed to tasks]]: 你也可以将参数传递给底层脚本。请注意，所有参数都将传递给 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 使用你的仓库的 lockfile 来确定缓存行为，软件包图等等。 因此，我们使用packageManager 字段来帮助你稳定你的 Turborepo。

为了帮助增量迁移或在你无法使用 packageManager 字段的情况下，你可以使用 --dangerously-disable-package-manager-check 来选择退出此检查，并承担不稳定的 lockfile 产生不可预测行为的风险。 禁用后，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 模式运行，而与其配置无关。

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 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 可以运行后台进程来预先计算用于确定需要完成的工作的值。 此独立进程 (daemon) 是一种优化，并非 turbo 正常运行所必需的。

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

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

--output-logs <option>

默认值：full

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

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 格式生成运行的跟踪，你可以使用它来分析性能。

你必须提供详细级别标志 (-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

远程缓存的 Bearer 令牌。 在非交互式 shell 中与 --team 标志结合使用时很有用。

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

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

--team

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

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