环境变量 missing 怎么排查

环境变量 missing 通常不是单纯“少一行配置”。它可能发生在本地、测试环境、预览部署、生产部署、服务端代码或客户端代码里。新手最容易犯的错误，是看到缺变量就让客户把密钥发过来，或者把真实密钥写进代码和聊天记录。

先给一个安全顺序：只讨论变量名、用途和所在环境，不收集真实密钥值。先确认缺哪个变量、在哪个命令或页面报错、是本地缺还是部署平台缺，再决定由谁配置。短表可以看 环境变量缺失检查清单，误区看 环境变量缺失常见错误和解决步骤。

适合谁

适合遇到 missing env、environment variable is not defined、process.env 为空、Vercel 部署失败、API key 未配置、本地能跑线上失败的新手。

也适合准备接小型部署诊断任务的人。你可以帮助客户定位变量名、环境和配置位置，但不应该保存客户真实密钥。

不适合谁

不适合需要你接管客户账号、保存客户 token、配置生产密钥或访问真实用户数据的新手独立操作。环境变量经常包含数据库连接、支付密钥、邮件服务密钥、AI API key 和 OAuth secret，这些都属于敏感信息。

也不适合把 .env 文件直接贴给 AI 或客户群聊的人。变量名可以讨论，变量值要保护。

风险提醒

环境变量排查的核心风险是泄密。你要避免三件事：把密钥写进代码、把密钥贴进聊天、把客户密钥保存到自己的设备。客户项目里，敏感变量应由客户在自己的部署平台或密钥管理系统里配置。

另一个风险是环境混淆。本地 .env.local 有变量，不代表预览部署或生产部署也有。预览环境、生产环境、开发环境可能各自需要配置。

具体步骤

1. 保存原始报错。记录命令、页面、接口、部署平台日志和报错变量名。
2. 只记录变量名，不记录真实值。比如写 DATABASE_URL 缺失，不写具体连接串。
3. 判断发生环境。本地 dev、本地 build、预览部署、生产部署、服务端请求、客户端页面要分开。
4. 看项目说明。检查 README、.env.example、配置文件、校验脚本和部署说明。
5. 判断变量类型。公开变量、服务端密钥、数据库连接、第三方 API key、功能开关要区别处理。
6. 找配置位置。本地放本地 env 文件；部署平台放对应环境的变量配置；客户密钥由客户自己配置。
7. 重新验证。配置后重启 dev server、重新 build 或重新部署，并保存结果。

公开变量和敏感变量怎么分

很多前端框架会用命名前缀区分客户端可见变量。以 Next.js 常见习惯为例，带公开前缀的变量可能进入浏览器代码，不能放服务端密钥。没有公开前缀的变量通常只应在服务端使用，但具体规则仍要看项目框架和文档。

判断时不要只看变量名字。PUBLIC_SITE_URL 可能只是网站地址，风险较低；DATABASE_URL、STRIPE_SECRET_KEY、OPENAI_API_KEY、JWT_SECRET 这类通常应视为敏感。敏感变量只确认名称和用途，不复制真实值。

本地和部署平台为什么不一致

本地能跑，线上缺变量，常见原因有四个。第一，本地有 .env.local，部署平台没有配置。第二，预览环境配置了，生产环境没配置。第三，变量名大小写不一致。第四，部署后没有重新触发构建。

所以排查时要写清：变量在哪个环境缺、谁有权限配置、配置后需要重启还是重新部署。不要把所有问题都归结为“平台坏了”。

项目前怎么处理

把任务定义为“环境变量缺失诊断”。交付内容包括缺失变量名、出现位置、可能用途、建议配置环境、客户待确认事项。只有客户授权明确时，才协助配置；涉及真实密钥时，让客户自己在后台填写。

需要客户沟通稿时，可以用 Proposal 生成器 起草确认问题；需要估算诊断时间时，用 报价计算器。

CTA：下一步

把当前报错整理成四项：缺失变量名、出现环境、相关命令或页面、谁有权限配置。遇到日志看不懂时，用 报错解释器 拆原因。

免责声明

本文是学习和排查流程，不构成法律、财务、安全或职业承诺。实际处理环境变量必须结合项目文档、部署平台规则、客户授权和安全要求人工判断。