設定工作區

大多數單一儲存庫可以在根目錄中宣告一個 turbo.json，其中包含套用於所有工作區的統一 管線。有時，單一儲存庫可能包含需要以不同方式設定其任務的工作區。為了適應這種情況，從 1.8 版開始，Turborepo 讓您可以在任何工作區中使用 turbo.json 來擴充根目錄設定。這種彈性讓更多樣化的應用程式和套件得以共存，並允許工作區擁有者維護專門的任務和設定，而不會影響單一儲存庫的其他應用程式和套件。

運作方式

若要覆寫根目錄 turbo.json 中定義的任何任務設定，請在單一儲存庫的任何工作區中新增一個 turbo.json 檔案，其中包含頂層 extends 鍵

{
  "extends": ["//"],
  "pipeline": {
    "build": {
      // custom configuration for the build task in this workspace
    },
    // new tasks only available in this workspace
    "special-task": {},
  }
}

工作區中的設定可以覆寫 管線任務設定 中的任何設定。如果您未包含鍵，設定將從擴充的 turbo.json 繼承。

範例

為了說明，讓我們來看一些使用案例。

不同的框架

假設你的單一儲存庫有多個 Next.js（在新分頁中開啟） 應用程式，以及一個 SvelteKit（在新分頁中開啟） 應用程式。這兩個框架都會在各自的 package.json 中使用 build 指令建立建置輸出。你可以設定 Turborepo 在根目錄使用單一 turbo.json 執行這些工作，如下所示

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

請注意，.next/** 和 .svelte-kit/** 都需要指定為 outputs，即使 Next.js 應用程式不會產生 .svelte-kit 目錄，反之亦然。使用工作區設定，你可以改為在 apps/my-svelte-kit-app/turbo.json 中新增 SvelteKit 工作區的客製化設定

{
  "extends": ["//"],
  "pipeline": {
    "build": {
      "outputs": [".svelte-kit/**"]
    }
  }
}

並移除根設定中的設定

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

這不僅讓每個設定更容易閱讀，也讓設定更接近使用的地方。

特殊工作

在另一個範例中，假設一個工作區中的 build 任務 dependsOn 一個 compile 任務。你可以普遍宣告它為 dependsOn: ["compile"]。這表示你的根目錄 turbo.json 必須有一個空的 compile 任務項目

{
  "pipeline": {
    "build": {
      "dependsOn": ["compile"]
    },
    "compile": {}
  }
}

使用工作區設定，你可以將 compile 任務移到 apps/my-custom-app/turbo.json，

{
  "extends": ["//"],
  "pipeline": {
    "build": {
      "dependsOn": ["compile"]
    },
    "compile": {}
  }
}

並從根目錄移除它

{
  "pipeline": {
+    "build": {}
-    "build": {
-      "dependsOn": ["compile"]
-    },
-    "compile": {}
  }
}

現在，my-app 的擁有者可以完全擁有他們的 build 任務，但繼續繼承在根目錄定義的任何其他任務。

與工作區特定任務的比較

乍看之下，Workspace 組態聽起來很像根目錄中的 workspace#task 語法。這些功能類似，但有一個重要的差異：當您在根目錄中宣告 Workspace 專用時 turbo.json，它會完全覆寫基線任務組態。使用 Workspace 組態時，任務組態會合併。

再次考慮包含多個 Next.js 應用程式和 Sveltekit 應用程式的單一儲存庫範例。在沒有 Workspace 專用任務的情況下，您可能會像這樣組態根目錄 turbo.json

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

在此範例中，my-sveltekit-app#build 會完全覆寫 Sveltekit 應用程式的 build，因此 outputMode 和 inputs 也需要重複。

使用 Workspace 組態時，outputMode 和 inputs 會繼承，因此您不需要重複它們。您只需要覆寫 outputs my-sveltekit-app 組態。

限制

儘管一般概念與根目錄 turbo.json 相同，但工作區設定會附帶一組防護措施，可防止工作區產生混淆的情況。這些防護措施會在此列出，以明確表示它們是有意的，而非意外

• 工作區設定無法使用 workspace#task 語法 作為管線項目

  workspace 會根據設定的位置推論，而且無法變更其他工作區的設定。例如，在「my-nextjs-app」的工作區設定中

  {
    "pipeline": {
      "my-nextjs-app#build": {
        // ❌ This is not allowed. Even though it's
        // referencing the correct workspace, "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 Workspace-specific tasks" section)
      },
      "my-sveltekit-app#build": {
        // ❌ Changing configuration for the "my-sveltekit-app" workspace
        // from Workspace Configuration in "my-nextjs-app" is not allowed.
      },
      "build": {
        // ✅ just use the task name!
      },
    }
  }

  請注意， build 任務仍然可以依賴於特定工作區的任務

  {
    "pipeline": {
      "build": {
        // ✅ It's still ok to have workspace#task in dependsOn!
        "dependsOn": ["some-pkg#compile"]
      },
    }
  }

• 工作區設定無法覆寫 pipeline 鍵以外的任何內容。

  例如，無法覆寫 globalEnv 或 globalDependencies。我們預期 monorepo 所有者應該絕對控制這一點，而且如果此設定並非真正全域，則不應這樣設定。

• 根目錄 turbo.json 無法使用 extends 鍵。

  為了避免在工作區上建立循環依賴，根目錄 turbo.json 無法延伸任何內容。

如果您有上述任一項目的使用案例，請 提交問題（在新分頁中開啟）！

疑難排解

在大型單一儲存庫中，有時難以理解 Turborepo 如何詮釋您的組態。為了提供協助，我們已將 resolvedTaskDefinition 加入到空跑輸出中。例如，如果您執行 turbo run build --dry-run，輸出將包含在執行 build 任務之前考慮的所有 turbo.json 組態的組合。