Go net/http.Server.MaxHeaderBytes 怎样限制请求头大小

如果 Go HTTP 服务遇到带着大量 Cookie、鉴权信息或代理追加字段的请求，最容易混淆的地方是：请求头大小、请求体大小和读取速度其实是三条不同的边界。http.Server.MaxHeaderBytes 只负责服务器解析请求行与请求头键值时允许读取的字节数，不负责限制上传文件或 JSON 请求体。

官方资料：https://pkg.go.dev/net/http#Server

最小配置是给 MaxHeaderBytes 设置一个合适的正整数；保持为零时会使用 Go 的默认请求头上限（当前源码中的 1 ，即 1 MB）。如果还要限制上传内容，要在 Handler 中另用 http.MaxBytesReader。

先把三种“大小不够”分开

一次 HTTP 请求可以先看成三块：请求行、请求头键值、请求体。MaxHeaderBytes 覆盖前两块，包含请求行；请求体要等请求头解析完成后，交给 Handler 读取。它们的责任可以这样对照：

在 http.Server 中显式设置请求头上限

当服务的 Cookie、签名头或网关追加字段有明确上限时，可以在创建 http.Server 时直接配置。下面的 64 KiB 只是示例值，实际数字应根据业务请求样本和代理链共同决定。

package main

import (
	"fmt"
	"log"
	"net/http"
	"time"
)

func main() {
	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 头部解析成功后，业务处理才会进入这里。
		fmt.Fprintln(w, "request accepted")
	})

	server := &http.Server{
		Addr:              ":8080",
		Handler:           handler,
		MaxHeaderBytes:    64 

这里的关键点不是把数字写得越小越好，而是明确配置意图：MaxHeaderBytes 是容量边界，ReadHeaderTimeout 是时间边界。两者可以一起使用，但不能互相替代。

零值不是“关闭限制”

Server.MaxHeaderBytes 为零时，Go 会回退到 DefaultMaxHeaderBytes。官方文档把这个默认值定义为请求头允许的最大尺寸，当前标准库源码中的数值是 1 ，也就是 1 MB。

因此，下面两种写法表达的意图不同：

• 不填写字段或设置为零：接受标准库默认值。
• 设置为正整数：为这个 Server 明确指定自己的上限。

源码的选择逻辑是“只有大于零才使用自定义值，否则使用默认值”。工程代码里不要用负数表达“无限制”；如果确实需要更大的请求头，应该显式写出经过评估的正整数，并同步检查前置代理的限制。

请求体要用 MaxBytesReader 单独限制

很多“请求太大”的问题其实发生在上传体，而不是请求头。此时应在 Handler 中包装 r.Body。这个限制只有在业务读取请求体时才发挥作用，和 Server 在进入 Handler 前解析请求头的边界不同。

import "io"

func uploadHandler(w http.ResponseWriter, r *http.Request) {
	const maxBody = 10 

如果只调小 MaxHeaderBytes，并不能阻止一个已经通过请求头解析的大 JSON 或大文件继续进入 Handler；反过来，只设置 MaxBytesReader 也不会改变请求头解析阶段的容量。

怎样为真实服务选一个可解释的值

不要从“常见值”倒推业务，而要从实际请求的组成开始估算。可以先记录几类合法请求的请求行长度、Cookie、Authorization、签名字段和代理追加头，再留出变化空间，最后把结果写进配置说明。

1. 列出最大合法 Cookie、鉴权头和自定义业务头，确认它们是否会叠加。
2. 把反向代理、网关或服务网格新增的头字段也算入预算。
3. 为密钥轮换、灰度标记和未来字段预留余量，但不要用无限放大来掩盖异常请求。
4. 把请求头容量、读取超时和请求体容量写成三个独立配置项，排障时分别观察。

如果调小后出现客户端请求被拒绝，先确认超出的究竟是 Cookie、Authorization 还是代理追加字段；如果问题是上传文件变大，排查方向应转到 Request.Body 和 MaxBytesReader，不要继续修改 MaxHeaderBytes。

常见误区

• 把它当成请求总大小限制：它不限制请求体，不能代替上传大小控制。
• 把零值理解成无限大：零值会回退到标准库默认上限。
• 只设置容量不设置读取时间：慢速发送请求头仍可能长期占用连接，时间边界要单独考虑。
• 用服务端数字覆盖代理数字：请求可能先在前置代理处被拒绝，排查时要沿请求链逐层确认。

结论与排查清单

要限制 Go HTTP 请求头大小，直接设置 http.Server.MaxHeaderBytes 正整数；不设置时使用默认 1 MB。它管的是请求行和请求头键值，不管请求体。慢速读取用 ReadHeaderTimeout，上传体积用 Handler 中的 http.MaxBytesReader，三者各自承担一个边界。

遇到“请求太大”时，可以按下面顺序判断：先看是否在进入 Handler 前失败，再区分请求头还是请求体；确认 Server 与前置代理的限制；最后检查客户端是否因为 Cookie 或鉴权头累积超过了业务预算。

相关问题

MaxHeaderBytes 会限制单个 Header 的长度吗？

它控制服务器解析请求头时读取的整体字节预算，官方字段说明包含请求行和请求头键值。若要讨论单个字段或字段数量，还要结合具体协议解析和 MaxHeaderValueCount 等配置理解，不能把整体预算当成单字段规则。

MaxHeaderBytes 能限制上传文件吗？

不能。上传文件属于请求体，应在 Handler 中用 http.MaxBytesReader 包装 Request.Body，并在读取错误时返回合适的业务响应。

应该优先调大还是调小？

先以合法请求样本估算，再给变化留出余量。调小可以收紧边界，但必须同步确认 Cookie、鉴权方案和代理链不会把正常请求推过上限；调大也不等于解决慢速读取或大请求体问题。