設定 turbo.json

透過在 Workspace 的根目錄中新增 turbo.json 檔案，來設定 turbo 的行為。

變更您的根目錄 turbo.json 檔案將會使所有任務的快取失效，因為它被視為全域雜湊的一部分。如果您想要在不影響全域雜湊的情況下變更設定的彈性，請使用套件設定。

全域選項

`extends`

./apps/web/turbo.json

{
  "extends": ["//"]
}

從根目錄 turbo.json 延伸，以使用套件設定為套件建立特定設定。

extends 的唯一有效值為 ["//"]，以繼承來自根目錄 turbo.json 的設定。
如果在根目錄 turbo.json 中使用 extends，它將會被忽略。

`globalDependencies`

./turbo.json

{
  "globalDependencies": [".env", "tsconfig.json"]
}

您想要包含在所有任務雜湊中的 glob 清單。如果任何符合這些 glob 的檔案變更，所有任務都會錯失快取。Glob 相對於 turbo.json 的位置。

預設情況下，Workspace 根目錄中原始碼控制中的所有檔案都會包含在全域雜湊中。

Glob 必須位於儲存庫的原始碼控制根目錄中。不支援儲存庫外部的 Glob。

`globalEnv`

./turbo.json

{
  "globalEnv": ["GITHUB_TOKEN", "PACKAGE_VERSION", "NODE_ENV"]
}

您想要影響所有任務雜湊的環境變數清單。對這些環境變數的任何變更都會導致所有任務錯失快取。

如需關於萬用字元和否定語法，請參閱 env 區段。

`globalPassThroughEnv`

./turbo.json

{
  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
}

您想要提供給任務使用的環境變數清單。使用此鍵會讓所有任務都選擇加入嚴格環境變數模式。

此外，Turborepo 具有內建的全域傳遞變數集，適用於常見情況，例如作業系統環境變數。這包含像 HOME、PATH、APPDATA、SHELL、PWD 等變數。完整的清單可以在原始碼中找到。

傳遞值不會影響快取的雜湊

如果您希望這些變數的變更導致快取錯失，您需要將它們包含在env 或 globalEnv 中。

`ui`

預設值："stream"

為儲存庫選取終端機 UI。

"tui" 允許一次檢視每個日誌並與任務互動。"stream" 會在日誌傳入時輸出，且不具互動性。

終端機

{
  "ui": "tui" | "stream"
}

`dangerouslyDisablePackageManagerCheck`

預設值：false

Turborepo 使用您儲存庫的鎖定檔來判斷快取行為、套件圖等等。因此，我們使用packageManager 欄位來協助您穩定 Turborepo。

為了協助增量移轉或在您無法使用 packageManager 欄位的情況下，您可以使用 --dangerously-disable-package-manager-check 來選擇退出此檢查，並承擔不穩定的鎖定檔產生不可預測行為的風險。停用時，Turborepo 將嘗試盡力探索儲存庫的預期套件管理器。

./turbo.json

{
  "dangerouslyDisablePackageManagerCheck": true
}

您也可以透過flag 或 TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK 環境變數選擇退出此檢查。

`cacheDir`

預設值：".turbo/cache"

指定檔案系統快取目錄。

./turbo.json

{
  "cacheDir": ".turbo/cache"
}

`daemon`

預設值：true

Turborepo 執行背景處理程序來預先計算一些耗時的操作。此獨立處理程序（守護程序）是一種效能最佳化，並非 turbo 正常運作的必要條件。

./turbo.json

{
  "daemon": true
}

小提示：

在 CI 環境中執行時，無論此設定為何，守護程序都會始終停用。

`envMode`

預設值："strict"

Turborepo 的環境模式可讓您控制哪些環境變數在執行時可供任務使用

"strict"：篩選環境變數，僅限於 turbo.json 中 env 和 globalEnv 鍵中指定的變數。
"loose"：允許進程的所有環境變數都可使用。

./turbo.json

{
  "envMode": "strict"
}

閱讀更多關於環境模式的資訊。

`tags` 實驗性功能

./apps/web/turbo.json

{
  "tags": ["utils"]
}

為套件新增標籤，以搭配邊界使用。

此鍵僅在套件設定中有效。在根目錄 turbo.json 中使用此鍵將會導致錯誤。

定義任務

`tasks`

tasks 物件中的每個鍵都是可由turbo run 執行的任務名稱。Turborepo 將會在您的Workspace 設定中描述的套件中搜尋 package.json 中具有任務名稱的腳本。

使用任務中描述的其餘設定，Turborepo 將會以描述的順序執行腳本，並在提供時將日誌和檔案輸出快取在outputs 鍵中。

在以下範例中，我們在 tasks 鍵下定義了三個任務：build、test 和 dev。

./turbo.json

