環境變數

Next.js 內建支援環境變數，讓你可以執行下列操作

• 使用 .env 載入環境變數
• 透過加上 NEXT_PUBLIC_ 前綴，為瀏覽器捆綁環境變數

警告： 預設的 create-next-app 範本會確保所有 .env 檔案都新增到你的 .gitignore。你幾乎永遠不會想要將這些檔案提交到你的儲存庫。

載入環境變數

Next.js 內建支援從 .env* 檔案載入環境變數到 process.env。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

這會自動將 process.env.DB_HOST、process.env.DB_USER 和 process.env.DB_PASS 載入 Node.js 環境，讓你可以在 Next.js 資料獲取方法和 API 路由中使用它們。

例如，使用 getStaticProps

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

使用 @next/env 載入環境變數

如果你需要在 Next.js 執行階段之外載入環境變數，例如在 ORM 或測試執行器的根設定檔中，你可以使用 @next/env 套件。

此套件由 Next.js 內部使用，以從 .env* 檔案載入環境變數。

若要使用它，請安裝套件並使用 loadEnvConfig 函式載入環境變數

npm install @next/env

import { loadEnvConfig } from '@next/env'
 
const projectDir = process.cwd()
loadEnvConfig(projectDir)

然後，你可以在需要的地方匯入設定。例如

import './envConfig.ts'
 
export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

參考其他變數

Next.js 將自動展開在 .env* 檔案內使用 $ 參考其他變數的變數，例如 $VARIABLE。這可讓你參考其他密碼。例如

TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

在上述範例中，process.env.TWITTER_URL 將設定為 https://x.com/nextjs。

要知道的好事：如果你需要在實際值中使用帶有 $ 的變數，則需要逸出它，例如 \$。

為瀏覽器捆綁環境變數

非 NEXT_PUBLIC_ 環境變數僅在 Node.js 環境中可用，這表示瀏覽器無法存取它們 (用戶端在不同的環境中執行)。

為了讓瀏覽器可以存取環境變數的值，Next.js 可以在建置時將值「內嵌」到傳遞至用戶端的 js 捆綁包中，以硬式編碼值取代對 process.env.[variable] 的所有參考。若要告知它執行此操作，你只需要在變數加上 NEXT_PUBLIC_ 前綴。例如

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

這會告知 Next.js 將 Node.js 環境中對 process.env.NEXT_PUBLIC_ANALYTICS_ID 的所有參考，取代為你執行 next build 的環境中的值，讓你可以在程式碼中的任何位置使用它。它將內嵌到傳送至瀏覽器的任何 JavaScript 中。

注意：建置完成後，你的應用程式將不再回應這些環境變數的變更。例如，如果你使用 Heroku 管道將在一個環境中建置的 slugs 升級到另一個環境，或者如果你建置並將單一 Docker 映像部署到多個環境，則所有 NEXT_PUBLIC_ 變數都將凍結為在建置時評估的值，因此在建置專案時需要適當地設定這些值。如果你需要存取執行階段環境值，則必須設定你自己的 API 以將它們提供給用戶端 (依需求或在初始化期間)。

import setupAnalyticsService from '../lib/my-analytics-service'
 
// 'NEXT_PUBLIC_ANALYTICS_ID' can be used here as it's prefixed by 'NEXT_PUBLIC_'.
// It will be transformed at build time to `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
 
function HomePage() {
  return <h1>Hello World</h1>
}
 
export default HomePage

請注意，動態查閱將不會被內嵌，例如

// This will NOT be inlined, because it uses a variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
 
// This will NOT be inlined, because it uses a variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

執行階段環境變數

Next.js 可以同時支援建置時和執行階段環境變數。

預設情況下，環境變數僅在伺服器上可用。若要將環境變數公開給瀏覽器，必須加上 NEXT_PUBLIC_ 前綴。但是，這些公開環境變數將在 next build 期間內嵌到 JavaScript 捆綁包中。

若要讀取執行階段環境變數，我們建議使用 getServerSideProps 或 逐步採用 App Router。

這可讓你使用單一 Docker 映像，該映像可以透過具有不同值的多個環境進行升級。

要知道的好事

• 你可以使用 register 函式在伺服器啟動時執行程式碼。
• 我們不建議使用 runtimeConfig 選項，因為這不適用於獨立輸出模式。相反地，如果你需要此功能，我們建議逐步採用 App Router。

Vercel 上的環境變數

當將你的 Next.js 應用程式部署到 Vercel 時，可以在 專案設定中設定環境變數。

所有類型的環境變數都應該在那裡設定。即使是在開發中使用的環境變數也是如此 – 這些環境變數可以下載到你的本機裝置之後。

如果你已設定開發環境變數，你可以使用以下命令將它們提取到 .env.local 中，以便在本機電腦上使用

vercel env pull

要知道的好事：當將你的 Next.js 應用程式部署到 Vercel 時，除非你的環境變數名稱加上 NEXT_PUBLIC_ 前綴，否則 .env* 檔案中的環境變數將無法用於 Edge Runtime。我們強烈建議你在專案設定中管理你的環境變數，從那裡可以取得所有環境變數。

測試環境變數

除了 development 和 production 環境之外，還有第 3 個可用的選項：test。如同你可以為開發或生產環境設定預設值一樣，你可以對 testing 環境的 .env.test 檔案執行相同的操作 (雖然這一個不如前兩個常見)。在 testing 環境中，Next.js 不會從 .env.development 或 .env.production 載入環境變數。

當使用 jest 或 cypress 等工具執行測試時，此功能非常有用，在這種情況下，你需要僅為測試目的設定特定的環境變數。如果 NODE_ENV 設定為 test，則會載入測試預設值，但你通常不需要手動執行此操作，因為測試工具會為你處理它。

test 環境與 development 和 production 環境之間存在一個小差異，你需要記住：.env.local 不會載入，因為你希望測試為每個人產生相同的結果。透過這種方式，每次測試執行都會使用相同的環境預設值，方法是忽略你的 .env.local (旨在覆寫預設設定)。

要知道的好事：與預設環境變數類似，.env.test 檔案應包含在你的儲存庫中，但 .env.test.local 不應包含在內，因為 .env*.local 旨在透過 .gitignore 忽略。

在執行單元測試時，你可以透過利用 @next/env 套件中的 loadEnvConfig 函式，確保以 Next.js 執行相同的方式載入你的環境變數。

// The below can be used in a Jest global setup file or similar for your testing set-up
import { loadEnvConfig } from '@next/env'
 
export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

環境變數載入順序

環境變數會依下列順序在以下位置中尋找，一旦找到變數就會停止。

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (當 NODE_ENV 為 test 時不檢查。)
4. .env.$(NODE_ENV)
5. .env

例如，如果 NODE_ENV 為 development，且你在 .env.development.local 和 .env 中都定義了變數，則會使用 .env.development.local 中的值。

要知道的好事：NODE_ENV 的允許值為 production、development 和 test。

要知道的好事

• 如果你使用 /src 目錄，則 .env.* 檔案應保留在專案的根目錄中。
• 如果未指派環境變數 NODE_ENV，則在執行 next dev 命令時，Next.js 會自動指派 development，對於所有其他命令則指派 production。

版本歷史