環境變數

環境變數可讓您將變數新增至在某個環境中執行的應用程式程序當中，而無需變更程式碼。環境變數能安全儲存，是下列使用案例的理想選擇：

用於第三方整合的 API 金鑰
用於應用程式邏輯的功能旗標
在各環境之間不同或可能不保密的設定

環境變數只能在應用伺服器中存取。它們無法修改邊緣服務的行為，包括 Proxy 和邊緣函式。

Note

先決條件

您必須在要為其管理環境變數的專案上具有開發人員或管理員角色。如果您沒有存取權限，請要求具有 Managed Runtime 管理員角色的人員來協助您。

教學

請按照這些教學來設定環境變數，然後在 PWA Kit 網站中實作程式碼以使用這些變數。您可以根據具體需求自訂程式碼。這些教學會示範如何：

我們建議在本機電腦上測試這些步驟，然後在非 Production 環境中測試，最後再將您的變更部署到 Production 中。如需更多指南，請參閱最佳做法、環境變數疑難排解、在本機偵錯。

管理環境變數

環境變數：

可以使用 Managed Runtime API 或 Runtime Admin 進行管理
在 Node.js 中使用 process.env 進行存取

導入新的環境變數時，首先要透過 API 或 Runtime Admin 進行設定。等待重新部署完成，然後部署使用它的新套件。

使用 Managed Runtime API

設定、更新、解除設定環境變數

使用 projects_target_env_var_partial_update：

1curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
2  --request 'PATCH' \
3  --header 'Content-Type: application/json' \
4  --header 'Accept: application/json' \
5  --header "Authorization: Bearer $MOBIFY_API_KEY" \
6  --data '{
7    "API_KEY": {"value": "b3Blbi1zZXNhbWU="},
8    "STOREFRONT_CONFIG": {"value": "{\"showBuyNowButton\": false}"},
9    "SLAS_CLIENT_ID": {"value": "da422690-7800-41d1-8ee4-3ce983961078"}
10}'

若要解除設定現有的環境變數，請將它的值設為 null。

修改環境變數會重新部署環境。部署完成後，更新的值就會生效。

取得所有環境變數

使用 projects_target_env_var_list：

1curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
2  --header "Authorization: Bearer $MOBIFY_API_KEY" \
3  --header 'Accept: application/json'

使用 Runtime Admin

要建立、更新、移除或查看環境變數，請執行以下操作：

登入 Runtime Admin。若要存取 Runtime Admin，請參閱 Managed Runtime 管理。
前往專案的 [Overview] (概觀) 頁面。
按一下要管理其環境變數的環境的名稱。
按一下左側選單中的 Environment Variables (環境變數)。

最佳做法

請選擇對您的應用程式有意義的環境變數名稱。使用描述性名稱：為環境變數選擇簡潔明瞭的名稱，讓您的團隊能夠輕鬆理解。
避免在程式碼中寫死 API 金鑰等敏感資訊。使用環境變數來確保其安全。
不要將環境變數傳遞到將會序列化到頁面的資料中。請考慮新增測試，以確保不會洩漏環境變數資料。
不要從 getProps 或 react-query Hook 傳回環境變數。
僅在伺服器端使用環境變數。預設情況下，環境變數不會在用戶端公開。您可以選擇在用戶端公開它們 (例如在設定檔中)，但請確定公開這些值符合您的安全做法。
在本機電腦上測試環境變數，然後在非 Production 環境中測試，最後再將它們部署到 Production 中。這有助於確保您可以在本機快速解決問題，然後模擬網站行為、驗證功能，並在部署到 Production 之前進行任何使用者驗收測試。
在使用環境變數的程式碼中加入錯誤處理，以防止因未定義的環境變數而導致失敗。
控制對環境變數的存取，以防止未經授權的修改。
記錄每個環境變數的用途和設定。這有助於讓新開發人員熟悉並解決問題。

限制

環境變數的使用受到下列限制：

每個環境限用 100 個環境變數。
環境變數名稱只能包含字母數位字元、下劃線（ _ ）和短劃線（ - ）。
環境變數名稱必須為 512 個字元以下，且不能以保留字首開頭：AWS、MRT、X_MRT、MOBIFY、X_MOBIFY、SSR_PROXY、NODE。
環境變數名稱不能使用任何保留名稱：BUNDLE_ID、DEPLOY_ID、DEPLOY_TARGET、EXTERNAL_DOMAIN_NAME、HANDLER、LAMBDA_RUNTIME_DIR、LAMBDA_TASK_ROOT、NODE_ENV、REDIRECT_BUCKET、REDIRECT_KEY、REDIRECT_UPDATE、REMOTE、X_AMZN_TRACE_ID。
環境變數值必須是字串。要儲存複雜值，請將 JSON 編碼為字串。
為環境設定的環境變數值最大大小為 32 KB。

環境變數疑難排解

本節針對使用環境變數時可能遇到的常見錯誤，提供建議的解決方案。

未設定環境變數

您的程式碼擲回 Error，指出缺少變數。

**原因：**未設定程式碼呼叫的環境變數。

**建議的解決方案：**呼叫 projects_target_env_var_partial_update API 端點來設定適用的環境變數。

環境變數名稱不正確

您的程式碼記錄了錯誤訊息，指出未找到環境變數。

**原因：**程式碼找不到環境變數，因為程式碼中有拼寫錯誤，或使用了不正確的環境變數名稱。

**建議的解決方案：**確認您在程式碼中正確拼寫了環境變數名稱，並且使用了所需的環境變數名稱。呼叫 projects_target_env_var_list API 端點以查看已設定之變數的完整清單，檢查環境變數名稱。

不支援的環境變數名稱

您用來設定環境變數的 API 呼叫失敗了。

**原因：**環境變數名稱可能不符合限制條件。例如，環境變數值的大小超過 32 KB。

**建議的解決方案：**確認您的環境變數符合限制條件。

無效的 API 金鑰格式

執行涉及使用 API 金鑰的程式碼時，發生驗證錯誤。

**原因：**設定環境變數時使用的 API 金鑰不是預期的格式或已遺失。

**建議的解決方案：**確認環境變數儲存的 API 金鑰正確無誤。如有需要，請呼叫 projects_target_env_var_partial_update API 端點來修正 API 金鑰。

API 端點的 URL 無效

fetch 要求因網路錯誤而失敗。

**原因：**程式碼中呼叫的任何 API 端點的 URL 可能未正確定義或無效。例如，內容管理系統 (CMS) 端點的 URL 不正確。

**建議的解決方案：**確認程式碼中 API 端點的任何 URL 都正確無誤。