{
  "$schema": "https://turbo.dev.org.tw/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "outputs": ["coverage/**"],
      "dependsOn": ["build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

任務選項

使用您在 tasks 中定義的任務中可用的選項，您可以描述 turbo 將如何執行您的任務。

`dependsOn`

在任務開始執行之前，需要完成的任務清單。

有三種類型的 dependsOn 關係：依賴關係、相同套件關係和任意任務關係。

依賴關係

在 dependsOn 中以 ^ 為字串加上前綴會告知 turbo，任務必須等待套件依賴項目中的任務先完成。例如，在下方的 turbo.json 中

./turbo.json

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

turbo 從套件圖的「底部」開始，並遞迴地走訪每個套件，直到找到沒有內部依賴項目的套件。然後，它將首先在依賴鏈的末端執行 build 任務，再往回「頂端」進行，直到所有 build 任務都依序完成。

相同套件關係

不含 ^ 前綴的任務名稱描述一個任務，該任務依賴於相同套件內的不同任務。例如，在下方的 turbo.json 中

./turbo.json

{
  "tasks": {
    "test": {
      "dependsOn": ["lint", "build"]
    }
  }
}

test 任務只會在 lint 和 build 任務完成在相同套件中後執行。

任意任務關係

指定特定套件任務之間的任務依賴關係。

./turbo.json

{
  "tasks": {
    "web#lint": {
      "dependsOn": ["utils#build"]
    }
  }
}

在此 turbo.json 中，web#lint 任務將會等待 utils#build 任務完成。

`env`

任務依賴的環境變數清單。

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["DATABASE_URL"] // Impacts hash of all build tasks
    },
    "web#build": {
      "env": ["API_SERVICE_KEY"] // Impacts hash of web's build task
    }
  }
}

小提示：

Turborepo 會透過架構推斷自動包含以常見架構為前綴的環境變數。例如，如果您的套件是 Next.js 專案，您不需要指定任何以 NEXT_PUBLIC_ 開頭的環境變數。

萬用字元

Turborepo 支援環境變數的萬用字元，因此您可以輕鬆地處理具有指定前綴的所有環境變數。例如，下方的 turbo.json 將所有以 MY_API_ 開頭的環境變數包含在雜湊中

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["MY_API_*"]
    }
  }
}

否定

前導 ! 表示整個模式將會被否定。例如，下方的 turbo.json 將會忽略 MY_API_URL 變數。

./turbo.json

{
  "tasks": {
    "build": {
      "env": ["!MY_API_URL"]
    }
  }
}

範例

模式	描述
`"*"`	*
`"!*"`	比對每個環境變數。
`""`	排除每個環境變數。
`"FOO*"`	比對 `FOO`、`FOOD`、`FOO_FIGHTERS` 等。
`"FOO\*"`	解析為 `"FOO*"` 並比對 `FOO`、`FOOD` 和 `FOO_FIGHTERS`。
`"FOO\\*"`	比對名為 `FOO*` 的單一環境變數。
`"!FOO*"`	排除所有以 `FOO` 開頭的環境變數。
`"\!FOO"`	解析為 `"!FOO"`，並排除名為 `!FOO` 的單一環境變數。
`"\\!FOO"`	比對名為 `!FOO` 的單一環境變數。

`"FOO!"`

比對名為 FOO! 的單一環境變數。

./turbo.json

{
  "tasks": {
    "build": {
      // Values will available within `build` scripts
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    }
  }
}

passThroughEnv

`即使在嚴格環境模式下，也應該提供給此任務執行階段使用的環境變數允許清單。`

passThroughEnv 中提供的值不會影響任務的快取鍵。如果您希望這些變數的變更導致快取錯失，您需要將它們包含在env 或 globalEnv 中。

outputs

./turbo.json

{
  "tasks": {
    "build": {
      // Cache all files emitted to the packages's `dist` directory
      "outputs": ["dist/**"]
    }
  }
}

相對於套件的 package.json 的檔案 glob 模式清單，用於在任務成功完成時快取。

`如果輸出路徑需要相對於儲存庫根目錄，請參閱` `$TURBO_ROOT$。`

預設值：true

省略此鍵或傳遞空陣列會告知 turbo 不要快取任何內容（日誌除外，在啟用快取時，日誌始終會被快取）。

./turbo.json

{
  "tasks": {
    "build": {
      "outputs": [".svelte-kit/**", "dist/**"] // File outputs will be cached
    },
    "dev": {
      "cache": false, // No outputs will be cached
      "persistent": true
    }
  }
}

`cache`

定義是否應快取任務輸出。將 cache 設定為 false 對於長時間執行的開發任務以及確保任務在其執行圖中時始終執行非常有用。

inputs

預設值：[]，套件中已簽入原始碼控制的所有檔案

./turbo.json

{
  "tasks": {
    "test": {
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
    }
  }
}

相對於套件的 package.json 的檔案 glob 模式清單，用於判斷套件是否已變更。turbo.json 始終被視為輸入。

`請造訪檔案 glob 規格以取得關於 globbing 語法的更多資訊。`

使用 inputs 鍵會讓您選擇退出 turbo 的預設行為，即考慮 .gitignore。您必須根據需要從 .gitignore 重建 glob，或使用 $TURBO_DEFAULT$ 以根據預設行為進行建構。

./turbo.json

{
  "tasks": {
    "check-types": {
      // Consider all default inputs except the package's README
      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
    }
  }
}

$TURBO_DEFAULT$

由於指定 inputs 鍵會立即選擇退出預設行為，您可以在 inputs 陣列中使用特殊字串 $TURBO_DEFAULT$ 來還原 turbo 的預設行為。這可讓您調整預設行為以獲得更精細的控制。

$TURBO_ROOT$

./turbo.json

{
  "tasks": {
    "check-types": {
      // Consider all Typescript files in `src/` and the root tsconfig.json as inputs
      "inputs": ["$TURBO_ROOT$/tsconfig.json", "src/**/*.ts"]
    }
  }
}

