Turborepo
API 參考

設定 turbo.json

透過在您的工作區根目錄中新增一個 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 的位置而言。

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

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 執行一個背景處理程序，以預先計算一些耗費資源的操作。此獨立處理程序 (daemon) 是一種效能最佳化，並非 turbo 正常運作所必需的。

./turbo.json
{
  "daemon": true
}

須知

在 CI 環境中執行時，無論此設定為何，daemon 一律會停用。

envMode

預設值："strict"

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

  • "strict"：篩選環境變數，只保留 turbo.json 中 env 和 globalEnv 鍵中指定的變數。
  • "loose"：允許使用處理程序的所有環境變數。

深入瞭解環境模式。

./turbo.json
{
  "envMode": "strict"
}

定義任務

tasks

tasks 物件中的每個鍵都是一個任務的名稱，可以使用 turbo run 執行。Turborepo 會在您的工作區設定中描述的套件中，搜尋 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! 的單個環境變數。

passThroughEnv

一個允許清單，列出應提供給此任務執行階段的環境變數，即使在嚴格環境模式下也是如此。

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

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

outputs

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

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

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

cache

預設值：true

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

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

inputs

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

一個相對於套件 package.json 的檔案 glob 模式列表，用於在判斷套件是否已變更時考慮。turbo.json 始終被視為輸入。

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

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

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

$TURBO_DEFAULT$

由於指定 inputs 鍵會立即退出預設行為，您可以在 inputs 陣列中使用特殊字串 $TURBO_DEFAULT$ 來恢復 turbo 的預設行為。這讓您可以微調預設行為以獲得更高的精細度。

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

outputLogs

預設值：full

設定輸出記錄詳細程度。可以透過 --output-logs CLI 選項覆寫。

選項描述
full顯示所有日誌
hash-only僅顯示任務的雜湊值
new-only僅顯示快取未命中時的日誌
errors-only僅顯示任務失敗時的日誌
none隱藏所有任務日誌
./turbo.json
{
  "tasks": {
    "build": {
      "outputLogs": "new-only"
    }
  }
}

persistent

預設值：false

將任務標記為 persistent，以防止其他任務依賴長時間運行的程序。預設情況下，持續性任務會設為互動式。

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

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

./turbo.json
{
  "tasks": {
    "dev": {
      "persistent": true
    }
  }
}

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

interactive

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

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

此任務對於在運行時可以操作的腳本最有用，例如 Jest 或 Vitest。

./turbo.json
{
  "tasks": {
    "test:watch": {
      "interactive": true,
      "persistent": true
    }
  }
}

interruptible

預設值：false

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

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

遠端快取

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

./turbo.json
{
  "remoteCache": {}
}

enabled

預設值：true

啟用遠端快取。

當 false 時，Turborepo 將停用所有遠端快取操作，即使儲存庫具有有效的 token 也會如此。如果為 true，則會啟用遠端快取，但仍需要使用者登入並將其儲存庫連結至遠端快取。

signature

預設值：false

啟用對遠端快取請求的簽章驗證。當 true 時，Turborepo 將使用環境變數 TURBO_REMOTE_CACHE_SIGNATURE_KEY 的值對每個上傳的成品進行簽名。Turborepo 將拒絕任何具有無效簽章或缺少簽章的下載成品。

preflight

預設值：false

啟用後，任何 HTTP 請求之前都會有一個 OPTIONS 請求，以判斷端點是否支援該請求。

timeout

預設值：30

設定遠端快取操作的逾時時間。值以秒為單位，且僅接受整數值。如果傳遞 0，則任何快取操作都不會逾時。

uploadTimeout

預設值：60

設定遠端快取上傳的逾時時間。值以秒為單位，且僅接受整數值。如果傳遞 0，則任何遠端快取上傳都不會逾時。

apiUrl

預設值："https://vercel.com"

設定對遠端快取進行 API 呼叫的端點。

loginUrl

預設值："https://vercel.com"

設定在 turbo login 期間請求 token 的端點。

上一個

Turborepo API 參考

下一個

套件組態

小時

總計節省的計算時間
開始使用
遠端快取 →

本頁內容

全域選項extendsglobalDependenciesglobalEnvglobalPassThroughEnvuidangerouslyDisablePackageManagerCheckcacheDirdaemonenvMode定義任務tasks任務選項dependsOn相依關係相同套件關係任意任務關係env萬用字元否定範例passThroughEnvoutputscacheinputs$TURBO_DEFAULT$outputLogspersistentinteractiveinterruptible遠端快取enabledsignaturepreflighttimeoutuploadTimeoutapiUrlloginUrl