用途:为 Next.js 项目提供环境变量的命名约定、文件组织与安全实践,适用于新项目环境配置、新增变量、环境安全审查、创建 .env.example 模板以及环境问题排查。
主要能力:定义 .env、.env.local、.env.development、.env.production、.env.example 的用途与是否提交 git,并给出加载顺序(后者覆盖前者):.env、.env.local、.env.development/.env.production(按 NODE_ENV)、.env.development.local/.env.production.local。规定仅以 NEXT_PUBLIC_ 前缀的变量可到达浏览器;推荐 SCREAMING_SNAKE_CASE 命名、按服务分组、第三方加前缀。提供基于 zod 的类型安全校验思路(如 src/lib/env.ts 在模块加载时 safeParse 并快速失败),以及客户端 env-client.ts 校验方式。给出 .env.example 模板结构(应用、数据库、认证、OAuth、第三方服务、开发专用)。
用法要点:复制模板 cp .env.example .env.local;本地启动 Docker 服务 docker compose up -d 后 npm run dev;生成密钥可用 openssl rand -base64 32、openssl rand -hex 32、uuidgen;部署平台可设变量,如 railway variables --set KEY=...、vercel env add KEY production,AWS 可用 Secrets Manager 存储并引用。
限制与安全:真实密钥绝不提交,.env.local 等含密钥文件须加入 .gitignore;.env.example 仅放占位值;禁止给密钥加 NEXT_PUBLIC_ 前缀;生产变量在部署平台设置,不写入提交文件。常见问题包括变量未加载(文件名、重启服务、大小写)、客户端无法访问(缺少前缀或未重新构建)、值被覆盖(加载顺序、清理 .next 缓存)、本地正常生产失败(平台变量、名称匹配、空格引号)。资料未提供该技能的具体安装命令与收费信息。