环境变量

示例

环境变量

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 环境中，您可以在 Next.js 数据获取方法和 API 路由中使用它们。

例如，使用 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,
  })
  // ...
}

引用其他变量

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 可以在构建时将值"内联"到发送给客户端的 JavaScript 包中，将所有对 process.env.[变量] 的引用替换为硬编码值。要实现这一点，只需在变量前添加 NEXT_PUBLIC_ 前缀。例如：

Terminal

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

这将指示 Next.js 在运行 next build 时，用环境中的值替换 Node.js 环境中所有对 process.env.NEXT_PUBLIC_ANALYTICS_ID 的引用，允许您在代码的任何地方使用它。它会被内联到发送给浏览器的任何 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