`任務可能會參考位於其目錄外部的檔案。`

以 $TURBO_ROOT$ 開頭的檔案 glob 將會變更 glob 以相對於儲存庫的根目錄，而不是套件目錄。

outputLogs

預設值：`full`	描述
`設定輸出日誌詳細程度。可以透過--output-logs CLI 選項覆寫。`	選項
`full`	顯示所有日誌
`hash-only`	僅顯示任務的雜湊
`new-only`	僅顯示來自快取錯失的日誌
`errors-only`	僅顯示來自任務失敗的日誌

./turbo.json

{
  "tasks": {
    "build": {
      "outputLogs": "new-only"
    }
  }
}

`none`

預設值：false

隱藏所有任務日誌

persistent

將任務標記為 persistent，以防止其他任務依賴長時間執行的處理程序。持續性任務預設為互動式。

./turbo.json

{
  "tasks": {
    "dev": {
      "persistent": true
    }
  }
}

由於長時間執行的處理程序不會結束，因此會依賴它的任務永遠不會執行。一旦您將任務標記為持續性，如果其他任務依賴它，turbo 將會擲回錯誤。

`此選項對於開發伺服器或其他「監看」任務最有用。`

標記為 persistent 的任務也預設為 interactive。

interactive

預設值：false（對於標記為 persistent 的任務，預設為 true）

./turbo.json

{
  "tasks": {
    "test:watch": {
      "interactive": true,
      "persistent": true
    }
  }
}

`將任務標記為 interactive，使其在終端機 UI 中接受來自 stdin 的輸入。必須與 persistent 一起使用。`

預設值：false

此選項對於可以在執行時操作的腳本最有用，例如 Jest 或 Vitest。

interruptible

將 `persistent` 任務標記為 `interruptible`，以允許它由 `turbo watch` 重新啟動。

turbo watch 監看您的套件變更，並自動重新啟動受影響的任務。但是，如果任務是持續性的，則預設情況下不會重新啟動。若要啟用重新啟動持續性任務，請將 interruptible 設定為 true。

./turbo.json

{
  "boundaries": {}
}

`邊界`

boundaries 標籤可讓您為 boundaries 指令定義規則。

`tags` 物件中的每個鍵都是可以使用 `turbo boundaries` 檢查的標籤名稱。

在標籤的設定物件中，您可以定義依賴項目和被依賴項目的規則。

dependencies 和 dependents

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // permit only packages with the `ui` tag
        "allow": ["ui"],
        // and ban packages with the `unsafe` tag
        "deny": ["unsafe"]
      }
    }
  }
}

標籤依賴項目和被依賴項目的規則。

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependencies": {
        // only packages with the `unsafe` tag are banned, all other packages permitted
        "deny": ["unsafe"]
      }
    }
  }
}

您可以新增允許清單和拒絕清單

./turbo.json

{
  "boundaries": {
    "utils": {
      "dependents": {
        // only packages with the `web` tag can import packages with the `utils` tag
        "allow": ["web"]
      }
    }
  }
}

允許清單和拒絕清單都可以省略。

也可以為標籤的被依賴項目新增規則，即匯入此標籤的套件。

./turbo.json

{
  "remoteCache": {}
}

`遠端快取`

預設值：true

全域 remoteCache 選項具有各種欄位，用於設定遠端快取使用方式

enabled

設定 turbo.json

即使在嚴格環境模式下，也應該提供給此任務執行階段使用的環境變數允許清單。

如果輸出路徑需要相對於儲存庫根目錄，請參閱 $TURBO_ROOT$。

請造訪檔案 glob 規格以取得關於 globbing 語法的更多資訊。

tags 物件中的每個鍵都是可以使用 turbo boundaries 檢查的標籤名稱。

本頁內容

`即使在嚴格環境模式下，也應該提供給此任務執行階段使用的環境變數允許清單。`

`如果輸出路徑需要相對於儲存庫根目錄，請參閱` `$TURBO_ROOT$。`

`請造訪檔案 glob 規格以取得關於 globbing 語法的更多資訊。`

`tags` 物件中的每個鍵都是可以使用 `turbo boundaries` 檢查的標籤名稱。