正在运行任务

Turborepo 通过自动并行化和缓存任务来优化存储库中的开发者工作流程。将任务配置为 在 turbo.json 中注册 后，你将拥有一个强大的新工具集，用于运行存储库中的脚本：

¥Turborepo optimizes the developer workflows in your repository by automatically parallelizing and caching tasks. Once a task is registered in turbo.json, you have a powerful new toolset for running the scripts in your repository:

• 在 package.json 中使用 scripts 执行需要经常运行的任务

  ¥Use scripts in package.json for tasks you need to run often

• 使用全局 turbo 快速按需运行自定义任务

  ¥Use global turbo to quickly run custom tasks on-demand

• 按目录、包名称、源代码控制更改等过滤任务

  ¥Filter tasks by directories, package names, source control changes, and more

通过 turbo 运行任务非常强大，因为你可以获得一个模型，用于在开发和 CI 流水线中执行整个存储库的工作流。

¥Running tasks through turbo is powerful because you get one model for executing workflows throughout your repository in development and in your CI pipelines.

在 package.json 中使用 scripts

¥Using scripts in package.json

对于你经常运行的任务，你可以将 turbo 命令直接写入根 package.json。

¥For tasks that you run frequently, you can write your turbo commands directly into your root package.json.

{
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint"
  }
}

然后可以使用你的包管理器运行这些脚本。

¥These scripts can then be run using your package manager.

pnpm dev

使用全局 turbo

¥Using global turbo

全局安装 turbo 允许你直接从终端运行命令。这可以改善你的本地开发体验，因为它可以让你在需要时更轻松地运行所需的内容。

¥Installing turbo globally lets you run commands directly from your terminal. This improves your local development experience since it makes it easier to run exactly what you need, when you need it.

此外，全局 turbo 在你的 CI 流水线中非常有用，它可以让你最大限度地控制在流水线的每个点上要运行哪些任务。

¥Additionally, global turbo is useful in your CI pipelines, giving you maximum control of exactly which tasks to run at each point in your pipeline.

自动确定软件包作用域

¥Automatic Package Scoping

当你在某个包的目录中时，turbo 会自动将命令范围限定在该包的 软件包图表 上。这意味着你可以快速编写命令，而无需对包进行 编写过滤器。

¥When you're in a package's directory, turbo will automatically scope commands to the Package Graph for that package. This means you can quickly write commands without having to write filters for the package.

cd apps/docs
turbo build

在上面的示例中，turbo build 命令将使用在 turbo.json 中注册的 build 任务为 docs 包运行 build 任务。

¥In the example above, the turbo build command will run the build task for the docs package using the build task registered in turbo.json.

自定义行为

¥Customizing behavior

在 run 子命令文档 中，你会发现许多有用的标志，可以根据你的需要定制 turbo run 的行为。运行全局 turbo 时，你可以使用以下工作流程加快速度：

¥In the documentation for the run subcommand, you'll find many useful flags to tailor the behavior of turbo run for what you need. When running global turbo, you can go faster using workflows like:

• 最常用命令的变体：package.json 中的 build 脚本在 turbo build 中最为实用。 - 但你目前可能只对特定的软件包感兴趣。你可以使用 turbo build --filter=@repo/ui 快速筛选你感兴趣的特定包。

  ¥Variations of your most common commands: The build script in package.json has the most utility when it is turbo build - but you might only be interested in a specific package at the moment. You can quickly filter for the specific package you're interested in using turbo build --filter=@repo/ui.

• 一次性命令：像 turbo build --dry 这样的命令并不常用，因此你可能不会在 package.json 中为其创建脚本。相反，你可以在需要时直接在终端中运行它。

  ¥One-off commands: Commands like turbo build --dry aren't needed often so you likely won't create a script in your package.json for it. Instead, you can run it directly in your terminal whenever you need it.

• 覆盖 turbo.json 配置：某些 CLI 参数在 turbo.json 中有等效项，你可以覆盖它们。例如，你可能已将 turbo build 命令配置为使用 turbo.json 中的 "outputLogs": "full"。 - 但你目前只想查看错误。使用全局 turbo，你可以使用 turbo lint --output-logs=errors-only 仅显示错误。

  ¥Overriding turbo.json configuration: Some CLI flags have an equivalent in turbo.json that you can override. For instance, you may have a turbo build command configured to use "outputLogs": "full" in turbo.json - but you're only interested in seeing errors at the moment. Using global turbo, you can use turbo lint --output-logs=errors-only to only show errors.

运行多个任务

¥Running multiple tasks

