環境變數

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

• 使用 .env.local 載入環境變數
• 透過加上 NEXT_PUBLIC_ 前綴將環境變數打包給瀏覽器

載入環境變數

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

注意：Next.js 也支援在 .env* 檔案中使用多行變數：

# .env.local

# 可以換行書寫
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# 或在雙引號內使用 `\n`
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.js 會自動展開在 .env* 檔案中使用 $ 參照的其他變數，例如 $VARIABLE。這讓您可以參照其他機密資料。例如：

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

在上面的範例中，process.env.TWITTER_URL 會被設定為 https://twitter.com/nextjs。

須知：如果需要在實際值中使用 $，必須進行跳脫，例如 \$。

為瀏覽器打包環境變數

非 NEXT_PUBLIC_ 的環境變數僅在 Node.js 環境中可用，意味著瀏覽器無法存取（客戶端執行在不同的 環境 中）。

為了讓環境變數的值在瀏覽器中可存取，Next.js 可以在建置時將值「內聯」到傳送給客戶端的 js 套件中，將所有對 process.env.[變數] 的參照替換為硬編碼的值。要做到這一點，您只需在變數前加上 NEXT_PUBLIC_。例如：

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

這會告訴 Next.js 在 Node.js 環境中將所有對 process.env.NEXT_PUBLIC_ANALYTICS_ID 的參照替換為執行 next build 時環境中的值，讓您可以在程式碼的任何地方使用它。它會被內聯到傳送給瀏覽器的任何 JavaScript 中。

注意：建置完成後，您的應用程式將不再回應這些環境變數的變更。例如，如果您使用 Heroku 管道將在一個環境中建置的 slug 推廣到另一個環境，或者如果您建置並將單一 Docker 映像部署到多個環境，所有 NEXT_PUBLIC_ 變數將被凍結為建置時評估的值，因此這些值需要在專案建置時適當設定。如果您需要存取執行時環境值，您必須設定自己的 API 來提供這些值給客戶端（無論是按需還是在初始化時）。

import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID' 可以在這裡使用，因為它有 'NEXT_PUBLIC_' 前綴。
// 它會在建置時轉換為 `setupAnalyticsService('abcdefghijk')`。
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

請注意，動態查詢將 不會 被內聯，例如：

// 這不會被內聯，因為它使用了變數
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// 這不會被內聯，因為它使用了變數
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

執行時環境變數

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

預設情況下，環境變數僅在伺服器端可用。要將環境變數暴露給瀏覽器，必須加上 NEXT_PUBLIC_ 前綴。然而，這些公開的環境變數會在 next build 時被內聯到 JavaScript 套件中。

要讀取執行時環境變數，我們建議使用 getServerSideProps 或 逐步採用 App 路由器。使用 App 路由器時，我們可以在動態渲染期間安全地在伺服器上讀取環境變數。這讓您可以使用一個單一的 Docker 映像，在多個具有不同值的環境中推廣。

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies()、headers() 和其他動態函式
  // 也會選擇動態渲染，意味著
  // 這個環境變數會在執行時評估
  const value = process.env.MY_VALUE
  // ...
}

須知：

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

預設環境變數

通常只需要一個 .env.local 檔案。但有時您可能想為 development (next dev) 或 production (next start) 環境新增一些預設值。

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

.env.local 總是會覆蓋設定的預設值。

須知：.env、.env.development 和 .env.production 檔案應該包含在您的儲存庫中，因為它們定義了預設值。.env*.local 應該被加入 .gitignore，因為這些檔案預期被忽略。.env.local 是用來儲存機密資料的地方。

Vercel 上的環境變數

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

所有類型的環境變數都應該在那裡設定。甚至開發中使用的環境變數也可以 下載到您的本地裝置。

如果您已經設定了 開發環境變數，可以使用以下命令將它們拉取到 .env.local 中以便在本地機器上使用：

vercel env pull .env.local

須知：當您將 Next.js 應用程式部署到 Vercel 時，.env* 檔案中的環境變數將不會提供給 Edge Runtime，除非它們的名稱以 NEXT_PUBLIC_ 為前綴。我們強烈建議在 專案設定 中管理您的環境變數，因為所有環境變數都可以從那裡取得。

測試環境變數

除了 development 和 production 環境外，還有第三個選項：test。與為開發或生產環境設定預設值的方式相同，您可以使用 .env.test 檔案為 testing 環境設定預設值（儘管這個選項不如前兩個常見）。Next.js 在 testing 環境中不會從 .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.js 相同的方式載入環境變數，方法是利用 @next/env 套件中的 loadEnvConfig 函式。

// 以下內容可以用於 Jest 全域設定檔案或類似的測試設定中
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。

版本歷史