環境變數

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

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

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_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 pipeline 將在一個環境中建置的 slug 升級到另一個環境，或者如果您建置單個 Docker image 並將其部署到多個環境，則所有 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 image，並可透過具有不同值的多個環境進行升級。

注意事項 (Good to know)

• 您可以使用 register 函式 在伺服器啟動時執行程式碼。
• 我們不建議使用 runtimeConfig 選項，因為它與獨立輸出模式不相容。相反地，我們建議逐步採用 App Router。

預設環境變數

一般情況下，只需要 .env* 檔案即可。然而，有時您可能想要為 development（`next dev`）或 production（`next start`）環境新增一些預設值。

Next.js 允許您在 .env（所有環境）、.env.development（開發環境）和 .env.production（生產環境）中設定預設值。

注意事項：.env、.env.development 和 .env.production 檔案應該包含在您的儲存庫中，因為它們定義了預設值。所有 .env 檔案在預設情況下都會被 .gitignore 排除，讓您可以選擇將這些值提交到儲存庫中。

Vercel 上的環境變數

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

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

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

vercel env pull

注意事項：當您將 Next.js 應用程式部署到 Vercel 時，.env* 檔案中的環境變數將無法在 Edge Runtime 中使用，除非它們的名稱以 NEXT_PUBLIC_ 作為前綴。我們強烈建議您在專案設定中管理您的環境變數，所有環境變數都可以在那裡使用。

測試環境變數

除了development 和 production 環境之外，還有第三個選項：test。如同您可以為開發或生產環境設定預設值一樣，您也可以使用 .env.test 檔案為測試環境設定預設值（雖然這個不像前兩個那麼常見）。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。

版本歷史記錄