本文介绍如何在 Go 中直接流式上传 multipart/form-data 大文件到 AWS S3，全程避免本地落盘与高内存缓冲，利用 s3manager.Uploader 的分块上传能力实现高效、可配置的直传方案。
本文介绍如何在 go 中直接流式上传 multipart/form-data 大文件到 aws s3，全程避免本地落盘与高内存缓冲，利用 `s3manager.uploader` 的分块上传能力实现高效、可配置的直传方案。
在构建高并发文件上传服务（如视频、日志归档或用户素材提交）时，将大型文件先保存到本地磁盘再上传至 S3 不仅浪费 I/O 资源、增加延迟，还存在磁盘满、权限异常、清理遗漏等运维风险。理想方案是：从 HTTP 请求体中读取 multipart/form-data 流，不经缓冲或落盘，直接通过分块上传（Multipart Upload）推送到 S3。
AWS SDK for Go v1 提供了 s3manager.Uploader，它原生支持流式上传（io.Reader 接口），可自动切片、并发上传、重试失败分块，并透明处理底层 CreateMultipartUpload / UploadPart / CompleteMultipartUpload 协议。关键优势在于：
- ✅ 零临时文件：Body 字段接受任意 io.Reader（如 *multipart.File 或 http.Request.Body 包装流），无需 os.CreateTemp 或 ioutil.TempFile；
- ✅ 可控内存占用：通过 PartSize（默认 5 MiB，最小允许值）限制单次读取缓冲区大小；
- ✅ 可调并发性：Concurrency 控制并行上传分块数，平衡吞吐与连接压力；
- ✅ 自动恢复：网络中断后可续传（需启用 LeavePartsOnError: false 等策略，见注意事项）。
以下是一个生产就绪的流式上传示例（适配 HTTP handler 场景）：
package main
import (
"fmt"
"io"
"mime/multipart"
"net/http"
"github.com/aws/aws-sdk-go/aws"
"github.com/aws/aws-sdk-go/aws/session"
"github.com/aws/aws-sdk-go/service/s3/s3manager"
)
func uploadHandler(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
// 解析 multipart 表单（注意：r.ParseMultipartForm 会缓存小文件到内存，需设合理 MaxMemory）
err := r.ParseMultipartForm(32 << 20) // 32MB 内存阈值，超限则写入临时磁盘 —— 但仅影响表单元数据，不影响文件流
if err != nil {
http.Error(w, "Failed to parse form", http.StatusBadRequest)
return
}
// 获取文件字段（假设前端字段名为 "file"）
file, header, err := r.FormFile("file")
if err != nil {
http.Error(w, "No file uploaded", http.StatusBadRequest)
return
}
defer file.Close()
// 初始化 AWS Session（推荐使用 IAM Role 或 ~/.aws/credentials，避免硬编码密钥）
sess, err := session.NewSession(&aws.Config{
Region: aws.String("us-west-2"), // 替换为你的 bucket 所在区域
})
if err != nil {
http.Error(w, "AWS config error", http.StatusInternalServerError)
return
}
// 创建自定义 Uploader：控制分块大小与并发数
uploader := s3manager.NewUploader(sess, func(u *s3manager.Uploader) {
u.PartSize = 5 * 1024 * 1024 // 每块 5MB（S3 最小要求）
u.Concurrency = 3 // 并发上传 3 个分块
u.LeavePartsOnError = false // 上传失败时自动清理已上传分块（防孤儿碎片）
})
// 执行流式上传（file 是 *multipart.File，满足 io.Reader 接口）
result, err := uploader.Upload(&s3manager.UploadInput{
Bucket: aws.String("my-bucket-name"), // 替换为你的 bucket
Key: aws.String("uploads/" + header.Filename), // 可动态构造路径
Body: file,
// 可选：设置 Content-Type（若未自动识别）
// ContentType: aws.String(header.Header.Get("Content-Type")),
})
if err != nil {
http.Error(w, fmt.Sprintf("S3 upload failed: %v", err), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
fmt.Fprintf(w, `{"location": %q}`, result.Location)
}
func main() {
http.HandleFunc("/upload", uploadHandler)
fmt.Println("Server starting on :8080")
http.ListenAndServe(":8080", nil)
}⚠️ 重要注意事项：
- 不要在 handler 中调用 r.Body 直接读取：multipart/form-data 必须通过 r.FormFile 或 r.MultipartReader() 获取文件流，否则会破坏边界解析；
- PartSize 不可低于 5 MiB：S3 分块上传强制要求，小于该值将触发 SDK panic；
- 避免 defer file.Close() 在上传中途执行：uploader.Upload 内部会完整消费 Body，提前关闭会导致 io.ErrUnexpectedEOF；
- 生产环境务必使用 IAM 角色或 ECS Task Role：禁用 accessKey/accessSecret 硬编码，遵循最小权限原则授予 s3:PutObject 权限；
- 超大文件建议添加进度回调与超时控制：可通过 uploader.UploadWithContext 配合 context.WithTimeout 实现；
- SDK v2 用户注意：github.com/aws/aws-sdk-go-v2/service/s3 中对应组件为 manager.Uploader（位于 github.com/aws/aws-sdk-go-v2/feature/s3/manager），API 略有差异，需迁移时参考官方迁移指南。
综上，借助 s3manager.Uploader 的流式设计，Go 应用可安全、高效地将百 GB 级文件“边收边传”至 S3，真正实现内存可控、磁盘无感、云原生友好的上传架构。