turbo 能够运行多个任务，并尽可能并行执行。

¥turbo is able to run multiple tasks, parallelizing whenever possible.

turbo run build test lint check-types

此命令将运行所有任务，并根据你的任务定义自动检测可以尽早运行脚本的位置。

¥This command will run all of the tasks, automatically detecting where it can run a script as early as possible, according to your task definitions.

使用过滤器

¥Using filters

caching 确保你不会重复执行相同的工作，从而保持快速运行，你还可以过滤任务以仅运行 任务图 的子集。

¥While caching ensures you stay fast by never doing the same work twice, you can also filter tasks to run only a subset of the Task Graph.

--filter API 参考 中有很多用于过滤的高级用例，但下面讨论的是最常见的用例。

¥There are many advanced use cases for filtering in the --filter API reference but the most common use cases are discussed below.

按软件包过滤

¥Filtering by package

按包过滤是一种简单的方法，可以仅针对你当前正在处理的包运行任务。

¥Filtering by package is a simple way to only run tasks for the packages you're currently working on.

turbo build --filter=@acme/web

你也可以直接在 CLI 命令中筛选包的特定任务，而无需使用 --filter：

¥You can also filter to a specific task for the package directly in your CLI command without needing to use --filter:

# Run the `build` task for the `web` package
turbo run web#build
 
# Run the `build` task for the `web` package, and the `lint` task for the `docs` package
turbo run web#build docs#lint

按目录过滤

¥Filtering by directory

你的代码库可能具有一个目录结构，其中相关的包被分组在一起。在这种情况下，你可以捕获该目录的全局变量，以便将 turbo 集中在这些包上。

¥Your repository might have a directory structure where related packages are grouped together. In this case, you can capture the glob for that directory to focus turbo on those packages.

turbo lint --filter="./packages/utilities/*"

过滤以包含依赖

¥Filtering to include dependents

当你处理特定包时，你可能需要为该包及其依赖运行任务。当你更改包并希望确保更改不会破坏其任何依赖时，... 微语法非常有用。

¥When you're working on a specific package, you might want to run tasks for the package and its dependents. The ... microsyntax is useful when you're making changes to a package and want to ensure that the changes don't break any of its dependents.

turbo build --filter=...ui

过滤以包含依赖

¥Filtering to include dependencies

要将范围限制在某个包及其依赖，请在包名称后附加 ...。这会为指定的包及其依赖的所有包运行任务。

¥To limit the scope to a package and its dependencies, append ... to the package name. This runs the task for the specified package and all packages it depends on.

turbo dev --filter=web...

按源代码控制更改过滤

¥Filtering by source control changes

使用过滤器根据源代码控制中的更改运行任务，是仅针对受更改影响的包运行任务的好方法。源代码控制过滤器必须封装在 [] 中。

¥Using filters to run tasks based on changes in source control is a great way to run tasks only for the packages that are affected by your changes. Source control filters must be wrapped in [].

• 与上一个提交比较：turbo build --filter=[HEAD^1]

  ¥Comparing to the previous commit: turbo build --filter=[HEAD^1]

• 与主分支比较：turbo build --filter=[main...my-feature]

  ¥Comparing to the main branch: turbo build --filter=[main...my-feature]

• 使用 SHA 比较特定提交：turbo build --filter=[a1b2c3d...e4f5g6h]

  ¥Comparing specific commits using SHAs: turbo build --filter=[a1b2c3d...e4f5g6h]

• 使用分支名称比较特定提交：turbo build --filter=[your-feature...my-feature]

  ¥Comparing specific commits using branch names: turbo build --filter=[your-feature...my-feature]

合并过滤器

¥Combining filters

为了更加明确，你可以组合使用过滤器来进一步优化 任务图 的入口点。

¥For even more specificity, you can combine filters to further refine the entrypoints into your Task Graph.

turbo build --filter=...ui --filter={./packages/*} --filter=[HEAD^1]

多个过滤器组合成一个联合体，这意味着 任务图 将包含与任意过滤器匹配的任务。更多有关过滤器高级用法的信息，请参阅 --filter API 参考。

¥Multiple filters are combined as a union, meaning that the Task Graph will include tasks that match any of the filters. For more information on advanced usage of filters, see the --filter API reference.

后续步骤

¥Next steps

当你开始在代码库中运行任务时，你可能会注意到任务速度变快了。接下来，你将探索 caching 以及 turbo 如何让你避免重复工作。

¥When you start running tasks in your repository, you might start noticing that your tasks get faster. Next, you'll explore caching and how turbo makes it so you never do the same work twice.