Go multipart boundary 缺失时怎么定位表单解析失败

Go 里遇到 multipart boundary 缺失，通常不是文件字段名写错，而是请求头里的 Content-Type 只有 multipart/form-data，没有继续携带分隔符参数。服务端无法知道请求体中每个表单块从哪里开始、在哪里结束，于是解析会在进入字段读取前失败。

先记录并解析请求的 Content-Type，确认媒体类型是 multipart/form-data 且参数中存在非空 boundary；客户端使用 multipart.Writer.FormDataContentType() 设置请求头，不要手动覆盖成裸的 multipart/form-data。

先确认错误发生在请求边界，而不是表单字段

这类故障常见的表象是“上传接口返回 400”“表单值为空”或 ParseMultipartForm 返回类似缺少 boundary 的错误。判断顺序要反过来：先看请求头，再看解析入口，最后才检查字段名。

不要只打印完整请求体来排查。multipart 内容可能包含隐私文件，完整 body 既难读，也会把敏感数据带进日志。只保留方法、路径、媒体类型、是否存在 boundary 和解析错误，就足够判断第一层问题。

沿着 Content-Type 到 multipart.Reader 找根因

Go 的 mime.ParseMediaType 会把 Content-Type 拆成媒体类型和参数；mime/multipart.NewReader 再使用参数中的 boundary 读取各个 part。也就是说，boundary 不在 JSON 字段里，也不是由服务端从文件名猜出来的。

例如下面的请求头是完整的：

Content-Type: multipart/form-data; boundary=----upload-9f2a

而下面这个请求头虽然看起来像 multipart，却没有告诉解析器分隔符是什么：

Content-Type: multipart/form-data

最容易造成差异的代码是：客户端先用 multipart.Writer 写完 body，又手动执行 req.Header.Set("Content-Type", "multipart/form-data")。这一步会覆盖 writer 根据实际 boundary 生成的值，导致头和体不再匹配。

修复客户端发送和服务端诊断代码

客户端应让 writer 提供最终的媒体类型；调用 Close 把结束边界写入 body 后，再创建请求并设置同一个值：

var body bytes.Buffer
writer := multipart.NewWriter(&body)

// 用真实文件内容创建文件 part，字段名要与服务端约定一致。
part, err := writer.CreateFormFile("file", "report.csv")
if err != nil {
    return err
}
if _, err = io.Copy(part, file); err != nil {
    return err
}
// Close 会写入最后的 boundary，不能省略。
if err = writer.Close(); err != nil {
    return err
}

req, err := http.NewRequest(http.MethodPost, uploadURL, &body)
if err != nil {
    return err
}
// 这个值包含 boundary，不能改成裸的 multipart/form-data。
req.Header.Set("Content-Type", writer.FormDataContentType())

服务端则把错误定位在请求头层，不要把缺少 boundary 当成“没有上传文件”。显式解析参数后再进入表单解析，日志可以保留媒体类型和参数是否存在：

mediaType, params, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
if err != nil || mediaType != "multipart/form-data" || params["boundary"] == "" {
    // 只记录结构性信息，避免把文件内容写入日志。
    http.Error(w, "invalid multipart content type", http.StatusBadRequest)
    return
}

if err := r.ParseMultipartForm(8 

用日志和测试防止边界回归

修复后建议补三类测试。第一类发送 writer 原生的 FormDataContentType，确认文件字段能被解析；第二类故意删除 boundary，确认服务端返回 400 而不是继续读取空字段；第三类验证解析大文件后临时文件会在请求结束时清理。

线上日志可以采用这样的最小字段：请求方法、路由、Content-Type 的媒体类型、boundary 是否存在、文件 part 数量和解析错误类型。不要记录 boundary 对应的完整请求体，也不要把上传文件名、用户身份和文件内容混在公开错误信息里。

如果只有代理转发后的请求失败，还要检查代理是否重写了 Content-Type，或是否把 body 与 header 分开缓存。原则是让产生 multipart body 的组件同时负责生成对应的 header，传输链路只转发，不自行拼接。

相关问题

boundary 可以自己随便写吗？

可以显式设置，但必须保证请求头参数、body 中的分隔线和结束边界完全一致。一般让 multipart.Writer 自动生成更稳妥。

为什么字段名正确仍然取不到文件？

字段名只有在 multipart body 成功解析后才有意义。先确认媒体类型和 boundary，再检查 r.MultipartForm.File 中的键名。

参考：Go mime/multipart 文档、Request.ParseMultipartForm 文档、mime.ParseMediaType 文档。