技术学院

Golang使用multipart处理文件上传流程

作者:P粉6029986702026-01-07 00:00:00

r.ParseMultipartForm 必须在 r.FormFile 之前调用，因为 multipart.Reader 是流式解析，ParseMultipartForm 负责预读并缓存表单字段和文件元信息；FormFile 仅查表，不重新解析 body。

为什么 `r.ParseMultipartForm` 必须在 `r.FormFile` 之前调用

不调用或调用顺序错误会导致 r.FormFile 返回 nil, nil 或 http.ErrMissingFile，而不是你预期的文件句柄。这是因为 Go 的 multipart.Reader 是流式解析，ParseMultipartForm 负责预读并缓存表单字段和文件元信息到内存或临时磁盘；后续的 FormFile 只是查表，不重新解析原始 body。

常见错误写法：

file, _, err := r.FormFile("file") // ❌ 此时 r.MultipartForm 为 nil
if err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}

正确做法：

必须先调用 r.ParseMultipartForm(maxMemory)，其中 maxMemory 是内存缓冲上限（单位字节），超过部分会写入临时磁盘
若只上传小文件（如头像、配置文件），设为 32 （32MB）较安全；若不确定大小，建议设为 10 （10MB），避免 OOM
调用后检查 r.MultipartForm == nil，可提前判断是否真的含 multipart 内容

`FormFile` 和 `MultipartReader` 该选哪个

FormFile 简单直接，适合单文件、字段名固定、无需流式处理的场景；MultipartReader 提供底层控制，适合多文件、动态字段名、需要校验 Content-Type 或分块处理的大文件。

例如，前端用 input type="file" multiple 上传多个同名文件，FormFile 只返回第一个；必须用 MultipartReader 手动遍历：

mr, err := r.MultipartReader()
if err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
for {
    part, err := mr.NextPart()
    if err == io.EOF {
        break
    }
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    if part.FormName() == "file" {
        // 处理每个 part，可读取 part.Header.Get("Content-Type")
        // 注意：part 是 io.Reader，需自行 copy 到目标位置
    }
}

FormFile 自动跳过非文件字段，MultipartReader 需手动过滤 part.FormName()
FormFile 返回的 multipart.File 是 io.ReadCloser，用完必须 Close()，否则临时文件不释放
MultipartReader 不创建临时文件，适合低延迟或高并发上传，但需自己管理边界与编码

如何安全保存上传的文件而不被路径遍历攻击

用户提交的 filename 可能含 ../、空字节或非法字符，直接拼接 path.Join(uploadDir, filename) 会导致任意文件覆盖甚至写入系统目录。

永远不要信任 part.FileName() 或 header.Filename 的原始值
用 filepath.Base() 截取纯文件名，再用正则清除非法字符（如 [\x00-\x1f\x7f\\/:*?"|]）
生成唯一文件名（如 uuid.New().String() + ".png"），从源头规避冲突与注入
保存前用 filepath.EvalSymlinks() 检查目标路径是否仍在 uploadDir 下（防御符号链接逃逸）

示例安全命名逻辑：

func safeFilename(orig string) string {
    base := filepath.Base(orig)
    base = regexp.MustCompile(`[\x00-\x1f\x7f\\/:*?"<>|]+`).ReplaceAllString(base, "_")
    if base == "" || base == "." || base == ".." {
        base = "unnamed"
    }
    return fmt.Sprintf("%s_%s", uuid.New().String(), base)
}

大文件上传时如何避免请求超时和内存溢出

默认 HTTP server 的 ReadTimeout 和 WriteTimeout 往往只有几秒，而百 MB 文件上传可能耗时数十秒；同时 ParseMultipartForm 的 maxMemory 若设得过高，会一次性吃光服务内存。

启动 server 时显式设置超时：&http.Server{ReadTimeout: 5 * time.Minute, WriteTimeout: 5 * time.Minute, ...}
对大文件启用流式处理：跳过 ParseMultipartForm，直接用 MultipartReader + io.Copy 写入磁盘或对象存储，不落地到内存
配合 http.MaxBytesReader 限制总上传体积，防止恶意上传耗尽磁盘：http.MaxBytesReader(w, r, maxUploadSize)
注意：Nginx/Apache 等反向代理也有自己的超时和 body size 限制（如 Nginx 的 client_max_body_size、client_body_timeout），需同步调整