Turborepo
API 参考

包配置

许多 Monorepo 可以在根目录中声明一个 turbo.json，其中包含一个适用于所有包的任务描述。但是，有时，Monorepo 可能包含需要以不同方式配置其任务的包。

为了适应这种情况，Turborepo 允许您在任何包中使用 turbo.json 扩展根配置。这种灵活性使得更多样化的应用程序和包能够在工作区中并存，并允许包的所有者维护专门的任务和配置，而不会影响 Monorepo 的其他应用程序和包。

工作原理

要覆盖根 turbo.json 中定义的任何任务的配置，请在您的 Monorepo 的任何包中添加一个 turbo.json 文件，并包含一个顶级的 extends 键

./apps/my-app/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "build": {
      // Custom configuration for the build task in this package
    },
    "special-task": {} // New task specific to this package
  }
}

目前，extends 键的唯一有效值是 ["//"]。// 是一个特殊名称，用于标识 Monorepo 的根目录。

包中的配置可以覆盖任务的任何配置。任何未包含的键都将从扩展的 turbo.json 继承。

示例

一个工作区中的不同框架

假设您的 Monorepo 有多个 Next.js 应用程序和一个 SvelteKit 应用程序。这两个框架都在各自的 package.json 中使用 build 脚本创建其构建输出。您可以配置 Turborepo 以在根目录使用单个 turbo.json 来运行这些任务，如下所示

./turbo.json
{
  "tasks": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"]
    }
  }
}

请注意，即使 Next.js 应用程序不生成 .svelte-kit 目录，反之亦然，也需要将 .next/** 和 .svelte-kit/** 指定为outputs。

使用包配置，您可以改为在 SvelteKit 包的 apps/my-svelte-kit-app/turbo.json 中添加自定义配置

./apps/my-svelte-kit-app/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": [".svelte-kit/**"]
    }
  }
}

并从根配置中删除特定于 SvelteKit 的outputs

./turbo.json
{
  "tasks": {
    "build": {
-      "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"]
+      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

这不仅使每个配置更易于阅读，还将配置放置在更接近其使用位置的地方。

专门的任务

在另一个示例中，假设一个包中的 build 任务 dependsOn 一个 compile 任务。您可以将其普遍声明为 dependsOn: ["compile"]。这意味着您的根 turbo.json 必须有一个空的 compile 任务条目

./turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["compile"]
    },
    "compile": {}
  }
}

使用包配置，您可以将 compile 任务移动到 apps/my-custom-app/turbo.json 中，

./apps/my-app/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "build": {
      "dependsOn": ["compile"]
    },
    "compile": {}
  }
}

并将其从根目录中删除

./turbo.json
{
  "tasks": {
+    "build": {}
-    "build": {
-      "dependsOn": ["compile"]
-    },
-    "compile": {}
  }
}

现在，my-app 的所有者可以完全拥有其 build 任务的所有权，但继续继承根目录中定义的任何其他任务。

与特定于包的任务的比较

乍一看，包配置可能听起来很像根 turbo.json 中的package#task 语法。这些功能类似，但有一个显着差异：当您在根 turbo.json 中声明特定于包的任务时，它会完全覆盖基线任务配置。使用包配置，任务配置是合并的。

再次考虑具有多个 Next.js 应用程序和一个 Sveltekit 应用程序的 Monorepo 示例。使用特定于包的任务，您可能会像这样配置您的根 turbo.json

./turbo.json
{
  "tasks": {
    "build": {
      "outputLogs": "hash-only",
      "inputs": ["src/**"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "my-sveltekit-app#build": {
      "outputLogs": "hash-only", // must duplicate this
      "inputs": ["src/**"], // must duplicate this
      "outputs": [".svelte-kit/**"]
    }
  }
}

在此示例中，my-sveltekit-app#build 完全覆盖了 Sveltekit 应用程序的 build，因此还需要复制 outputLogs 和 inputs。

使用包配置，outputLogs 和 inputs 是继承的，因此您不需要复制它们。您只需要在 my-sveltekit-app 配置中覆盖 outputs。

尽管没有计划删除特定于包的任务配置，但我们希望包配置可以用于大多数用例。

局限性

尽管总体思路与根 turbo.json 相同，但包配置带有一组防护措施，可以防止包创建可能令人困惑的情况。

包配置不能使用workspace#task 语法作为任务条目

package 是根据配置的位置推断出来的，并且无法更改另一个包的配置。例如，在 my-nextjs-app 的包配置中

./apps/my-nextjs-app/turbo.json
{
  "tasks": {
    "my-nextjs-app#build": {
      // ❌ This is not allowed. Even though it's
      // referencing the correct package, "my-nextjs-app"
      // is inferred, and we don't need to specify it again.
      // This syntax also has different behavior, so we do not want to allow it.
      // (see "Comparison to package-specific tasks" section)
    },
    "my-sveltekit-app#build": {
      // ❌ Changing configuration for the "my-sveltekit-app" package
      // from Package Configuration in "my-nextjs-app" is not allowed.
    },
    "build": {
      // ✅ just use the task name!
    }
  }
}

请注意，build 任务仍然可以依赖于特定于包的任务

./apps/my-nextjs-app/turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["some-pkg#compile"] 
    }
  }
}

包配置只能覆盖 tasks 键中的值

无法在包配置中覆盖全局配置，例如 globalEnv 或 globalDependencies。需要在包配置中更改的配置不是真正的全局配置，应该以不同的方式进行配置。

根 turbo.json 不能使用 extends 键

为了避免在包上创建循环依赖关系，根 turbo.json 不能从任何东西扩展。extends 键将被忽略。

故障排除

在大型 Monorepo 中，有时可能难以理解 Turborepo 如何解释您的配置。为了提供帮助，我们已将 resolvedTaskDefinition 添加到Dry Run 输出中。例如，如果您运行 turbo run build --dry-run，则输出将包括在运行 build 任务之前考虑的所有 turbo.json 配置的组合。

上一个

配置 turbo.json

下一个

系统环境变量

小时

节省的总计算量
开始使用
远程缓存 →

本页内容

工作原理示例一个工作区中的不同框架专门的任务与特定于包的任务的比较局限性包配置不能使用 workspace#task 语法作为任务条目包配置只能覆盖 tasks 键中的值根 turbo.json 不能使用 extends 键故障排除