如何在 Next.js 中使用环境变量

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

# 可以使用换行符书写
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/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 可以在构建时将值“内联”到交付给客户端的 JavaScript 包中，将所有对 process.env.[variable] 的引用替换为硬编码的值。要实现这一点，只需在变量前添加 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 包中。

您可以在动态渲染期间安全地在服务器上读取环境变量：

import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies、headers 和其他动态 API
  // 也会选择动态渲染，意味着
  // 这个环境变量在运行时被评估
  const value = process.env.MY_VALUE
  // ...
}

这允许您使用一个单一的 Docker 镜像，可以在多个环境中提升，并具有不同的值。

小知识：

• 您可以使用 register 函数 在服务器启动时运行代码。
• 我们不建议使用 runtimeConfig 选项，因为它不适用于独立输出模式。相反，如果您需要此功能，我们建议 逐步采用 应用路由。

测试环境变量

除了 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)
}

环境变量加载顺序

环境变量按以下顺序查找，一旦找到变量即停止。

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。

版本历史