使用環境變數

環境變數輸入是您應用程式的重要組成部分，您需要在 Turborepo 設定中加以考慮。

在 Turborepo 中使用環境變數時，有三個重要的問題

• 我的環境變數是否已納入任務雜湊中？
• turbo 將使用哪種環境模式？
• 我是否已處理我的 .env 檔案？

將環境變數新增至任務雜湊

Turborepo 需要知道您的環境變數，以便考量應用程式行為的變更。為此，請在您的 turbo.json 檔案中使用 env 和 globalEnv 鍵。

{
  "globalEnv": ["IMPORTANT_GLOBAL_VARIABLE"],
  "tasks": {
    "build": {
      "env": ["MY_API_URL", "MY_API_KEY"]
    }
  }
}

• globalEnv：此清單中任何環境變數值的變更都會變更所有任務的雜湊。
• env：包含影響任務的環境變數值的變更，從而實現更佳的精細度。例如，當 API_KEY 的值變更時，lint 任務可能不需要錯過快取，但 build 任務很可能需要。

框架推斷

對於常見的框架，Turborepo 會自動將前綴萬用字元新增至您的 env 鍵。如果您在套件中使用以下框架之一，則無需指定具有這些前綴的環境變數

如果您想選擇退出框架推斷，您可以透過以下方式執行：

• 使用 --framework-inference=false 執行您的任務
• 將負萬用字元新增至 env 鍵（例如，"env": ["!NEXT_PUBLIC_*"]）

環境模式

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

• 嚴格模式（預設）：篩選環境變數，僅保留在 turbo.json 中的 env 和 globalEnv 鍵中指定的環境變數。
• 寬鬆模式：允許所有環境變數可供程序使用。

嚴格模式

嚴格模式會篩選可供任務執行階段使用的環境變數，僅保留在 turbo.json 中的 globalEnv 和 env 鍵中指定的環境變數。

這表示未考量其所需的所有環境變數的任務很可能會失敗。這是好事，因為您不希望快取在不同環境中可能具有不同行為的任務。

Pass-through 變數

在進階使用案例中，您可能希望讓某些環境變數可供任務使用，而無需將其包含在雜湊中。這些變數的變更不會影響任務輸出，但仍需要可供任務成功執行。

對於這些情況，請將這些環境變數新增至 globalPassThroughEnv 和 passThroughEnv。

CI 供應商相容性

嚴格模式會篩選掉來自您的 CI 供應商的環境變數，直到您使用 env、globalEnv、passThroughEnv 或 globalPassThroughEnv 將其納入考量。

如果這些變數中的任何一個對您的任務很重要，且未透過框架推斷包含在內，請確保它們在您的 turbo.json 設定中。

寬鬆模式

寬鬆模式不會根據您的 globalEnv 和 env 鍵篩選您的環境變數。這使得開始逐步遷移到嚴格模式更容易。

使用 --env-mode 標記在您看到環境變數無法被您的腳本找到的任何調用中啟用寬鬆模式

turbo run build --env-mode=loose

只要環境變數在 turbo 執行時可用，您的腳本就能夠使用它。但是，這也讓您更容易意外忘記在設定中考量環境變數，從而允許任務在不應該命中的時候命中快取。

例如，您的應用程式中可能有某些程式碼會從 API 擷取資料，並使用環境變數作為基本 URL

const data = fetch(`${process.env.MY_API_URL}/resource/1`);

然後，您使用以您的預覽環境為目標的 MY_API_URL 值來建置您的應用程式。當您準備發布您的應用程式時，您為生產環境建置，並看到快取命中 - 即使 MY_API_URL 變數的值已變更！MY_API_URL 已變更 - 但 Turborepo 從快取還原了您應用程式的版本，該版本使用預覽環境的 MY_API_URL 而不是生產環境的。

當您使用寬鬆模式時，MY_API_URL 在任務執行階段可用，即使它未納入任務雜湊中。為了讓此任務更有可能失敗並保護您免於此錯誤設定，我們鼓勵您選擇嚴格模式。

平台環境變數

當將您的應用程式部署到 Vercel 時，您可能已經在您的專案上設定了 環境變數。Turborepo 將自動針對您的 turbo.json 設定檢查這些變數，以確保您已考量它們，並會警告您任何遺失的變數。

可以透過設定 TURBO_PLATFORM_ENV_DISABLED=false 來停用此功能

處理 .env 檔案

.env 檔案非常適合在本地端處理應用程式。Turborepo 不會將 .env 檔案載入到您的任務執行階段中，而是將它們留給您的框架或 dotenv 等工具處理。

但是，重要的是 turbo 知道您的 .env 檔案中值的變更，以便它可以將它們用於雜湊。如果您在建置之間變更 .env 檔案中的變數，build 任務應該錯過快取。

若要執行此操作，請將檔案新增至 inputs 鍵

{
  "globalDependencies": [".env"], // All task hashes
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env"] // Only the `build` task hash
    }
  }
}

多個 .env 檔案

您可以一次擷取多個 .env 檔案，方法是使用 *。

{
  "globalDependencies": [".env"], // All task hashes
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env*"] // Only the `build` task hash
    }
  }
}

最佳實務

在套件中使用 .env 檔案

不建議在儲存庫的根目錄中使用 .env 檔案。相反地，我們建議將您的 .env 檔案放置在使用它們的套件中。

此實務更緊密地模擬您的應用程式的執行階段行為，因為環境變數個別存在於每個應用程式的執行階段中。此外，隨著您的 monorepo 擴展，此實務使得管理每個應用程式的環境變得更容易，防止環境變數洩漏到各個應用程式中。

使用 eslint-config-turbo

eslint-config-turbo 套件可協助您尋找在您的程式碼中使用但未在您的 turbo.json 中列出的環境變數。這有助於確保您的所有環境變數都已納入您的設定中。

避免在執行階段建立或變更環境變數

Turborepo 會在任務開始時雜湊您的任務的環境變數。如果您在任務期間建立或變更環境變數，Turborepo 將不會知道這些變更，也不會將它們納入任務雜湊中。

例如，Turborepo 將無法偵測到以下範例中的內嵌變數

{
  "scripts": {
    "dev": "export MY_VARIABLE=123 && next dev"
  }
}

MY_VARIABLE 是在 dev 任務啟動之後才新增至環境，因此 turbo 將無法將其用於雜湊。

範例

以下是一些熱門框架的正確環境變數設定範例

疑難排解

使用 --summarize

您可以將 --summarize 標記新增至您的 turbo run 命令，以產生摘要關於您的任務資料的 JSON 檔案。檢查 globalEnv 和 env 鍵的差異可以幫助您識別可能從您的設定中遺失的任何環境變數。

後續步驟

一旦您考量了您的環境變數，您就可以開始建置 CI 管道，以 turbo 的速度建置、檢查和部署您的應用程式。