環境變數

範例

環境變數

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

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

載入環境變數

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

.env.local

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

這會自動將 process.env.DB_HOST、process.env.DB_USER 和 process.env.DB_PASS 載入 Node.js 環境，讓你能在路由處理器 (Route Handlers) 中使用。

例如：

app/api/route.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。這讓你能參照其他機密值。例如：

.env

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_ 前綴。例如：

Terminal

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

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

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

pages/index.js

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)

預設環境變數

通常只需要一個 .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 中供本地機器使用：

Terminal

vercel env pull .env.local

測試環境變數

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

// 以下程式碼可以用於 Jest 全域設定檔案或類似的測試設定中
import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

環境變數載入順序

環境變數會按以下順序查找，一旦找到變數即停止。

process.env
.env.$(NODE_ENV).local
.env.local（當 NODE_ENV 為 test 時不檢查。）
.env.$(NODE_ENV)
.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。

On this page