调用 DeepSeek API 时收到 401，通常不是单一原因，而是请求链路上某一环没有把正确的凭证传递到服务端。本文按请求从客户端到服务端的顺序，逐层拆解排查路径，并提供可复现的定位方法。
重要提示：本文中的 API 端点、模型名称、认证头格式等均为示例占位符，仅用于演示排查思路。实际调用时，请以 DeepSeek 官方文档公布的最新信息为准。
第一层：确认 API Key 是否被正确加载
401 最常见的原因是代码里根本没有拿到有效的 Key。排查时不要先怀疑服务端，先确认客户端实际发送了什么。
本地开发场景：
- 检查环境变量是否在当前 shell 会话中生效。export 只对当前会话有效，新开终端或 IDE 重启后可能丢失。
- 检查 .env 文件是否被正确加载。不同框架加载 .env 的时机不同，有的在应用启动时读取，有的在首次调用时读取。如果代码在加载 .env 之前就发起了请求，Key 会是空值。
- 检查 Key 是否被意外截断。从网页复制时可能带入换行或空格，导致实际发送的字符串与预期不符。
生产部署场景：
- 检查密钥管理服务（如 Vault、KMS、Secrets Manager）注入的变量名是否与代码读取的变量名一致。大小写、下划线、前缀都可能导致读取失败。
- 检查容器编排配置中环境变量的传递路径。Kubernetes 的 Secret 挂载为文件还是环境变量，代码读取方式不同。
- 检查是否存在多套环境共用同一份配置，导致测试环境的 Key 被用于生产请求。
一个快速验证方法：在代码中打印 Key 的长度和前几位（不要打印完整 Key），确认它非空且长度符合预期。
第二层：检查 Authorization 请求头格式
如果 Key 已正确加载，下一步检查请求头。DeepSeek API 的认证头格式请以官方文档为准。以下为常见示例形式，仅用于说明排查思路：
Authorization: Bearer
常见错误包括：
- 缺少 Bearer 前缀，直接写成了 Authorization:。
- Bearer 与 Key 之间缺少空格，或使用了多个空格。
- 请求头名称拼写错误，例如 Authorisation 或 Auth。
- 在 SDK 中同时设置了全局默认头和单次请求头，后者覆盖了前者，导致实际发送的凭证为空。
用 curl 做最小复现（以下端点和模型名为示例占位符，请替换为官方文档中的实际值）：
# 注意：以下 URL 和 model 仅为示例，实际值请查阅 DeepSeek 官方文档
curl -X POST https:/// \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "",
"messages": [{"role": "user", "content": "ping"}]
}'
如果 curl 成功而代码失败，问题在客户端代码或 SDK 配置；如果 curl 也返回 401，问题在 Key 本身或网络链路。
第三层：排查反向代理与 API 网关
在本地开发中直连 API 通常不会遇到网关问题，但生产部署往往经过 Nginx、API Gateway、Service Mesh 等中间层。这些中间层可能：
- 过滤或重写
Authorization请求头。部分网关默认不转发认证头，需要显式配置白名单。 - 在转发时添加自己的认证头，覆盖了原始请求头。
- 对请求头大小写敏感，导致下游服务无法识别。
- 在重定向或重试时丢失请求头。
排查方法：在网关的访问日志中记录收到的 Authorization 头（注意脱敏），与客户端实际发送的值对比。如果网关日志中该头为空或与预期不符，问题就在网关配置。
对于使用 SDK 的场景，还要检查 SDK 是否自动添加了认证头，以及是否与手动设置的头冲突。部分 SDK 允许通过 default_headers 或类似参数覆盖，需要确认最终生效的是哪一个。
第四层：用日志对比定位问题层
当无法直接判断时，用二分法定位：
- 用 curl 直连 API，确认 Key 有效。
- 用 curl 经过网关访问，确认网关是否透传认证头。
- 用最小化代码（不依赖框架）调用 API，确认 SDK 或框架是否改写请求。
- 逐步加回业务代码，直到 401 复现。
每一步都记录实际发送的请求头和响应状态码。如果某一步从成功变为失败，问题就出现在该步引入的组件中。
配置检查清单
- API Key 非空，长度符合预期，无换行或空格。
- 环境变量在请求发起前已加载。
Authorization头格式符合官方文档要求，注意前缀与空格。- 请求头名称拼写正确，大小写符合服务端要求。
- 网关或代理已配置转发
Authorization头。 - SDK 或框架没有覆盖或清空认证头。
- 生产环境使用的 Key 与预期环境一致。
401 本身不区分“Key 无效”和“Key 未送达”，因此排查的核心是确认请求链路上每一环实际发送了什么。从客户端到服务端逐层对比，比反复更换 Key 更有效。