使用nginx-jwt-module从Cookie验证JWT出现解析失败如何解决

• 第一步 校验JWT本身格式合法性 #

  先提取请求Cookie中携带的JWT字符串，离线校验格式：
  • 确认JWT是标准的三段式结构，由.分隔为Header、Payload、Signature三部分，没有缺失段、多余空格、换行或特殊转义字符
  • 确认JWT签名使用的算法为模块支持的HS256/HS512等对称加密算法
  • 用相同的密钥本地生成测试JWT，替换请求中的令牌测试，排除原令牌本身签名错误问题

• 第二步 确认JWT提取逻辑正确 #

  在对应location块中临时添加调试配置：

  add_header X-Debug-JWT $cookie_auth always;
  

  发起请求后查看响应头中的X-Debug-JWT值，确认和你实际携带的JWT内容完全一致：
  • 检查Cookie名是否匹配，nginx的$cookie_变量后需跟随Cookie名的全小写形式，若实际Cookie名为Auth、Authorization等，需对应调整变量名
  • 确认JWT没有被nginx自动转义特殊字符，或被其他配置截断

• 第三步 校验密钥配置规则 #

  检查auth_jwt_key配置是否符合模块要求：
  • 若使用明文密钥，直接填写字符串即可，无需额外前缀；若使用十六进制格式密钥，需在字符串前添加hex:前缀，示例：auth_jwt_key hex:48454C4C4F5F574F524C44;（对应HELLO_WORLD的十六进制）
  • 确认密钥配置没有多余的转义字符、前后空格，若密钥包含特殊字符需按nginx配置规则正确转义
  • 可先替换为简单纯字母数字密钥生成测试令牌验证，排除密钥字符兼容性问题

• 第四步 排查其他配置冲突 #

  • 临时注释location块中的rewrite规则测试，排除重写逻辑导致的变量异常
  • 将nginx错误日志级别调整为debug，查看更详细的报错信息，确认解析失败的具体触发点
  • 确认模块编译版本与当前nginx版本兼容，编译时依赖的相关库安装完整无缺失

内容的提问来源于stack exchange，提问作者Alexus