環境變數

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

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

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

載入環境變數

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

注意：Next.js 也支援你的 .env* 檔案內的多行變數

# .env
 
# you can write with line breaks
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"
 
# or with `\n` inside double quotes
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

注意：如果你正在使用 /src 資料夾，請注意 Next.js 將僅從父資料夾載入 .env 檔案，而不會從 /src 資料夾載入。這會自動將 process.env.DB_HOST、process.env.DB_USER 和 process.env.DB_PASS 載入到 Node.js 環境中，讓你可以在路由處理器中使用它們。

例如

export async function GET() {
  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 捆綁包中。

你可以在動態渲染期間安全地在伺服器上讀取環境變數

import { connection } from 'next/server'
 
export default async function Component() {
  await connection()
  // cookies, headers, and other Dynamic APIs
  // will also opt into dynamic rendering, meaning
  // this env variable is evaluated at runtime
  const value = process.env.MY_VALUE
  // ...
}

這可讓你使用單一 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.js 在執行 next dev 命令時自動分配 development，或為所有其他命令分配 production。

版本歷史