环境变量 missing 排查检查清单

环境变量缺失排查要先保护密钥，再定位问题。完整流程见 环境变量 missing 怎么排查。这篇是可以复制到项目诊断表里的检查清单。

适合谁

适合遇到本地或部署环境提示变量缺失的新手。你可以用它记录变量名、发生环境、配置位置和验证结果。

也适合项目前做诊断的人。清单能帮你避免一上来就索要客户密钥。

不适合谁

不适合需要直接处理客户真实密钥、生产数据库、支付配置、OAuth secret 或部署后台的新手独立操作。敏感配置要由客户确认和填写。

也不适合把 .env 文件整段发给 AI 分析的人。只记录变量名、用途和环境，不记录真实值。

风险提醒

环境变量任务的第一条规则是：不要泄露变量值。变量名可以出现在记录里，真实值不应出现在聊天、截图、代码、公开文档和交付记录里。

第二条规则是：区分环境。本地、预览、生产、CI、服务端、客户端都可能不同。只说“缺变量”太粗，无法指导下一步。

具体步骤

1. 报错记录

• 完整报错：
• 缺失变量名：
• 报错命令：
• 报错页面或接口：
• 首次出现时间：

只记变量名，不记变量值。

2. 环境记录

• 本地 dev：
• 本地 build：
• 预览部署：
• 生产部署：
• CI：
• 服务端或客户端：

确认到底是哪一个环境缺。

3. 项目说明

• 是否有 .env.example：
• README 是否列出变量：
• 配置文件是否校验变量：
• 部署文档是否提到变量：
• 是否有变量命名前缀规则：

项目已有说明时，优先按项目说明处理。

4. 变量类型

• 公开网站地址：
• 客户端可见变量：
• 服务端密钥：
• 数据库连接：
• 支付或邮件服务密钥：
• 功能开关：

类型不同，处理边界不同。

5. 配置位置

• 本地 env 文件：
• 部署平台开发环境：
• 部署平台预览环境：
• 部署平台生产环境：
• CI secret：
• 客户后台：

客户敏感值由客户自己配置。

6. 验证

• 重启本地 dev server：
• 重新运行 build：
• 重新部署：
• 检查目标页面：
• 检查日志是否还缺同一变量：

配置变量后通常需要重新运行命令或重新部署。

结论怎么写

结论建议分三类：变量名已确认但值待客户配置；变量所在环境待确认；变量用途不清需要查项目文档。不要把结论写成“让客户发 key”，那不是安全的交付方式。

如果你已经完成诊断，交付时写清：缺什么变量、在哪个环境缺、客户需要在哪里配置、配置后如何验证。这样客户可以自己完成敏感操作。

最低交付记录

最低交付记录至少包含七项：原始报错、变量名、发生环境、变量类型、建议配置位置、客户待确认事项、验证方式。每一项都只写必要信息，尤其不要写真实变量值。

如果变量是非敏感配置，比如公开站点地址，也可以写清示例格式；如果变量是数据库、支付、邮件、AI API 或 OAuth secret，只写“客户自行配置”，不要在交付记录中出现值。这个边界看起来啰嗦，但它能避免你把诊断服务变成密钥代管。

交付给客户时，可以附一句说明：为保护账号安全，本文档只列变量名和配置位置，不收集或保存真实密钥。

本地和线上差异怎么查

如果本地正常、线上失败，单独检查四件事。第一，本地是否有 .env.local 或其他本地配置文件。第二，部署平台的预览环境和生产环境是否都配置了同名变量。第三，变量名大小写是否完全一致。第四，配置后是否重新触发构建或重启服务。

这四项能覆盖很多常见问题。新手不要只写“线上缺变量”，而要写“生产环境缺某变量，预览环境已配置，配置后需要重新部署”。这样下一步才可执行，也能减少客户反复问你到底要做什么。

CTA：下一步

复制这份清单，先填变量名、发生环境、配置位置和验证命令。需要拆报错时用 报错解释器，需要估算诊断时间时用 报价计算器。

免责声明

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