Go mime/multipart 出错时怎么排查边界参数

我排查 Go 文件上传接口时，最容易被误判成“文件内容坏了”的问题，往往只是 Content-Type 里的 boundary 和请求体分隔线没有对上。mime/multipart 不会替你猜分隔符：解析器从头部参数取值，再用它寻找 --boundary 和结束标记。先修这条对应关系，通常比盲目增大上传限制更有效。

先看 Content-Type：boundary 是解析入口

multipart 消息由多段内容组成，头部的 boundary 只是“分隔符名字”，真正出现在正文时要加两个连字符。例如头部声明 boundary=upload-42，正文分隔线应是 --upload-42，末尾则是 --upload-42--。少了参数、头部与正文使用不同值，或者把带引号的参数直接连同引号传给 NewReader，都会让解析停在入口。

把生成端和解析端的 boundary 对齐

我更愿意把生成端和解析端分开看。生成端负责产生边界、写入每个 part 并关闭 Writer；解析端只负责从头部读取边界并消费 body。下面的示例没有手拼分隔线，代码中的注释说明了错误处理和资源边界。

// 发送端：让 Writer 同时生成正文分隔线和 Content-Type 参数。
func newUploadRequest(url, filename string, src io.Reader) (*http.Request, error) {
    var body bytes.Buffer
    writer := multipart.NewWriter(&body)

    // 字段名必须和服务端约定一致，文件名只描述该 part。
    part, err := writer.CreateFormFile("file", filename)
    if err != nil {
        return nil, fmt.Errorf("创建文件字段: %w", err)
    }
    // 流式复制避免为了构造 multipart 额外复制整个文件。
    if _, err = io.Copy(part, src); err != nil {
        return nil, fmt.Errorf("写入文件字段: %w", err)
    }
    // Close 会写入最后的 --boundary--，必须在发送请求前调用。
    if err = writer.Close(); err != nil {
        return nil, fmt.Errorf("关闭 multipart writer: %w", err)
    }

    req, err := http.NewRequest(http.MethodPost, url, &body)
    if err != nil {
        return nil, fmt.Errorf("创建请求: %w", err)
    }
    // 该值同时包含 multipart/form-data 和当前 Writer 的 boundary。
    req.Header.Set("Content-Type", writer.FormDataContentType())
    return req, nil
}

如果请求来自浏览器或其他客户端，服务端不要凭经验截取字符串。应先用 mime.ParseMediaType 解析媒体类型和参数，再把 params["boundary"] 传给 multipart.NewReader。这样能正确处理参数引号、大小写和其他合法参数排列。

// 解析端：只接受 form-data，并把格式错误与资源限制分开返回。
func readUpload(r *http.Request) error {
    mediaType, params, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
    if err != nil {
        return fmt.Errorf("解析 Content-Type: %w", err)
    }
    if mediaType != "multipart/form-data" {
        return fmt.Errorf("不支持的媒体类型: %s", mediaType)
    }
    boundary := params["boundary"]
    if boundary == "" {
        return errors.New("缺少 multipart boundary")
    }

    reader := multipart.NewReader(r.Body, boundary)
    form, err := reader.ReadForm(32 

如果服务端是 net/http 的请求处理器，也可以使用 r.MultipartReader() 让标准库结合请求头创建 Reader；但无论哪种写法，底层仍然依赖同一条 boundary 对应关系。

按错误层次排查，不要先改上传上限

边界问题解决后，仍可能遇到请求体被代理截断、part 头部没有完整结束，或客户端只写了一个开头分隔线。看到 io.ErrUnexpectedEOF 时，先比较实际收到的 body 长度和客户端发送长度；看到下一段读取失败时，检查每个 part 的头部后是否有空行，以及换行是否稳定使用 \r\n。这类错误不是把 maxMemory 调大就能修好的。

ReadForm 另有保护性限制：非文件字段受 maxMemory 影响，文件可能落到临时文件；当前文档还说明了 part 数量和头部数量上限，并允许通过 GODEBUG 调整相关限制。生产接口应在反向代理、HTTP 服务和 multipart 解析三层都设请求大小策略，同时记录字段名、文件大小和解析阶段，避免只留一条笼统的 400 日志。

上线前用一张清单收口

• 发送端是否使用 FormDataContentType()，并在 Close() 后才发送 body？
• 服务端拿到的媒体类型是否确实是 multipart/form-data，boundary 是否非空？
• 正文是否包含匹配的 --boundary、part 头空行和 --boundary-- 结束标记？
• 解析失败时是否能区分边界错误、提前 EOF 和大小/数量限制？
• 临时文件是否在处理结束后清理，字段名和文件名是否经过业务层校验？

常见问题

为什么只设置 multipart/form-data 仍然解析失败？

因为没有 boundary 参数，解析器无法知道正文中哪一行负责分隔 part。手动设置请求头时最容易覆盖客户端自动生成的完整值。

boundary 前面要不要自己加两个连字符？

传给 multipart.NewReader 或 SetBoundary 的是名字本身，不要把 -- 一起传入；两个连字符只出现在消息正文的分隔行。

什么时候应该不用 ReadForm？

如果文件很大、字段数量不稳定，或业务只需要按 part 流式落盘，可以循环调用 NextPart，边读边处理，减少一次性建立完整表单的内存压力。

排查 mime/multipart 时，第一优先级始终是“头部 boundary、正文分隔线、结束标记”三者一致；只有这条链路成立后，大小限制和业务字段才值得继续看。