# 环境变量

本文档适用于 9.4 和更高版本的 Next.js。如果你使用的是较旧版本的 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

这回将 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 将在构建时会将 process.env.*替换为对应的值。这就意味着 process.env不是标准的 JavaScript 对象，因此你不能对其使用 对象解构（object destructuring） 语法。环境变量应当以类似 process.env.PUBLISHABLE_KEY方式访问，而不能以 const { PUBLISHABLE_KEY } = process.env方式。

注意： Next.js 会在 .env*文件中自动扩展变量（例如 $VAR）。这允许你访问其它的密钥类信息，如下所示：

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

如果你尝试使用实际值中带有 $符号的变量，则需要像这样 \$对其进行转义。

例如：

# .env
A=abc

# 扩展为 "preabc"
WRONG=pre$A

# 扩展为 "pre$A"
CORRECT=pre\$A

# 将环境变量暴露给浏览器

默认情况下，环境变量仅在 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 can be used here as it's prefixed by NEXT_PUBLIC_
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

# 默认环境变量

通常只需要一个 .env.local文件就够了。但是，有时你可能希望分别为 development(next dev) 或 production(next start) 环境添加一些默认设置。

Next.js允许你在 .env（所有环境下）、.env.development（development 环境）和 .env.production（production 环境）中设置默认值。

.env.local始终覆盖默认设置。

注意：由于 .env、.env.development和 .env.production文件定义了默认设置，因此应该提交到源码仓库中。而 .env.*.local应当添加到 .gitignore中，因为这类文件是需要被忽略的。.env.local是被用来存储密钥类信息的。

# Environment Variables on Vercel

When deploying your Next.js application to Vercel , Environment Variables can be configured in the Project Settings .

All types of Environment Variables should be configured there. Even Environment Variables used in Development – which can be downloaded onto your local device afterwards.

If you've configured Development Environment Variables you can pull them into a .env.localfor usage on your local machine using the following command:

vercel env pull .env.local

When using the Vercel CLI to deploy make sure you add a .vercelignore that includes files that should not be uploaded, generally these are the same files included in .gitignore.

# 测试环境变量

除了 development和 production环境，还有第三个环境： test。与为 development 和 production 环境设置默认值类似，你可以使用 .env.test为 test 环境设置变量（尽管此文件并不如前两个文件常见）。

当使用 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)
}

← TypeScript Supported Browsers and Features →