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

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 或分块处理的大文件。

立即学习“go语言免费学习笔记（深入）”；

例如，前端用 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-x1fx7f\/:*?"|]）
• 生成唯一文件名（如 uuid.New().String() + ".png"），从源头规避冲突与注入
• 保存前用 filepath.EvalSymlinks() 检查目标路径是否仍在 uploadDir 下（防御符号链接逃逸）

示例安全命名逻辑：

func safeFilename(orig string) string {     base := filepath.Base(orig)     base = regexp.MustCompile(`[x00-x1fx7f\/:*?"<>|]+`).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），需同步调整

真正难处理的是中断重传、断点续传、进度反馈——这些 Go 标准库不提供，得靠前端分片 + 后端合并，或者换用专用上传服务（如 tusd）。