client_header_buffer_size 是 nginx 单个请求头初始缓冲区大小，设太小会因请求头超长触发 400 错误；需结合 large_client_header_buffers 协同配置，常见合理值为 2k～4k，并通过构造长 header 请求验证生效。
client_header_buffer_size 是 Nginx 用来分配单个请求头初始缓冲区大小的指令，设得太小会导致请求头无法完整读入，从而触发 400 Bad Request 错误——尤其当客户端发送长 Cookie、自定义 Header 或带大量参数的 Referer 时。
什么情况下会触发请求头解析失败
当请求头总长度超过 client_header_buffer_size 设定值，Nginx 会尝试切换到更大的 large_client_header_buffers 缓冲区；若仍不够或配置不当，就直接拒绝请求。常见诱因包括：
- 前端 SDK 自动注入超长追踪 ID 或调试信息到 Header
- 用户登录态使用 Base64 编码的长 JWT 放在 Authorization 字段
- 反向代理链路中多层网关叠加添加 Header（如 X-Forwarded-*、X-Request-ID）
- 浏览器插件或测试工具（如 Postman、curl -H）手动拼接大量自定义 Header
合理设置 client_header_buffer_size 的参考值
默认值是 1k（1024 字节），对多数常规请求足够，但稍复杂场景就容易踩坑。建议按实际业务 Header 规模调整：
- 纯静态站点或简单 API：保持默认 1k 即可
- 含身份认证、多级代理、埋点字段的 Web 应用：设为 2k～4k（如 client_header_buffer_size 2k;）
- 移动端混合 App 或 SDK 集成较多的后端：建议 4k，并同步调大 large_client_header_buffers（例如 large_client_header_buffers 4 8k;）
配合 large_client_header_buffers 才算完整防护
client_header_buffer_size 只是“第一道缓冲”，真正兜底靠的是 large_client_header_buffers。它定义了后续可分配的缓冲区数量和大小。两者需协同配置：
- 若只调大 client_header_buffer_size 但未改 large_client_header_buffers，超长请求头仍可能失败
- 典型安全组合：client_header_buffer_size 2k; + large_client_header_buffers 4 8k;（最多用 4 个 8k 缓冲区）
- 注意：large_client_header_buffers 的总容量不能超过系统单次 read() 调用限制，一般不建议单 buffer 超过 16k
如何验证是否生效
修改后 reload Nginx，再用构造的长 Header 请求测试（例如用 curl 发送含 2KB Cookie 的请求），观察响应状态码和 error.log：
- 出现 "400 Bad Request" 且日志含 "client sent too large request" 或 "too large request header"，说明缓冲区仍不足
- 成功返回 200 或预期状态，且 access.log 中有该请求记录，基本表明配置已起效
- 可在配置中临时加 error_log /path/to/error.log debug; 查看更细粒度的 header 解析过程（生产环境慎用）
