环境变量

例子

环境变量

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

使用 .env 文件加载环境变量
通过添加 NEXT_PUBLIC_ 前缀为浏览器打包环境变量

加载环境变量

Next.js 支持从.env*文件中加载环境变量到process.env。

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

注意: Next.js 还支持.env*文件中的多行变量：

# .env

# you can write with line breaks
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# or with `\n` inside double quotes
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 环境中，允许您在路由处理程序中使用它们。

例如:

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函数来加载环境变量：

npm install @next/env

import { loadEnvConfig } from "@next/env";

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

import { loadEnvConfig } from "@next/env";

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

接着，您可以在需要的地方导入配置。例如：

import "./envConfig.ts";

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

import "./envConfig.js";

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

引用其他变量

Next.js 将自动扩展在 .env* 文件中使用$引用其他变量的情况，例如$VARIABLE。这允许您引用其他的密钥。例如：

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]的所有引用。要实现这一点，您只需在变量名前加上 NEXTPUBLIC 前缀。例如：

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

这将告诉 Next.js 在 Node.js 环境中将process.env.NEXT_PUBLIC_ANALYTICS_ID的引用替换为构建时的环境值，允许您在代码中的任何地方使用它。它会被嵌入到发送到浏览器的 JavaScript 中。

注意: 构建后，应用程序将不再响应这些环境变量的更改。例如，如果您使用 Heroku 管道将一个环境中构建的 slug 提升到另一个环境，或者将单个 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 同时支持构建时和运行时的环境变量。

**默认情况下，环境变量仅在服务器上可用。**要让环境变量在浏览器中可见，必须以 NEXTPUBLIC 为前缀。然而，这些公共环境变量将在 next build 期间被嵌入到 JavaScript 包中。

要读取运行时环境变量，我们建议使用getServerSideProps或逐步采用 App Router。通过 App Router，我们可以在动态渲染期间安全地在服务器上读取环境变量。这样，您可以使用一个 Docker 镜像，在多个环境中使用不同的值进行部署。

import { unstable_noStore as noStore } from "next/cache";

export default function Component() {
  noStore();
  // cookies(), headers(), and other dynamic functions
  // will also opt into dynamic rendering, meaning
  // this env variable is evaluated at runtime
  const value = process.env.MY_VALUE;
  // ...
}

您需要知道:

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

默认环境变量

通常情况下，只需要一个 .env*文件。然而，有时您可能希望为development (next dev)或production (next start)环境添加一些默认值。

Next.js 允许您在.env（所有环境）、.env.development（开发环境）和 .env.production（生产环境）文件中设置默认值。

您需要知道: .env、 .env.development和.env.production文件应该包含在您的仓库中，因为它们定义了默认值。所有的.env文件默认都会被排除在.gitignore文件之外, 允许您选择将这些值提交到仓库中。

Vercel 上的环境变量

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

所有类型的环境变量都应该在那里进行配置。即使是用于开发的环境变量，也可以下载到您的本地设备进行使用。

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

vercel env pull

您需要知道:当将您的 Next.js 应用部署到Vercel时，.env*文件中的环境变量不会被提供给 Edge Runtime，除非它们的名称带有 NEXTPUBLIC 前缀。.env*文件中的环境变量不会被提供给 Edge Runtime，除非它们的名称带有NEXT_PUBLIC_前缀。我们强烈建议在项目设置中管理您的环境变量，从那里可以访问所有的环境变量。

测试环境变量

除了development和production环境外，还有第三个选项： test。您可以像为开发或生产环境设置默认值一样，为test环境创建.env.test文件（虽然这种情况并不像前两种那样常见）。Next.js 不会在 test 环境中加载 .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 的加载方式相同。

// 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);
};

环境变量的加载顺序

环境变量按顺序在以下位置查找，一旦找到变量就停止：

process.env
.env.$(NODE_ENV).local
.env.local (Not checked when NODE_ENV is test.)
.env.$(NODE_ENV)
.env

提示：NODE_ENV 的允许值为 production、development 和 test。

例如，如果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。

版本历史

Version	Changes
`v9.4.0`	开始支持`.env` 和 `NEXT_PUBLIC_` 。

加载环境变量​

使用@next/env加载环境变量​

引用其他变量​

为浏览器打包环境变量​

运行时环境变量​

默认环境变量​

Vercel 上的环境变量​

测试环境变量​

环境变量的加载顺序​

您需要知道​

版本历史​