本文档适用于 9.4 和更高版本的 Next.js。如果你使用的是较旧版本的 Next.js,请参阅next.config.js 中的环境变量。
Next.js 内置了对环境变量的支持,让你可以执行以下操作:
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将在您的
.env*
文件中自动展开变量($VAR
)。 这允许你引用其他内置变量,比如:# .env HOSTNAME=localhost PORT=8080 HOST=http://$HOSTNAME:$PORT
如果您试图在实际值中使用一个带有
$
的变量,那么就需要像这样进行转义\$
.比如:
# .env A=abc WRONG=pre$A # becomes "preabc" CORRECT=pre\$A # becomes "pre$A"
默认情况下,通过 .env.local
加载的所有环境变量仅在 Node.js 环境中可用,这意味着它们不会暴露在浏览器中。
为了向浏览器公开一个变量,你必须在变量前面加上 NEXT_PUBLIC_
。例如:
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk
这个加载过程。自动地将 process.env.NEXT_PUBLIC_ANALYTICS_ID
放入Node.js环境中。允许您在代码中的任何位置使用它。由于 NEXT_PUBLIC_
前缀,该值将同步发送到浏览器的 JavaScript 中。
// 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
(开发环境)和 .env.production
(生产环境)中设置默认值。
.env.local
总是覆盖默认值设置。
注意:
.env
、.env.development
和.env.production
文件应该包含在存储库中,因为它们定义了默认值。.env*.local
应该添加到.gitignore
, 因为这些文件是要忽略的。.env.local
是可以储存秘密的地方。
当在 Vercel 上进行部署时,您可以在 Vercel dashboard 中的环境变量部分配置秘密。
您仍然可以使用 .env
、.env.development
和 .env.production
来添加默认值。
如果您已经配置了开发环境变量,您可以使用以下命令将它们拉入 .env.local
以便在本地机器上使用:
vercel env pull .env.local
除了 development
和 production
环境之外,还有第三个备选办法:test
。与您可以为开发或生产环境设置默认值的方式一样,您也可以为测试环境设置 .env.test
文件(尽管这个文件不如前两个文件那么常见)。
当使用诸如 jest
或 cypress
之类的工具运行测试时,这一点非常有用,因为您需要为测试目的设置特定的环境变量。如果 NODE_ENV
被设置为 test
,测试默认值将被加载,尽管您通常不需要手动执行此操作,因为测试工具将为您解决此问题。
test
与 development
(和production
)之间有一个很小的区别,即您需要记住:.env.local
不会加载,因为您期望测试对每个人都产生相同的结果。通过这种方式,每个测试执行将在不同的执行过程中使用相同的 env 默认值,方法是忽略您的.env.local
(其目的是覆盖默认设置)。
注意: 与默认环境变量类似,
.env.test
文件应该包含在存储库中,但是.env.test.local
不应该包含,因为.env*.local
应该通过.gitignore
设置忽略。