【Next】配置环境变量

Next.js

---

1) Next.js 支持的环境变量来源

• 项目根目录下的 .env* 文件（Next.js 会自动加载）。
• 运行时（CLI / CI / 系统）通过 shell 导出的环境变量（export FOO=bar / CI 环境变量）。
• next.config.js 中的 env（旧 API，不推荐长期使用；会把变量打包进客户端）。(Next.js)

说明：要在浏览器端可访问，变量名必须以 NEXT_PUBLIC_ 开头；否则只能在服务器端使用（server-side / Node 中）。(Next.js)

---

2) 常用 .env 文件与优先级（从高到低，Next 官方推荐的加载顺序）

（注意：下面以 NODE_ENV 决定的 mode 举例 —— development / production / test 等）

优先级（以高 → 低）通常为：

1. .env.local
2. .env.[mode].local（例如 .env.test.local）
3. .env.[mode]（例如 .env.test）
4. .env

也就是说，如果同一个变量在多个文件都定义，最先匹配到的文件值生效。在 NODE_ENV=test 时，.env.test.local 会覆盖 .env.test，而 .env.local（通用本地覆盖）通常优先于 mode-specific 文件。(Next.js)

---

3) 如何写「测试环境」的变量（文件方式）

常见做法是在仓库根目录创建：

• .env.test —— 测试环境共享变量（会被版本控制视情况而定，通常列入 .gitignore）
• .env.test.local —— 本机/敏感覆盖（绝对不要提交）

示例 .env.test：

DATABASE_URL=postgres://test:pass@localhost:5432/testdb
API_KEY=local-test-key
NEXT_PUBLIC_FEATURE_FLAG=false

如果你在本地或 CI 想覆盖敏感值，就放 .env.test.local（不提交）。Next 会在 NODE_ENV=test 时按上面优先级加载这些文件。(Next.js)

---

4) 如何通过脚本（package.json）控制：设置 NODE_ENV / 选择 mode

两种常见方式：

1) 直接在脚本里设置 NODE_ENV（UNIX）

{"scripts": {"test": "NODE_ENV=test jest"}
}

（注意：Windows 上直接这样写会有兼容性问题。）(Stack Overflow)

2) 推荐跨平台写法 — 用 cross-env（最常见）
先安装：

npm i -D cross-env

脚本：

{"scripts": {"test": "cross-env NODE_ENV=test jest","build:test": "cross-env NODE_ENV=test next build","start:test": "cross-env NODE_ENV=test next start"}
}

cross-env 确保在 Windows / macOS / Linux 下行为一致。也可用 dotenv-cli / env-cmd 在脚本启动前显式加载特定 .env 文件（见下）。(blog.jimmydc.com)

3) 用 dotenv-cli / env-cmd 显式加载某个 .env 文件（可选）

{"scripts": {"test": "dotenv -e .env.test -- jest"}
}

这样可以在不依赖 NODE_ENV 的情况下直接指定要加载的 env 文件。(Medium)

---