Go multipart 为什么上传文件读到空内容

Go 接收 multipart 上传时，文件“读到空内容”通常不是 multipart 把字节丢了，而是读取链路中的某个边界没有对齐：客户端字段名和服务端不一致、Content-Type 被手动改坏、请求体已经被中间件读到末尾，或者同一个文件流第一次读取后又被当成新流使用。

最小修复是让一个处理函数负责从 r.FormFile("file") 获取文件、检查错误、关闭文件并完成读取；如果要处理大文件，再改用 r.MultipartReader() 流式遍历 Part。不要把空字节直接解释成“上传成功但文件损坏”，先确认输入字段和读取游标。

本文依据 Go 官方 net/http 与 mime/multipart 文档说明接口语义，示例代码用于解释结构和排查方法。

先固定上传字段和 multipart 边界

multipart 请求至少有两个容易错位的名称：表单字段名和文件名。客户端如果提交的是 upload，服务端却调用 FormFile("file")，得到的通常是“没有这个表单文件”一类错误，而不是可读取的空文件。文件名 header.Filename 只描述上传文件的名称，不能替代字段名。

另一个关键是 Content-Type 中的 boundary。使用 Go 的 multipart.Writer 或浏览器 FormData 发送时，应让发送方自动生成完整的 Content-Type；手动把它覆盖成只有 multipart/form-data，会使服务端无法找到每个 Part 的分隔线。

// 客户端字段名必须与服务端 FormFile 的 key 一致。
form.append("file", input.files[0])

// 服务端只从同名字段取文件；Filename 不是字段 key。
file, header, err := r.FormFile("file")
if err != nil {
    http.Error(w, "上传字段 file 不可用", http.StatusBadRequest)
    return
}
defer file.Close() // 读取完成后释放临时文件或内存资源。
_ = header.Filename

如果错误值是 http: request body too large、multipart: NextPart: EOF 或 request Content-Type isn't multipart/form-data，先记录它，不要用空切片吞掉错误。错误本身决定了应该检查大小限制、请求边界还是字段类型。

用 FormFile 获取独立文件流

FormFile 会在需要时调用 ParseMultipartForm 和 ParseForm，返回文件流、文件头和错误。真正需要读取文件字节时，应在同一个责任点处理错误和关闭资源，并把读取错误与“读到了零字节”区分开。

func upload(w http.ResponseWriter, r *http.Request) {
    file, header, err := r.FormFile("file")
    if err != nil {
        // 不把字段缺失、边界错误和大小限制伪装成空文件。
        http.Error(w, "multipart 文件字段不可用", http.StatusBadRequest)
        return
    }
    defer file.Close() // FileHeader.Open 返回的资源也必须关闭。

    var dst bytes.Buffer
    n, err := io.Copy(&dst, file)
    if err != nil {
        // 读取中断时保留真实错误，方便区分 EOF 与传输失败。
        http.Error(w, "读取上传文件失败", http.StatusBadRequest)
        return
    }
    if n == 0 {
        // 空文件是合法输入；是否允许由业务规则决定。
        http.Error(w, "上传文件为空", http.StatusBadRequest)
        return
    }
    fmt.Fprintf(w, "%s %d bytes", header.Filename, n)
}

这里的 n == 0 只表示这一次读取没有得到字节，不能替代错误检查。上传一个合法的零字节文件时，n 本来就可能为零；如果业务禁止空文件，应显式返回业务错误，而不是继续解析内容。

如果代码先调用了 io.ReadAll(file)，再把同一个 file 交给另一个函数读取，后者看到的就是 EOF。需要重复读取时，保存读取后的字节并创建新的 Reader，或者通过 Seek(0, io.SeekStart) 回到开头，但不要假定所有 Reader 都支持定位。

避免 EOF、重复解析和请求体抢读

ParseMultipartForm 的职责是解析整个 multipart 请求，并把文件的一部分放入内存，超过 maxMemory 的部分写入临时文件；一次解析成功后，后续调用不会重新读取出一份新的表单。不要在日志中先把 r.Body 全部读完，再期待 FormFile 还能看到原始请求。

实践中最容易忽视的是中间件顺序：签名校验、日志记录或请求体缓存层如果消费了 Body 却没有把等价的新 Reader 放回去，业务 handler 看到的只能是 EOF。修复方式不是在 handler 中多调用一次 ParseMultipartForm，而是明确一个组件拥有请求体读取权。

调试时只记录低风险元数据：r.Header.Get("Content-Type")、header.Filename、字段名、错误值和读取次数；不要把完整上传内容或可能包含隐私的数据写入日志。文件上传链路的保护目标是字节完整性，同时也要避免调试信息泄露原始文件。

大文件改用 MultipartReader

当文件不适合先整体解析，或你希望边读边写入存储，可以使用 MultipartReader 逐个取得 Part。它要求请求是 multipart/form-data 或 multipart/mixed；如果缺少 boundary，返回的错误比“文件为空”更能说明输入不完整。

func streamUpload(w http.ResponseWriter, r *http.Request) {
    reader, err := r.MultipartReader()
    if err != nil {
        // Content-Type 或 boundary 不正确时，在入口处返回原因。
        http.Error(w, "不是有效的 multipart 请求", http.StatusBadRequest)
        return
    }

    for {
        part, err := reader.NextPart()
        if errors.Is(err, io.EOF) {
            // 没有更多 Part，正常结束遍历。
            break
        }
        if err != nil {
            http.Error(w, "读取 multipart 分段失败", http.StatusBadRequest)
            return
        }
        if part.FormName() != "file" {
            part.Close() // 非目标字段不交给文件存储层。
            continue
        }

        _, err = io.Copy(dst, part) // 生产代码应给 dst 配置大小上限。
        part.Close()                // 当前 Part 用完后释放资源。
        if err != nil {
            http.Error(w, "写入上传文件失败", http.StatusBadRequest)
            return
        }
    }
    w.WriteHeader(http.StatusCreated)
}

流式写入时仍要检查字段名、文件名、大小上限和存储错误；“使用流式 API”并不会自动替你完成鉴权、限流或文件类型策略。若只是普通的小文件表单，FormFile 更易读；只有在内存、大小或处理方式确实需要时再切换。

发布前可按这份清单定位

• 客户端字段名是否真的叫 file，服务端是否对同一个 key 调用 FormFile。
• Content-Type 是否保留了自动生成的 boundary，没有被手动覆盖。
• 是否检查并保留了 FormFile、MultipartReader 和 io.Copy 返回的错误。
• 同一个 multipart.File 是否被前一个日志、哈希或解析函数读到了 EOF。
• 是否存在中间件提前消费 r.Body，并且没有把读取责任重新交给业务层。
• 大文件是否使用了明确的大小限制、临时文件策略或流式 Part 处理。

相关接口可查阅 https://pkg.go.dev/net/http 与 https://pkg.go.dev/mime/multipart。把“空内容”拆成字段、边界、读取游标和所有权四类证据，通常比继续增加解析调用更快找到根因。

两个容易混淆的问题

调用 ParseMultipartForm 后还能调用 FormFile 吗？ 可以，FormFile 会复用已经解析出的表单；但重复调用不会让已读到 EOF 的文件流自动回到开头。

文件大小超过 maxMemory 就会读空吗？ 不会。超过内存预算的文件部分可以转入临时文件；读空应优先检查错误、请求体是否被提前消费以及字段和边界是否匹配。