跳至主要內容

增加自訂環境變數

附註：此功能使用 react-scripts@0.2.3 以上版本。

貴專案可以利用在您環境中宣告的變數，就如同這些變數在您的 JS 檔案中宣告的一樣。您預設會有 NODE_ENV 為您定義，以及開頭為 REACT_APP_ 的任何其他環境變數。

警告：請勿在您的 React app 中儲存任何機密（例如私密 API 金鑰）！

環境變數會嵌入至建置中，表示任何人都可以透過檢查您的 app 檔案來檢視它們。

環境變數於建置期間嵌入。由於 Create React App 會產生靜態 HTML/CSS/JS 捆綁，因此它無法在執行期間讀取它們。若要於執行期間讀取它們，您需要將 HTML 載入伺服器上的記憶體，並在執行期間取代佔位符，如在此處說明。或是在您變更它們時隨時在伺服器上重新建置 app。

注意：您必須建立以 REACT_APP_ 開頭的客製環境變數。除了 NODE_ENV 之外的任何其他變數都將會被忽略，以避免意外地在機器上揭露一個私人金鑰，該金鑰可能具有相同的名稱。變更任何環境變數需要您在它正在執行的情況下重新啟動開發伺服器。

這些環境變數將在 process.env 上為您定義。例如，擁有稱為 REACT_APP_NOT_SECRET_CODE 的環境變數，將會在您的 JS 中作為 process.env.REACT_APP_NOT_SECRET_CODE 公開。

還有一個稱為 NODE_ENV 的內建環境變數。您可以從 process.env.NODE_ENV 讀取它。當您執行 npm start 時，它始終等於 'development'，當您執行 npm test 時，它始終等於 'test'，而當您執行 npm run build 建立生產組合時，它始終等於 'production'。您無法手動覆寫 NODE_ENV。這可以防止開發人員不小心將緩慢的開發建置部署到生產環境。

這些環境變數對於顯示有條件的資訊（基於專案的部署位置）或使用版本控制之外的敏感資料很有用。

首先，您需要定義環境變數。例如，假設您想要使用 <form> 內的環境變數

render() {
  return (
    <div>
      <small>You are running this application in <b>{process.env.NODE_ENV}</b> mode.</small>
      <form>
        <input type="hidden" defaultValue={process.env.REACT_APP_NOT_SECRET_CODE} />
      </form>
    </div>
  );
}

在建置過程中，process.env.REACT_APP_NOT_SECRET_CODE 將會被替換為 REACT_APP_NOT_SECRET_CODE 環境變數的目前值。請記住，系統會自動為您設定 NODE_ENV 變數。

當您在瀏覽器中載入應用程式並檢查 <input> 時，您將會看到它的值設為 abcdef，而且粗體文字將會顯示在使用 npm start 時提供的環境。

<div>
  <small>You are running this application in <b>development</b> mode.</small>
  <form>
    <input type="hidden" value="abcdef" />
  </form>
</div>

上述的表單正在從環境尋找稱為 REACT_APP_NOT_SECRET_CODE 的變數。為了使用這個值，我們需要在環境中定義它。這可以使用兩種方式完成：在您的 shell 中或在 .env 檔案中。接下來的幾個區段將會說明這兩種方式。

存取 NODE_ENV 對於有條件地執行動作也很有用。

if (process.env.NODE_ENV !== 'production') {
  analytics.disable();
}

當您使用 npm run build 編譯應用程式時，最佳化步驟將會移除這個條件，而且產生的組合會更小。

在 HTML 中參照環境變數​

注意：此功能在 react-scripts@0.9.0 及更新版本中提供。

您也可以在 public/index.html 中存取以 REACT_APP_ 開頭的環境變數。例如

<title>%REACT_APP_WEBSITE_NAME%</title>

請注意，上面區段的警告事項適用

  • 除了幾個內建變數（NODE_ENV 和 PUBLIC_URL）以外，變數名稱必須以 REACT_APP_ 開頭才能運作。
  • 環境變數會在建置時注入。如果你需要在執行時注入，改採這個方法。

在您的 Shell 中新增暫存環境變數​

定義環境變數會依作業系統而有所不同。重要的是，需要知道這種方式在 Shell 會話期間暫時存在。

Windows (cmd.exe)​

set "REACT_APP_NOT_SECRET_CODE=abcdef" && npm start

(注意：變數指定周圍需要加上引號，才能避免尾隨空白。)

Windows (Powershell)​

($env:REACT_APP_NOT_SECRET_CODE = "abcdef") -and (npm start)

Linux、macOS (Bash)​

REACT_APP_NOT_SECRET_CODE=abcdef npm start

在 .env 中新增開發環境變數​

注意：此功能適用於 react-scripts@0.5.0 和更高版本。

若要定義永久環境變數，請在專案根目錄建立一個名為 .env 的檔案

REACT_APP_NOT_SECRET_CODE=abcdef

注意：您必須從 REACT_APP_ 開頭建立自訂環境變數。除了 NODE_ENV 以外的任何其他變數都會被忽略，以避免意外公開電腦上的私鑰，因為私鑰可能有相同的名稱。若要變更任何環境變數，如果開發伺服器正在執行，您需要重新啟動開發伺服器。

注意：在變更 .env 檔案後，您需要重新啟動開發伺服器。

應該將 .env 檔案提交到原始程式碼管理（排除 .env*.local）。

還能使用哪些其他 .env 檔案？​

注意：此功能適用於 react-scripts@1.0.0 和更高版本。

  • .env：預設。
  • .env.local：本機覆寫。此檔案會在測試環境以外的所有環境中載入。
  • .env.development、.env.test、.env.production：環境特定設定。
  • .env.development.local、.env.test.local、.env.production.local：環境特定設定的本機覆寫。

左方的檔案優先於右方的檔案

  • npm start：.env.development.local、.env.local、.env.development、.env
  • npm run build：.env.production.local、.env.local、.env.production、.env
  • npm test：.env.test.local、.env.test、.env （注意，缺少 .env.local）

如果電腦未明確設定，這些變數會作為預設值。

請參閱dotenv 說明文件，了解詳細資訊。

注意：如果您正在為開發定義環境變數，則 CI 和/或託管平台很可能會需要定義這些變數。請查閱他們的說明文件以了解如何執行此操作。例如，請參閱 Travis CI 或 Heroku 的文件說明。

在 .env 中展開環境變數​

注意：此功能可用於 react-scripts@1.1.0 及以上版本。

展開機器上已存在的變數，以便在 .env 檔案中使用（使用 dotenv-expand）。

例如，取得環境變數 npm_package_version

REACT_APP_VERSION=$npm_package_version
# also works:
# REACT_APP_VERSION=${npm_package_version}

或展開目前 .env 檔案本地的變數

DOMAIN=www.example.com
REACT_APP_FOO=$DOMAIN/foo
REACT_APP_BAR=$DOMAIN/bar