Go multipart 解析为什么报 boundary 缺失

Go 里看到 http: no multipart boundary param in Content-Type，先别去查文件字段名。这个错误说明服务端收到的请求头只有 multipart/form-data，却没有告诉解析器本次正文使用哪一个 boundary 分隔符。最常见的原因是客户端用 multipart.Writer 组好了正文，又手动把 Content-Type 覆盖成了不完整的值。

boundary 不是正文内容，而是 Content-Type 的参数

multipart 请求由两部分共同组成：请求体里用分隔符切开各个 part，请求头里的 Content-Type 则要通过 boundary 参数把这个分隔符告诉接收方。例如，下面这个头是完整的：

Content-Type: multipart/form-data; boundary=------------------------a1b2c3d4

如果头被写成下面这样，媒体类型虽然看起来对了，但解析器不知道应该寻找哪一条分隔线：

Content-Type: multipart/form-data

Request.MultipartReader 会从这个参数创建 mime/multipart.Reader。参数不存在时返回 http.ErrMissingBoundary，所以错误发生在解析请求结构之前，与文件名、表单字段名和文件后缀都没有直接关系。

先检查客户端是否覆盖了 multipart.Writer 生成的请求头

客户端最稳妥的做法是让 multipart.Writer 同时负责正文和媒体类型。FormDataContentType 会把 writer 当前的 boundary 拼到请求头里；不要再用一个固定字符串覆盖它。

package main

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

func newUploadRequest(url string) (*http.Request, error) {
    var body bytes.Buffer
    writer := multipart.NewWriter(&body)

    // 字段名和文件名只是 part 元数据，不负责生成 boundary。
    if err := writer.WriteField("description", "demo"); err != nil {
        return nil, err
    }
    filePart, err := writer.CreateFormFile("file", "demo.txt")
    if err != nil {
        return nil, err
    }
    if _, err := filePart.Write([]byte("hello multipart")); err != nil {
        return nil, err
    }

    // 关闭 writer 才会把结束 boundary 写入正文。
    if err := writer.Close(); err != nil {
        return nil, err
    }

    req, err := http.NewRequest(http.MethodPost, url, &body)
    if err != nil {
        return nil, err
    }
    // 必须保留 writer 生成的 boundary，不能改成固定的媒体类型字符串。
    req.Header.Set("Content-Type", writer.FormDataContentType())
    fmt.Println("发送类型:", req.Header.Get("Content-Type"))
    return req, nil
}

排障时可以只看这一行输出：如果它以 multipart/form-data; boundary= 开头，客户端至少没有在组包阶段丢掉边界参数。如果你在更外层的 HTTP 封装里又设置了一次 Content-Type，仍然可能在真正发送前把正确值覆盖掉。

writer.Close 也要检查：正文没有结束边界是另一类问题

Content-Type 有 boundary，并不代表正文一定完整。multipart.Writer 在 Close 时写入最后的结束分隔线；如果忘了关闭，服务端通常会在读 part 的过程中报意外结束或读不完整。这和“请求头缺少 boundary 参数”是两个相邻但不同的故障点。

FormFile、ParseMultipartForm 和 MultipartReader 怎么选

修好请求头以后，再根据处理目标选择 API。只拿一个上传文件时可以直接调用 FormFile；需要同时访问普通字段和多个文件时调用 ParseMultipartForm；需要大文件边读边处理时使用 MultipartReader，不要先把整个表单读进内存。

func uploadHandler(w http.ResponseWriter, r *http.Request) {
    // 先限制请求体上限，避免无界读取占用服务端资源。
    r.Body = http.MaxBytesReader(w, r.Body, 10

FormFile 会按需触发 multipart 表单解析。若要一次拿到表单对象，可以显式传入内存预算：

func formHandler(w http.ResponseWriter, r *http.Request) error {
    // maxMemory 只控制文件 part 的内存使用，其余内容仍需按业务限制。
    if err := r.ParseMultipartForm(8 

如果请求体很大，流式分支更合适。它同样要求正确的 Content-Type 和 boundary，只是把每个 part 交给调用方逐段处理：

func streamHandler(w http.ResponseWriter, r *http.Request) error {
    // MultipartReader 根据请求头中的 boundary 创建逐段读取器。
    reader, err := r.MultipartReader()
    if err != nil {
        return fmt.Errorf("create multipart reader: %w", err)
    }
    for {
        part, err := reader.NextPart()
        if errors.Is(err, io.EOF) {
            // 读到结束 boundary，说明所有 part 已处理完成。
            break
        }
        if err != nil {
            return fmt.Errorf("read multipart part: %w", err)
        }
        // 这里按 part.FormName 或 part.FileName 分流，并限制单个 part 的读取量。
        if _, err := io.Copy(io.Discard, io.LimitReader(part, 1

一份可复用的 boundary 排障清单

1. 记录服务端实际收到的 Content-Type，确认不是只剩 multipart/form-data。
2. 检查客户端是否使用同一个 multipart.Writer 生成正文和 FormDataContentType()。
3. 确认 writer.Close() 在发送请求前成功返回。
4. 检查 HTTP 封装、中间件或代理是否在发送前覆盖了请求头。
5. 根据文件大小选择 FormFile、ParseMultipartForm 或 MultipartReader，并设置请求体与 part 限制。
6. 只有在 boundary 正确以后，再检查字段名、文件名和业务校验。

这类错误的定位顺序很固定：先看媒体类型，再看 boundary 参数，接着看正文是否正常封口，最后才进入字段和文件业务。把这几个层次分开，通常不需要改服务端解析代码。

常见问题

能不能手动写一个固定 boundary？

可以，但正文中的分隔线、请求头参数和转义规则必须完全一致。除非你在实现底层协议，否则让 multipart.Writer 统一生成更稳妥。

把 Content-Type 改成 application/json 会解决问题吗？

不会。那会把请求变成另一种媒体类型，服务端应改用 JSON 解码；它不是 multipart boundary 的修复方式。

FormFile 和 MultipartReader 能同时调用吗？

一般不要把它们当成两次独立读取。前者会触发表单解析，后者用于把请求体作为流读取，应该按处理目标选择一条路径。

为什么只在某些客户端上报错？

不同客户端对 multipart 请求头的默认处理不同。有的自动保留 boundary，有的在用户手动设置请求头后会覆盖自动值，所以应以服务端实际收到的头为准。