Go mime/multipart.Reader 不生效怎么办

Go 的 mime/multipart.Reader “不生效”时，最常见的原因不是 Reader 没有工作，而是创建它时传入了错误的 boundary，请求体已经被前面的中间件读过，或者把一次性的流同时交给了 NextPart 和 ReadForm。排查顺序可以固定为：先解析 Content-Type，再确认 Body 仍未消费，最后只选一种读取模式。

先把“Reader 不生效”拆成四种现象

同一句“读不到 multipart”，可能对应完全不同的输入问题。NewReader 创建成功，并不代表后续一定能得到 Part；它只保存了底层流和边界，真正解析发生在调用 NextPart 或 ReadForm 时。

因此，排障时不要先给 Reader 加更多循环或重试。先记录经过解析的媒体类型和边界长度，再检查流的所有权，通常很快就能缩小范围。

boundary 必须从 Content-Type 参数中取出

HTTP 请求的头通常类似 multipart/form-data; boundary=----GoBoundaryABC。传给 multipart.NewReader 的第二个参数只能是 ----GoBoundaryABC 这一段值，不能把整个头字符串传进去，也不能手工加上每个分隔行使用的 --。

package main

import (
    "fmt"
    "mime"
    "mime/multipart"
    "net/http"
)

func newMultipartReader(r *http.Request) (*multipart.Reader, error) {
    // ParseMediaType 会同时返回媒体类型和 boundary 参数，避免手工切字符串。
    mediaType, params, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
    if err != nil {
        return nil, fmt.Errorf("解析 Content-Type 失败: %w", err)
    }
    if mediaType != "multipart/form-data" {
        return nil, fmt.Errorf("不支持的媒体类型: %s", mediaType)
    }

    boundary := params["boundary"]
    if boundary == "" {
        return nil, fmt.Errorf("Content-Type 缺少 boundary")
    }
    // 第二个参数是边界值本身，不包含头部前缀和分隔线的两个短横线。
    return multipart.NewReader(r.Body, boundary), nil
}

如果这里返回“缺少 boundary”，先修客户端或代理层设置，不要尝试猜一个边界。边界是发送方写入每个分隔行时使用的值，服务端猜错后当然找不到任何 Part。

用 NextPart 读取时要消费完整的流

NextPart 适合边读边处理的场景：文件很大、不想把整张表单一次装入内存，或者需要根据部件头决定处理方式。每次成功调用返回一个 Part，读完所有部件后返回 io.EOF。

func dumpParts(r *multipart.Reader) error {
    for {
        part, err := r.NextPart()
        if err == io.EOF {
            // EOF 表示 multipart 的结束，不是一个异常上传。
            return nil
        }
        if err != nil {
            return fmt.Errorf("读取下一个部件失败: %w", err)
        }

        // FormName 和 FileName 来自部件头；两者都为空时不要把它当成普通字段。
        name := part.FormName()
        fileName := part.FileName()
        body, err := io.ReadAll(io.LimitReader(part, 8

上面的示例用 io.LimitReader 给单个部件设置了处理上限。它是示例层面的结果保护，不等于服务端已经拒绝了超大输入；生产代码还应根据读取到的字节数判断是否触及上限，并结合请求级大小限制。

另一个容易忽略的点是读取责任。若前置中间件已经调用过 io.ReadAll(r.Body) 而没有把内容恢复给后续处理器，Reader 看到的就是剩余流，自然可能直接得到 io.EOF。同一个 Body 应明确由一个组件负责消费；确实需要多次读取时，必须由上游保存并重建一个新的 Reader。

ReadForm 和 NextPart 只能选一种主路径

ReadForm(maxMemory) 面向完整的 multipart/form-data 表单：它会把字段和文件组织成 Form，超过内存预算的文件可能落到临时文件。它不是 NextPart 的“第二次读取接口”，调用前应保证 Reader 仍在流的起点。

func readForm(r *multipart.Reader) (string, error) {
    // maxMemory 只描述内存预算；不要把它当作整个请求体的大小上限。
    form, err := r.ReadForm(2 

如果业务需要流式保存文件，就走 NextPart；如果业务需要同时拿到多个字段和文件元数据，并且表单规模可控，就走 ReadForm。不要先调用一次 NextPart 检查字段，再调用 ReadForm 期待它从头开始。

四步检查请求为什么读不到

1. 看媒体类型：确认头部是 multipart 类型，并且参数中存在非空 boundary。
2. 看流位置：检查日志、中间件和鉴权代码是否已经读取过 r.Body；不要把空流误判成 Reader 失效。
3. 看读取模式：流式处理选择 NextPart，整体表单选择 ReadForm，不要混用。
4. 看客户端收尾：如果客户端自己拼接 multipart，请确认每个部件头后有空行，并写入最终边界；更稳妥的方式是使用 multipart.Writer 生成请求体和对应的 Content-Type。

最终判断标准不是“有没有拿到一个非空 Reader”，而是：边界能够定位，Body 仍有数据，部件头能读出字段名或文件名，读取循环能以 io.EOF 正常结束。把这四个结果分别记录下来，比盲目重试更有价值。

常见问题

为什么把整个 Content-Type 传给 NewReader 后读不到部件？

因为 NewReader 需要的是 boundary 参数值。先用 mime.ParseMediaType 取出 params["boundary"]，不要把 multipart/form-data; 等头部内容一起传入。

NextPart 返回 io.EOF 是不是上传失败？

不一定。第一次调用就 EOF 通常表示请求体为空、Body 已被消费或边界不匹配；循环中在已有部件之后返回 EOF，则是正常的 multipart 结束信号。

ReadForm 为什么拿不到自定义 multipart/mixed 的内容？

ReadForm 面向带 form-data 处置方式的表单。自定义 multipart 类型应使用 NextPart，按每个部件的头部和正文自行处理。