401 在服务端调用里往往不是一个错误，而是一类错误。同一个状态码，可能来自密钥本身失效，可能来自进程读到的值和预期不一致，可能来自请求头构造错误，也可能来自请求还没到上游就被代理或网关拦下。这四层的原因和验证手段完全不同，混在一起试，结果就是反复换密钥却始终不好。

下面是一套通用的分层定位方法。具体产品的请求头名称、鉴权方案前缀、环境变量名、错误响应体结构，必须以对应官方文档为准，本文不替换官方约定。

先确认 401 是谁返回的

这一步能省掉一半时间。关键线索是响应体形态和响应头：

  • 上游返回的鉴权失败，通常带该服务自己的错误结构，例如 JSON 中的错误类型与 message 字段，以及便于排障的请求 ID。
  • 中间层（网关、WAF、负载均衡、鉴权代理）拦截，往往返回 HTML 错误页、纯文本，或者带自家 server 标识的响应头，错误结构和你调用的服务对不上。

如果响应体是 HTML，或请求 ID 明显由网关生成，就不该继续怀疑密钥，而应该去查转发链路。反过来，如果拿到的是结构化的鉴权错误，再往下走密钥与请求构造的排查。

顺带确认语义边界：有些实现会把配额、权限范围、账号状态问题也归到 401。这种情况下密钥本身没问题，改配置也不会好，需要按官方文档的错误码说明区分。

密钥被污染的几种形态

从控制台复制密钥，再粘贴到配置文件、CI secret、容器环境变量或 Serverless 配置，这条链路上会引入肉眼不可见的字符：

  • 结尾多一个换行 \n 或 \r\n
  • 被引号包住，引号也进了值："sk-..."
  • 复制时带入全角空格或其他不可见字符
  • 值被截断，尤其是跨屏复制时

不要靠肉眼比对，用长度和哈希做指纹：

printf '%s' "$API_KEY" | wc -c
printf '%s' "$API_KEY" | sha256sum | cut -c1-12
printf '%s' "$API_KEY" | tail -c 4 | xxd

在应用代码里对同一份配置值打印同样的两个数：长度和前 12 位哈希。两处指纹不一致，说明问题在传递过程，而不是密钥本身。注意日志里永远不要输出完整密钥，只输出长度、脱敏前缀或哈希。

环境变量在哪一层丢掉了

同样是「配了环境变量」，不同运行环境的生效路径并不一样：

  • 容器：docker run -e、Dockerfile 里的 ENV、--env-file，三者的优先级与覆盖关系需要实测确认，构建期注入和运行期注入是两件事。
  • Compose：environment 与 env_file 同时存在时，哪个生效取决于具体实现，别靠记忆。
  • CI：来自 fork 的 PR 通常拿不到 secret，这类失败只在特定触发方式下出现。
  • Serverless：配置变更后是否有未生效的旧实例、冷启动是否重新注入，需要在目标平台上验证。
  • systemd / pm2 等进程管理器：不继承登录 shell 中 export 的变量，本地手动跑得通、上了服务就 401，常见原因就在这里。
  • .env 文件：是否被加载、加载顺序如何、遇到已存在的同名变量是否覆盖，取决于所用库的实现，必须实测而不是假设。

验证手段很轻：在真正发起请求的那个进程里，只打印配置值的长度和哈希。如果长度是 0，说明是注入问题，与密钥内容无关。

请求头构造与中间层改写

到了这一层，值是对的，但请求出去时变了样：

  • 请求头名拼写或多了一个空格。HTTP/1.1 对头名大小写不敏感，但 HTTP/2 要求头名小写，自建网关做字符串精确匹配时容易漏掉。
  • 鉴权方案前缀后面的分隔符写错，比如把空格写成冒号，或在 token 前后引入多余空白。前缀大小写是否被接受，取决于服务端实现。
  • 中间件重复设置同一个头，最终变成逗号拼接的多值，服务端解析失败。
  • 带下划线的自定义头被 Nginx 等默认丢弃（underscores_in_headers 相关行为）。
  • 代理、网关或 CDN 重写、剥离 Authorization，或者节点间转发时丢了这一头。

最直接的定位方式是看最终出网的请求。可以在网关侧打开该路径的头日志，或在最小脚本里手工构造同一个请求，对比结果。如果手工请求通过、应用请求失败，问题就在应用到网关这一段。

另外要注意 SDK 读取密钥的顺序：显式传参和从环境变量读取谁优先，属于实现细节，必须以官方文档或源码为准，不能按常识推断。

用最小脚本把范围逐级收敛

每次只改一个变量，四步走：

  1. 用 curl 直接请求，头全部手工写死，排除 SDK 与框架封装。
  2. 用应用同一份代码读取环境变量后请求，排除值传递。
  3. 从容器 / Serverless 运行时内部发同一请求，排除注入时机。
  4. 换成经过网关的域名再发一次，排除转发链路。

骨架大致如下，其中路径、请求头名与请求体格式需要按官方文档替换：

curl -sS -D /tmp/headers -o /tmp/body \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST "${BASE_URL}/" \
  -d ''

先看 /tmp/headers 里的状态码与 server 类响应头，再看 /tmp/body 是不是目标服务的错误结构。这两条信息决定了下一步往哪走。

可以直接复用的检查清单

  • 配置值的长度是否与预期一致，尾部有无换行或引号
  • 应用内与配置源头的指纹（长度 + 短哈希）是否一致
  • 发起请求的进程里，该变量是否真的存在
  • 请求头名拼写、大小写、连字符是否正确
  • 鉴权方案前缀与 token 之间是否恰好一个空格
  • 是否存在重复设置的同一个头
  • 是否有下划线头的头名经过 Nginx 类组件
  • 网关日志中最终出网的 Authorization 是否完整
  • 失败是稳定复现还是只在冷启动、特定触发方式下出现
  • 401 与 403 的错误结构差异是否符合官方文档描述

从工程角度看，这类问题的成本大头不在修复，而在定位顺序。先确定返回方，再验证值的一致性，最后检查链路改写，绝大多数 401 会在前三步收敛。剩下的部分——头名约定、前缀规则、环境变量名、错误码语义——属于产品接口约定，必须回官方文档核对，而不是从其他服务的经验里外推。