Next.js教程基本特性：环境变量

本文档适用于 9.4 和更高版本的 Next.js。如果你使用的是较旧版本的 Next.js，请参阅 next.config.js 中的环境变量。

示例

• 环境变量

Next.js 内置了对环境变量的支持，让你可以执行以下操作：

• 使用 .env.local 加载环境变量
• 将环境变量暴露给浏览器

加载环境变量

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.NEXT_PUBLIC_PUBLISHABLE_KEY 方式使用，而 不能 const { NEXT_PUBLIC_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

将环境变量暴露给浏览器

默认情况下，所有通过 .env.local 加载的环境变量仅在 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 被用来存储密钥类信息。

Vercel上的环境变量

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

应在此处配置所有类型的环境变量。甚至是开发中使用的环境变量-以后都可以下载到本地设备上。

如果您已经配置了开发环境变量，则可以.env.local使用以下命令将它们放入a以便在本地计算机上使用：

vercel env pull .env.local

使用Vercel CLI进行部署时，请确保添加了一个.vercelignore包含不应上传的文件的文件，通常这些文件与中包含的文件相同.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 来忽略的文件。