431错误主因是HTTP/2下请求头超限，需调高nginx的http2_max_header_size（默认16KB），并同步调整http2_max_field_size、max_headers等参数，后端也需匹配限制。
当后端服务（如 FastAPI、Node.js）返回 431 Request Header Fields Too Large，而你确认是因 JWT Token 过长（比如含大量声明、嵌套对象或签名膨胀）导致，问题通常出在 Nginx 对 HTTP/2 请求头总大小的限制上——http2_max_header_size 是关键开关。
确认是否是 http2_max_header_size 触发的 431
该错误只在启用 HTTP/2 的 server 块中生效。先检查配置里是否有：
-
listen 443 ssl http2;（或http2关键字存在） - 未显式设置
http2_max_header_size，则走默认值 16KB（16384 字节） - 用
curl -v --http2 -H "Authorization: Bearer $(python3 -c 'print(\"a\"*20000)')" https://yoursite.com模拟大 header，观察是否返回 431 并在 error.log 中出现 client sent too large header while reading header
合理调高 http2_max_header_size
JWT 实际体积受算法、payload 字段数、签名长度影响。常见 JWT（含用户信息+权限+多级 trace 头）可能达 8–25KB。建议按场景分级设置：
- 纯内部 API 网关、JWT 含完整用户上下文：设为
32k或64k - 对外轻量接口、仅基础鉴权：保持默认
16k即可 - 不建议超过
128k，否则失去防御意义，且可能被用于内存耗尽攻击
配置示例（放在 http 或 server 块内）：
必须同步检查的关联参数
单调大 http2_max_header_size 不够，还需覆盖其他头部限制点：
-
http2_max_field_size：防单个超长 header（如一个 30KB 的Cookie），默认 4k，建议同步设为32k -
max_headers（Nginx 1.29.8+）：防“大量小 header”攻击（如 2000 个X-Trace-Id-*），默认 1000 行，可设为500～800更稳妥 - 后端自身限制也要匹配：如 Node.js 需加启动参数
--max-http-header-size=32768；FastAPI/Uvicorn 无直接等效项，但应确保其反向代理前的 Nginx 已拦截，避免透传异常 header
验证配置是否真正生效
改完配置后执行：
nginx -t && nginx -s reload- 查看
error.log是否还有相关报错 - 用真实带长 JWT 的请求测试（不要只测人工拼接字符串，要复现生产 token 结构）
- 注意：HTTP/1.1 请求不受
http2_max_header_size影响，它只作用于启用了http2的连接
