Golang多文件上传实现与实战教程

Go 的 http.FileServer 不支持多文件上传，必须用 multipart/form-data 表单提交并调用 ParseMultipartForm 解析；需设置 MaxMemory，用 form.File["files"] 获取同名文件切片，再通过 Open() 和 io.Copy() 保存，注意关闭文件句柄。

Go 的 http.FileServer 不能直接处理多文件上传

很多开发者一上来就想用 http.FileServer 或静态路由转发实现上传，但这是行不通的——它只服务已存在的文件，不接收 POST 数据。多文件上传必须走标准的 multipart/form-data 表单提交，由 Go 的 request.ParseMultipartForm() 解析。

关键点在于：ParseMultipartForm 会把文件先暂存到内存或磁盘（取决于大小），你得主动调用 form.File 拿到每个 *multipart.FileHeader，再用 Open() 和 io.Copy() 写出。

• 必须在 ParseMultipartForm 前设置 MaxMemory（默认 32MB），否则大文件会直接报错 http: request body too large
• form.File 返回的是文件头信息，不是内容；要读内容必须调用 fileHeader.Open() 得到一个 multipart.File（本质是 io.ReadCloser）
• 别忘了关闭 multipart.File 和目标文件句柄，否则可能泄漏 fd

如何安全地接收并保存多个同名字段的文件（name="files"）

前端用 <input type="file" name="files" multiple> 提交时，后端收到的是多个同名 key 的文件项，不能用 form.File("files") —— 它只返回第一个。必须用 form.File["files"] 拿到切片。

示例代码片段：

err := r.ParseMultipartForm(32 << 20) // 32MB
if err != nil {
    http.Error(w, "parse form err: "+err.Error(), http.StatusBadRequest)
    return
}
files := r.MultipartForm.File["files"]
for _, fileHeader := range files {
    src, err := fileHeader.Open()
    if err != nil {
        http.Error(w, "open file err", http.StatusInternalServerError)
        return
    }
    defer src.Close() // 注意：这里不能用 defer 在循环里，应改用显式 close 或移出循环

    dst, err := os.Create("./uploads/" + fileHeader.Filename)
    if err != nil {
        http.Error(w, "create file err", http.StatusInternalServerError)
        return
    }
    if _, err := io.Copy(dst, src); err != nil {
        dst.Close()
        http.Error(w, "save file err", http.StatusInternalServerError)
        return
    }
    dst.Close()
}

• 文件名直接拼接路径有风险，生产环境务必校验 fileHeader.Filename（过滤 ../、空字节、控制字符）
• 多个 defer src.Close() 在循环中会堆积，最后只执行最后一次，所以应显式 src.Close()
• 建议用 filepath.Clean() 和白名单扩展名做基础防护

上传过程中如何防止阻塞和超时

默认 HTTP server 没有读取 body 超时控制，恶意客户端可以发超长 header 或慢速上传拖垮服务。必须显式设置 http.Server.ReadTimeout 和 ReadHeaderTimeout。

• ReadTimeout 控制整个请求（含 body）的最大读取时间，设为 60–120 秒较合理
• ReadHeaderTimeout 控制 header 解析超时，建议 ≤5 秒，避免慢 header 攻击
• 如果需要更细粒度控制（比如限制单个文件大小），应在解析后检查 fileHeader.Size，超过阈值立即拒绝
• 不要依赖 context.WithTimeout 包裹 handler——HTTP/1.1 的 body 读取不在 context 控制范围内

为什么不用第三方库（如 gofrs/flock 或 minio）？

纯多文件上传服务，核心逻辑就是解析 multipart + 写磁盘，Go 标准库完全够用。gofrs/flock 是文件锁，上传场景一般不需要并发写同一文件；minio 是对象存储 SDK，适合海量文件或分布式场景，本地小规模服务反而增加部署复杂度和延迟。

真正该加的其实是：文件去重（基于 SHA256）、异步保存（避免阻塞 HTTP worker）、上传进度回调（需搭配前端 XMLHttpRequest.upload.onprogress），但这些都属于业务延伸，不是“实现上传”本身的前提。

最常被忽略的是临时目录清理——ParseMultipartForm 在 MaxMemory 不足时会把文件暂存到系统临时目录，Go 不会自动清理。若长期运行且上传频繁，得定期扫 os.TempDir() 下的 multipart-* 文件。