环境变量

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

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

警告： 默认的 create-next-app 模板确保所有 .env 文件都添加到您的 .gitignore 中。您几乎永远不希望将这些文件提交到您的存储库。

加载环境变量

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 包中，从而将对 process.env.[variable] 的所有引用替换为硬编码值。要告诉它这样做，您只需在变量前加上 NEXT_PUBLIC_ 前缀。例如：

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

这将告诉 Next.js 将 Node.js 环境中对 process.env.NEXT_PUBLIC_ANALYTICS_ID 的所有引用替换为您运行 next build 的环境中的值，从而允许您在代码中的任何位置使用它。它将被内联到发送到浏览器的任何 JavaScript 中。

注意：构建完成后，您的应用程序将不再响应对这些环境变量的更改。例如，如果您使用 Heroku 管道将在一个环境中构建的 slugs 提升到另一个环境，或者如果您构建并将单个 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 包中。

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

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

须知

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

Vercel 上的环境变量

当将您的 Next.js 应用程序部署到 Vercel 时，可以在 项目设置 中配置环境变量。

所有类型的环境变量都应在那里配置。甚至在开发中使用的环境变量 – 也可以 下载到您的本地设备上。

如果您已配置 开发环境变量，您可以使用以下命令将它们拉取到 .env.local 中，以便在本地计算机上使用：

vercel env pull

须知：当将您的 Next.js 应用程序部署到 Vercel 时，除非您的环境变量名称以 NEXT_PUBLIC_ 为前缀，否则 .env* 文件中的环境变量将无法用于 Edge Runtime。我们强烈建议您在 项目设置 中管理您的环境变量，所有环境变量都可以在那里使用。

测试环境变量

除了 development 和 production 环境之外，还有第三个选项：test。就像您可以为开发或生产环境设置默认值一样，您可以为 testing 环境使用 .env.test 文件执行相同的操作（尽管这个文件不像前两个文件那么常用）。在 testing 环境中，Next.js 不会从 .env.development 或 .env.production 加载环境变量。

当使用 jest 或 cypress 等工具运行测试时，这非常有用，您需要在其中仅出于测试目的设置特定的环境变量。如果 NODE_ENV 设置为 test，则将加载测试默认值，尽管您通常不需要手动执行此操作，因为测试工具会为您处理。

test 环境与 development 和 production 环境之间存在一个小的差异，您需要记住：.env.local 不会被加载，因为您希望测试为每个人产生相同的结果。这样，每次测试执行都会通过忽略您的 .env.local（旨在覆盖默认设置）来使用相同的 env 默认值。

须知：与默认环境变量类似，.env.test 文件应包含在您的存储库中，但不应包含 .env.test.local，因为 .env*.local 旨在通过 .gitignore 忽略。

在运行单元测试时，您可以确保使用与 Next.js 相同的方式加载环境变量，方法是利用 @next/env 包中的 loadEnvConfig 函数。

// 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 dev 命令时，Next.js 会自动分配 development，对于所有其他命令，则分配 production。

版本历史