使用環境變數

環境變數輸入是您應用程式的重要組成部分，您需要在 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 鍵中指定的那些環境變數。

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

傳遞變數

在進階使用案例中，您可能想要讓一些環境變數可用於任務，而無需將它們包含在雜湊中。這些變數的變更不會影響任務輸出，但仍然需要可用，才能使任務成功執行。

對於這些案例，請將這些環境變數新增至 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", ".env.local"] // Only the `build` task hash
    }
  }
}

最佳實務

在套件中使用 .env 檔案

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

這種實務更能模擬應用程式的執行時行為，因為環境變數會單獨存在於每個應用程式的執行時環境中。此外，隨著您的單一儲存庫擴展，這種實務可讓您更輕鬆地管理每個應用程式的環境，防止環境變數洩漏到不同應用程式中。

使用 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 鍵的差異，可以幫助您找出配置中可能遺失的任何環境變數。

下一步

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