API Key 无效或缺失排查清单

这份清单适合在本地项目、部署平台或客户小单里排查 API Key 无效、缺失、权限不足的问题。它的重点不是“快速试到能跑”，而是让每一步都有记录、可复查、不会泄露密钥。你可以把它放进项目笔记，配合 /tools/error-explainer 和 /templates 使用。

适合谁

适合正在调试 AI API、支付 API、邮件 API、自动化接口或第三方服务 SDK 的新手。你已经能运行项目，但看到认证相关报错，不确定问题出在代码、变量、账号还是部署平台。

也适合准备接一个小型排错任务的人。只要客户能用测试环境复现报错，并且愿意自己管理敏感凭据，你就可以按清单协助排查。

不适合谁

不适合需要直接接管客户生产账号、账单后台、管理员权限或真实密钥的任务。若客户只能通过发送完整密钥让你处理，应先建议改用屏幕共享、临时测试密钥或最小权限授权。

也不适合没有日志和复现步骤的任务。如果客户只说“线上坏了”，但没有错误信息、触发路径、部署记录或最近变更，你很难做出可靠判断。

具体步骤

1. 记录错误原文：状态码、错误码、接口路径、运行环境、出现时间。
2. 脱敏保存证据：截图或日志里只保留密钥前后少量字符，删除中间内容。
3. 检查变量名：.env、代码读取名称、部署平台变量名称是否完全一致。
4. 检查加载位置：密钥是否只在服务端读取，是否被误放进浏览器端代码。
5. 重启本地服务：修改 .env 后重新启动开发服务器，再测试一次。
6. 检查线上变量：Vercel、Railway、Render 或其他平台是否配置了同名变量。
7. 重新部署线上环境：确认变量写入后，触发一次新的部署。
8. 检查账号状态：额度、计费、项目归属、模型权限、组织选择是否正确。
9. 检查代码路径：请求是否真的走到使用该变量的位置，是否有旧缓存或旧配置。
10. 写出结论：问题原因、修改内容、测试结果、后续注意事项。

项目前检查

客户是否愿意提供可脱敏的错误信息？是否能说明报错发生在本地、测试环境还是线上？是否可以创建测试密钥？如果这三个问题都答不上来，先不要报价为“修复完成”，可以只报价为“诊断和排查报告”。

还要确认客户是否理解密钥安全。你可以明确写：我不会要求你发送完整密钥；你需要自行在平台创建、撤销和保存密钥；我只检查变量名、读取位置、部署配置和测试结果。

交付前检查

交付时至少给客户四样东西：排查记录、修改位置、测试结果、密钥后续管理建议。不要只说“已经好了”。更好的写法是：“线上环境变量名称已更正，重新部署后测试接口返回正常；旧密钥是否撤销由客户在平台后台确认。”

如果发现密钥疑似泄露，要把“撤销旧密钥、生成新密钥、检查账单和访问记录”列为优先事项。不要为了赶进度继续使用旧密钥。

风险提醒

密钥不是普通配置项。它可能绑定费用、数据访问、模型权限和客户账号责任。任何截图、日志、提交记录、聊天记录都要先脱敏。若你不确定某段代码会不会被公开打包，就先不要放真实密钥。

客户沟通模板

我可以协助排查 API key 无效或缺失的问题，但不会要求你发送完整密钥。
请先提供以下脱敏信息：
1. 错误原文或状态码。
2. 报错发生在本地、测试环境还是线上。
3. 变量名截图，密钥内容请遮挡中间部分。
4. 最近是否修改过部署、套餐、模型权限或项目组织。

如果需要重新生成密钥，请由你在平台后台自行操作；我只根据配置位置和测试结果判断下一步。

验收记录

排查完成后，不要只用“已修复”三个字收尾。建议写成一段可复查记录：报错原因是什么，修改了哪个变量或部署配置，是否重新部署，测试接口返回什么结果，客户还需要自己确认什么后台状态。

如果最终发现问题来自客户账号额度、计费、权限或模型开通状态，也可以交付诊断结论。诊断结论不是失败，它说明技术配置没有继续修改的空间，下一步需要客户在账号后台处理。只要项目前写清楚“诊断”和“修复”的区别，这种交付也是合理的。

免责声明

本文仅供学习和排错流程参考，不构成安全、法律、财务或平台合规建议。不同服务商的密钥规则和错误码不同，发布前需要人工复核官方文档。做项目时请遵守平台规则、客户授权边界和最小权限原则。

CTA：把这份清单复制到你的排错笔记里；需要写客户回复时，可先用 /tools/proposal-generator 生成草稿，再人工补上真实错误、范围和验收方式。