本文介绍如何在 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 <p>⚠️ <strong>重要注意事项</strong>： </p>
- 不要在 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，真正实现内存可控、磁盘无感、云原生友好的上传架构。
