环境变量

Next.js 内置支持环境变量，允许您执行以下操作

• 使用 .env 加载环境变量
• 通过以 NEXT_PUBLIC_ 为前缀，将环境变量捆绑到浏览器

加载环境变量

Next.js 内置支持从 .env* 文件加载环境变量到 process.env 中。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

这会将 process.env.DB_HOST、process.env.DB_USER 和 process.env.DB_PASS 自动加载到 Node.js 环境中，允许您在Next.js 数据获取方法和API 路由中使用它们。

例如，使用getStaticProps

export async function getStaticProps() {
  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 会自动扩展使用 $ 引用其他变量（例如 $VARIABLE）的变量，例如在您的 .env* 文件中。这允许您引用其他密钥。例如

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

在上面的示例中，process.env.TWITTER_URL 将设置为 https://x.com/nextjs。

了解一下：如果您需要在实际值中使用带有 $ 的变量，则需要对其进行转义，例如 \$。

为浏览器捆绑环境变量

非 NEXT_PUBLIC_ 环境变量仅在 Node.js 环境中可用，这意味着浏览器无法访问它们（客户端在不同的环境中运行）。

为了使环境变量的值在浏览器中可访问，Next.js 可以在构建时将值“内联”到交付给客户端的 js bundle 中，用硬编码的值替换所有对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 镜像到多个环境，所有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 bundle 中。

要读取运行时环境变量，我们建议使用getServerSideProps或逐步采用 App Router。

这允许你使用单个 Docker 镜像，该镜像可以通过多个具有不同值的的环境进行推广。

了解一下

• 你可以使用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文件为testing环境执行相同的操作（尽管此文件不像前两个文件那么常见）。Next.js 不会在testing环境中加载.env.development或.env.production中的环境变量。

当使用jest或cypress等工具运行测试时，此功能很有用，在这些工具中，你需要仅为测试目的设置特定的环境变量。如果将NODE_ENV设置为test，则将加载测试默认值，尽管你通常不需要手动执行此操作，因为测试工具将为你解决此问题。

你需要记住，test环境与development和production环境之间存在一个小差异：不会加载.env.local，因为你希望测试对每个人都产生相同的结果。这样，每个测试执行都会使用相同的 env 默认值，跨不同的执行忽略你的.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。

版本历史