用途:本技能用于管理 Next.js 应用的环境变量,涵盖文件结构、变量类型与部署配置。
文件与优先级:项目可包含 .env(共享默认,提交)、.env.local(本地密钥,gitignore)、.env.development、.env.development.local、.env.production、.env.production.local、.env.test、.env.example。加载优先级从高到低为 .env.$(NODE_ENV).local、.env.local(测试环境不加载)、.env.$(NODE_ENV)、.env。例如生产中 DATABASE_URL 同时存在于 .env 与 .env.production.local 时,取后者。
变量类型:客户端变量必须以 NEXT_PUBLIC_ 前缀,会暴露给浏览器;服务端变量仅在 API 路由、getServerSideProps 等服务端代码可用。资料明确警告不得把密钥放入 NEXT_PUBLIC_* 变量。
部署到 Vercel:在项目设置的环境变量中逐项添加键值并选择环境;NEXT_PUBLIC_* 在构建时注入,修改后需重新部署,命令为 vercel --prod。
校验流程:资料给出脚本命令,如 python scripts/validate_env.py .env.local --framework nextjs、--compare-with .env.example、python scripts/scan_exposed.py --check-gitignore,以及同步命令 python scripts/sync_secrets.py --platform vercel --compare/--sync --dry-run/--sync --confirm。
常见问题:浏览器中变量为 undefined 需补 NEXT_PUBLIC_ 前缀;修改后未生效需重新部署;本地可用生产失败需核对变量是否已在 Vercel 设置。安全清单要求本地文件加入 .gitignore,不在提交文件中放真实密钥,.env.example 只保留结构。具体脚本实现、依赖与平台细节暂未提供。