React / 系统课时

管理环境变量

管理环境变量

Next.js 会同时运行服务端代码和浏览器代码,环境变量一旦跨错边界就可能泄露密钥。本节用一个最小 App Router 示例区分私有变量与 NEXT_PUBLIC_ 变量,并建立本地、构建和生产环境的安全配置习惯。

学习目标

  • 区分只在服务端读取的私有变量与可进入浏览器包的公开变量
  • 使用 .env.local 配置本地环境,并验证敏感值不会通过接口返回
  • 识别构建时固化、版本库泄露和变量缺失这三类常见风险

先划清服务端与客户端边界

普通环境变量默认用于服务端,例如数据库密码、签名密钥和第三方服务令牌。需要让浏览器代码读取的变量必须显式使用 NEXT_PUBLIC_ 前缀,这类值会进入客户端可见的 JavaScript,因此只能放站点名、公开分析 ID 等非敏感配置。

服务端私有变量与客户端公开变量的边界

配置一个不会泄密的最小示例

在项目根目录创建 .env.local。如果项目使用 src 目录,环境文件仍放在项目根目录,而不是 src 内。

bash
APP_SECRET=dev-only-secret
NEXT_PUBLIC_APP_NAME=Anystack Demo

这段配置的生效行为是:APP_SECRET 只供服务端代码读取;NEXT_PUBLIC_APP_NAME 可以在客户端代码中使用。.env.local 应保持在 .gitignore 中,生产密钥则优先由部署平台或运行环境注入。

再创建 app/api/env-check/route.ts,只返回“变量是否存在”,不要把密钥本身写进响应、日志或错误信息。

ts
export async function GET() {
  const hasSecret = Boolean(process.env.APP_SECRET)

  return Response.json({
    appName: process.env.NEXT_PUBLIC_APP_NAME ?? null,
    hasSecret,
  })
}

启动开发服务器后验证接口:

bash
curl -s http://localhost:3000/api/env-check

预期输出:

json
{"appName":"Anystack Demo","hasSecret":true}

输出证明服务端读取到了私有变量,但响应里没有出现 dev-only-secret。若改动 .env.local 后结果未更新,重启开发服务器再验证;环境变量通常在进程启动或构建阶段读取。

选择正确的环境文件和注入位置

Next.js 会按环境加载 .env* 文件,本地开发通常用 .env.local 覆盖个人配置,团队可把不敏感的默认值放在 .env 或特定环境文件中。测试环境应避免依赖开发者私有覆盖,以保证 CI 与本机结果一致。

生产环境不要把真实凭据写进仓库中的 .env.production。更稳妥的做法是让 CI、容器平台或云部署平台在运行时注入私有变量,并限制只有应用服务账号能够读取。对客户端公开变量则要记住:修改值后往往需要重新构建前端产物。

把变量缺失当作启动错误

敏感配置最危险的失败方式不是“变量不存在”,而是应用带着空值继续运行。服务端模块可以在首次使用前做显式检查,让错误尽早暴露。

ts
export function requireEnv(name: string): string {
  const value = process.env[name]

  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`)
  }

  return value
}

这是片段示例,调用它的服务端模块应传入诸如 APP_SECRET 的真实变量名。验证方法是在本地临时删除对应变量并重启开发服务器,预期请求会明确失败,而不是使用空字符串继续访问外部服务。

环境变量的安全原则可以归结为一条边界:只有确认可以公开给所有浏览器用户的值,才使用 NEXT_PUBLIC_;其余凭据只在服务端读取,并由部署环境负责注入和轮换。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理环境变量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通