环境变量
示例
Next.js 内置了对环境变量的支持,允许你执行以下操作
警告: 默认的
create-next-app
模板确保所有.env
文件都添加到你的.gitignore
中。你几乎永远不想将这些文件提交到你的代码仓库。
加载环境变量
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 './envConfig.ts'
export default defineConfig({
dbCredentials: {
connectionString: process.env.DATABASE_URL!,
},
})
引用其他变量
Next.js 将自动展开使用 $
引用其他变量的变量,例如 $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_
前缀。例如
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk
这将告诉 Next.js 将 Node.js 环境中对 process.env.NEXT_PUBLIC_ANALYTICS_ID
的所有引用替换为你运行 next build
的环境中的值,从而允许你在代码中的任何位置使用它。它将被内联到发送到浏览器的任何 JavaScript 中。
注意:构建完成后,你的应用程序将不再响应对这些环境变量的更改。例如,如果你使用 Heroku 管道将在一个环境中构建的 slugs 提升到另一个环境,或者如果你构建并将单个 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 可以同时支持构建时和运行时环境变量。
默认情况下,环境变量仅在服务器上可用。要将环境变量暴露给浏览器,它必须以 NEXT_PUBLIC_
为前缀。但是,这些公共环境变量将在 next build
期间内联到 JavaScript 包中。
你可以在动态渲染期间安全地在服务器上读取环境变量
import { connection } from 'next/server'
export default async function Component() {
await connection()
// cookies, headers, and other Dynamic APIs
// will also opt into dynamic rendering, meaning
// this env variable is evaluated at runtime
const value = process.env.MY_VALUE
// ...
}
这允许你使用单个 Docker 镜像,该镜像可以在具有不同值的多个环境之间提升。
须知
- 你可以使用
register
函数在服务器启动时运行代码。 - 我们不建议使用
runtimeConfig
选项,因为它不适用于独立输出模式。相反,如果你需要此功能,我们建议逐步采用 App 路由。
Vercel 上的环境变量
当将你的 Next.js 应用程序部署到 Vercel 时,可以在项目设置中配置环境变量。
所有类型的环境变量都应在那里配置。甚至是在开发环境中使用的环境变量——可以下载到你的本地设备之后。
如果你已经配置了开发环境变量,你可以使用以下命令将它们拉取到 .env.local
中,以便在本地计算机上使用
vercel env pull
须知:当将你的 Next.js 应用程序部署到 Vercel 时,除非你的环境变量名称以
NEXT_PUBLIC_
为前缀,否则.env*
文件中的环境变量将不会提供给 Edge Runtime。我们强烈建议在项目设置中管理你的环境变量,从那里可以获得所有环境变量。
测试环境变量
除了 development
和 production
环境外,还有第三个可用选项:test
。与你可以为开发或生产环境设置默认值的方式相同,你可以为 testing
环境使用 .env.test
文件执行相同的操作(尽管这一个不如前两个常见)。在 testing
环境中,Next.js 不会从 .env.development
或 .env.production
加载环境变量。
当使用 jest
或 cypress
等工具运行测试,并且你需要仅为测试目的设置特定的环境变量时,这非常有用。如果 NODE_ENV
设置为 test
,则将加载测试默认值,尽管你通常不需要手动执行此操作,因为测试工具会为你处理它。
test
环境与 development
和 production
环境之间存在一个小的差异,你需要记住:.env.local
将不会加载,因为你期望测试为每个人产生相同的结果。这样,每次测试执行都将通过忽略你的 .env.local
(旨在覆盖默认设置)来使用相同的 env 默认值。
须知:与默认环境变量类似,
.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
(当NODE_ENV
为test
时不检查。).env.$(NODE_ENV)
.env
.env
例如,如果
NODE_ENV
是development
并且你在.env.development.local
和.env
中都定义了一个变量,则将使用.env.development.local
中的值。
须知:NODE_ENV
的允许值为 production
、development
和 test
。
- 须知
- 如果你正在使用
/src
目录,则.env.*
文件应保留在项目的根目录中。
如果环境变量 NODE_ENV
未分配,则在运行 next dev
命令时,Next.js 会自动分配 development
,对于所有其他命令,则会自动分配 production
。
版本历史 | 版本 |
---|---|
变更 | v9.4.0 |
这是否有帮助?