加载环境变量

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,
  })
  // ...
}

注意: 为了保证仅服务器加密安全,环境变量在构建时期评估,因此仅仅实际被使用的环境变量才会被包括,这意味着process.env并不是标准的js对象,因此它不能够使用对象解构,环境变量必须直接引用而不是解构,例如:

process.env.PUBLISHABLE_KEY,而不是const { PUBLISHABLE_KEY } = process.env

注意:

Next.js 将自动的扩展变量($VAR) 包含在.env*文件中的这一类变量,允许引用其他秘密 ..

HOSTNAME=localhost PORT=8080 HOST=http://$HOSTNAME:$PORT

如果你尝试使用$作为实际的值,需要进行转移: \$

例如:

# .env A=abc # becomes "preabc" WRONG=pre$A # becomes "pre$A" CORRECT=pre\$A

注意到: 如果你使用/src目录,请注意next.js 将自动加载 .env 文件(仅仅从父目录并且不会从/src目录中加载 ..

暴露环境变量到浏览器中

默认情况仅仅存在于node.js环境中,为了这样做,为环境变量添加前缀

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

process.env.NEXT_PUBLIC_ANALYTICS_ID将自动的加载到node环境中,允许在应用中的任何代码处使用,这个值将自动的内联到js中并发送到浏览器(因为NEXT_PUBLIC_前缀 .. 这内联发生在构建时期,因此你的各种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_'.
// 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)

默认的环境变量

通常,仅仅只有.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中,环境变量能够在项目配置中进行设置 … 所有类型的环境变量都应该在这里配置,即使在开发中使用的环境变量,这些能够稍后下载到你本地的设备 …

如果你已经配置了开发环境变量,你能够拉取它们到一个.env.local,本地通过以下命令进行进行拉去并后续用于使用

vercel env pull .env.local

Test 环境变量

除了开发和生产环境之外,还有第三种选择,test,同样,你可以设置.env.test文件来设置测试环境的环境变量(尽管这是一种不常见的情况),next.js 将不会从.env.development或者 .env.production中加载(如果处于测试环境) ..

当使用工具运行测试的时候这非常有用(例如jest或者cypress),为了测试目的去设置特定的环境属性值的时候 … test默认值将会被加载(如果NODE_ENV设置为test,尽管你通常不需要手动的这样做,因为测试工具已经帮你处理了)…

但是在test环境与其他环境development以及 production中唯一有一点小小的不同是你需要时刻记住: .env.local不会被加载,因为你期待每次对于每一个人产生相同的效果 …(这是故意这样做的) …

注意到:

类似于默认环境变量,.env.test文件应该包括在你的仓库中,但是.env.test.local不应该,因为由于.env*.local打算覆盖默认配置,所以应该被.gitignore

当你需要运行单元测试(你可能确保加载你的环境变量 - 以相同的方式通过利用

loadEnvConfig函数进行加载(来自next/env) ..

// 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_ENVis test)
.env.$(NODE_ENV)
.env

举个例子,如果NODE_ENV是development并且定义了一个变量同时在

.env.development.local以及 .env,那么.env.development.local的环境变量将被使用 …

NODE_ENV允许的值是production,development,test…

也就是在项目构建时会将对应的文件扫描,然后查询的时候根据上述的顺序进行查询,找到即可返回 …

Environment Variables - 图1