Key 无效API Key 格式 / 轮换
invalid API key：密钥无效、格式错误或泄露后怎么处理
invalid API key 是 401 的最常见具体原因。重点检查复制完整性、前后空白、环境变量名、Key 所属平台和泄露轮换。
排查结论
先用最小请求隔离问题：只保留 API Key、Base URL、模型名和一条 ping 消息。最小请求失败，先修配置；最小请求成功，再回到业务代码排查并发、上下文和部署环境。
1. 问题现象
- 错误信息明确出现 invalid API key、Incorrect API key provided、API key not valid 或 malformed key。
- 同一个 Base URL 下，换成新 Key 后马上恢复。
- 本地 .env 修改了，但运行中的进程仍使用旧 Key。
- 把 Key 放到前端、截图或仓库后，平台自动禁用了该 Key。
2. 最可能原因
Key 复制不完整、开头结尾带空格或换行。
环境变量名写错，例如代码读 OPENAI_API_KEY，实际写了 OPENAI_KEY。
开发工具缓存旧配置，重启前没有重新读取 .env。
Key 泄露后被平台或你自己撤销。
把 Gemini、Anthropic、OpenAI 兼容平台的 Key 混用。
3. 快速排查清单
1
不要继续使用可疑 Key
如果 Key 出现在公开仓库、截图、聊天记录或前端代码里，立即删除并重新生成。
2
修剪空白字符
读取环境变量后 trim，但不要在日志里输出完整值。
3
确认变量名一致
.env、部署平台 Secret、代码里的 getenv 名称必须完全一致。
4
重启进程和工具
Next.js、Node、Python、Claude Code、Codex 等进程通常不会自动重读已经加载的环境变量。
5
一平台一 Key
不要把同一个变量名 API_KEY 在多个平台间复用，建议按供应商命名。
4. 对应 API 的特殊情况
Gemini
AI Studio Key 常见前缀是 AIza；不要把它传给 OpenAI SDK 的 OpenAI 官方 Base URL。
Anthropic
Anthropic Key 常见前缀是 sk-ant；直连时用 Anthropic SDK 或 x-api-key。
OpenAI 兼容国产平台
即使都能用 OpenAI SDK，Key 仍然只在各自平台有效，不能跨平台通用。
工具类应用
CC Switch、Claude Code、Codex 等工具可能有自己的配置文件；改了 .env 不代表工具配置已更新。
5. 可复制的修复示例
Node.js 启动时校验 Key，并避免完整日志泄露
typescript
function readRequiredSecret(name: string) {
const value = (process.env[name] ?? "").trim();
if (!value) {
throw new Error(name + " 未配置或为空");
}
const masked = value.slice(0, 4) + "..." + value.slice(-4);
console.log(name + " loaded:", masked, "length:", value.length);
return value;
}
const apiKey = readRequiredSecret("DEEPSEEK_API_KEY");只记录脱敏信息，既能排查加载问题，也不会泄露完整 Key。
发现泄露后的处理顺序
bash
# 1. 到平台控制台删除已泄露的 API Key
# 2. 重新创建一个新 Key
# 3. 更新服务器环境变量或 Secret
# 4. 重启应用进程
# 5. 检查 Git 历史、日志和截图里是否仍保留旧 Key不要只在 .env 里改值；旧 Key 必须在控制台删除。