NNext.js 中文网 GitHub

如何在 Next.js 中使用环境变量

了解如何在 Next.js 应用程序中添加和访问环境变量。

Next.js 内置了对环境变量的支持,使你能够执行以下操作:

警告:默认的 create-next-app 模板确保所有 .env 文件都添加到你的 .gitignore 中。你几乎永远不应将这些文件提交到代码仓库。

加载环境变量#

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

.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:

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* 文件中使用多行变量:

bash
# .env

# 你可以用换行符书写
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# 或者在双引号内使用 \n
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

注意:如果你使用 /src 文件夹,请注意 Next.js 将仅从父文件夹加载 .env 文件,而不会从 /src 文件夹加载。 这会将 process.env.DB_HOST、process.env.DB_USER 和 process.env.DB_PASS 自动加载到 Node.js 环境中,使你能够在 Route Handlers 中使用它们。

例如:

app/api/route.js
export async function GET() {
  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 函数加载环境变量:

bash · pnpm
pnpm add @next/env
bash · npm
npm install @next/env
bash · yarn
yarn add @next/env
bash · bun
bun add @next/env
envConfig.ts
import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)
envConfig.js
import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

然后,你可以在需要的地方导入配置。例如:

orm.config.ts
import './envConfig.ts'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})
orm.config.js
import './envConfig.js'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
})

引用其他变量#

Next.js 将自动展开 .env* 文件中使用 $ 引用其他变量的变量,例如 $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_ 前缀。例如:

.env
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

请注意,动态查找 不会 被内联,例如:

js
// 这不会被内联,因为它使用了变量
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// 这不会被内联,因为它使用了变量
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

运行时环境变量#

Next.js 可以同时支持构建时和运行时环境变量。

默认情况下,环境变量仅在服务端可用。要将环境变量暴露给浏览器,必须为其添加 NEXT_PUBLIC_ 前缀。但是,这些公共环境变量将在 next build 期间内联到 JavaScript 包中。

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

在动态渲染期间,你可以安全地在服务端读取环境变量:

app/page.ts
import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies、headers 和其他请求时 API
  // 也会选择动态渲染,这意味着
  // 此环境变量在运行时计算
  const value = process.env.MY_VALUE
  // ...
}
app/page.js
import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies、headers 和其他请求时 API
  // 也会选择动态渲染,这意味着
  // 此环境变量在运行时计算
  const value = process.env.MY_VALUE
  // ...
}

这使你能够使用单个 Docker 镜像,并通过多个具有不同值的环境进行提升。

小知识:

测试环境变量#

除了 development 和 production 环境外,还有第三个选项:test。就像你可以为开发或生产环境设置默认值一样,你也可以使用 .env.test 文件为 testing 环境设置默认值(尽管这不如前两种常见)。在 testing 环境中,Next.js 不会从 .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 相同的方式加载环境变量。

js
// 以下内容可用于 Jest 全局设置文件或类似的测试设置
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。

版本历史#

版本变更
v9.4.0引入了对 .env 和 NEXT_PUBLIC_ 的支持。
Next.js 中文网