環境變數

這份文件適用於 Next.js 9.4 及以上版本。如果你正在使用較舊的 Next.js 版本，請升級或參考 next.config.js 中的環境變數。

範例

• 環境變數

Next.js 內建支援環境變數，讓你可以做以下事情：

• 使用 .env.local 來載入環境變數
• 在環境變數的前綴加上 NEXT_PUBLIC_ 來讓瀏覽器存取

載入環境變數

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

.env.local 的範例：

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

可以在 Next.js 資料取得方法 和 API 路由 中，自動載入 process.env.DB_HOST、process.env.DB_USER 和 process.env.DB_PASS 到 Node.js 環境中，並使用它們。

例如在使用 getStaticProps：

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

注意： 為了確保伺服器端的變數安全，環境變數會在建置時被賦值，所以只有 真正 使用到的環境變數會被包含。這意味著 process.env 不是一個標準的 JavaScript 物件，所以你不能使用 解構賦值。 環境變數必須以 process.env.PUBLISHABLE_KEY 的方式被引用，而 不是 const { PUBLISHABLE_KEY } = process.env。

注意： Next.js 會自動以 $VAR 的方式展開你 .env* 檔案中的變數。 這允許你參考其他的變數，像這樣：

# .env
HOSTNAME=localhost
PORT=8080
HOST=http://$HOSTNAME:$PORT

如果你想要在變數的值中使用 $ 該符號，需要在前方加上 \ 來進行轉義，像這樣：\$。

範例:

# .env
A=abc

# becomes "preabc"
WRONG=pre$A

# becomes "pre$A"
CORRECT=pre\$A

注意： 如果你使用了 /src 資料夾， Next.js 只會 從父資料夾載入 .env 檔案， 不會 從 /src 資料夾載入。

將環境變數暴露給瀏覽器

預設情況下，環境變數只會在 Node.js 環境中被使用，這意味著它們不會被暴露給瀏覽器。

為了讓瀏覽器存取環境變數，你必須在變數前面加上 NEXT_PUBLIC_ 。例如：

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

這會將 process.env.NEXT_PUBLIC_ANALYTICS_ID 自動載入到 Node.js 環境中，讓你可以在程式碼任何地方使用它。因為有 NEXT_PUBLIC_ 前綴，所以值會被嵌入到瀏覽器的 JavaScript 中。這個嵌入發生在建置時，所以你的各種 NEXT_PUBLIC_ 環境變數需要在專案建置前被設定。

// 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 中：

vercel env pull .env.local

測試環境的變數

在 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/env 套件中的 loadEnvConfig 函式來確保你的環境變數與 Next.js 一樣。

// 下面指令可以用在 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 (Not checked when NODE_ENV is test.)
4. .env.$(NODE_ENV)
5. .env

舉例來說，如果 NODE_ENV 是 development ，並且你在 .env.development.local 和 .env 中都定義了一個變數，那麼 .env.development.local 中的值將被使用。

注意： NODE_ENV 允許的值有 production、development 和 test。