Go语言AWS S3包中Upload()与PutObject()的区别及适用场景

核心差异 #

两者最本质的区别在于是否自动处理分块上传：

• PutObject()是S3原生API的直接调用，仅支持单次HTTP请求上传对象。
• Upload()是AWS SDK Go提供的高层封装（基于s3manager.Uploader实例），会根据文件大小自动选择单次上传或分块上传。

详细特性对比 #

PutObject()

• 上传限制：单次请求最大支持5GB（S3的单请求上传上限），超过此大小会直接报错。
• 代码特点：逻辑简单，无需额外配置上传器，直接通过S3客户端调用即可。
• 示例代码：

import (
    "context"
    "os"
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func putObjectExample(s3Client *s3.Client) error {
    file, err := os.Open("small-document.pdf")
    if err != nil {
        return err
    }
    defer file.Close()

    input := &s3.PutObjectInput{
        Bucket: aws.String("your-bucket-name"),
        Key:    aws.String("small-document.pdf"),
        Body:   file,
    }
    _, err = s3Client.PutObject(context.TODO(), input)
    return err
}

Upload()（s3manager.Uploader）

• 自动分块：当文件大小超过上传器的PartSize（默认5MB）时，自动拆分文件为多个分块并行上传，完成后合并为单个S3对象；小文件则自动降级为单次上传。
• 额外能力：支持断点续传（默认开启）、并行上传（可通过Concurrency参数调整并发数），大幅提升大文件上传效率。
• 示例代码：

import (
    "context"
    "os"
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/feature/s3/manager"
)

func uploadExample(s3Client *s3.Client) error {
    file, err := os.Open("large-archive.zip")
    if err != nil {
        return err
    }
    defer file.Close()

    uploader := manager.NewUploader(s3Client)
    // 可自定义配置，比如调整分块大小、并发数
    // uploader = manager.NewUploader(s3Client, func(u *manager.Uploader) {
    //     u.PartSize = 10 * 1024 * 1024 // 10MB分块
    //     u.Concurrency = 5
    // })
    input := &manager.UploadInput{
        Bucket: aws.String("your-bucket-name"),
        Key:    aws.String("large-archive.zip"),
        Body:   file,
    }
    _, err = uploader.Upload(context.TODO(), input)
    return err
}

适用场景选择 #

• 优先用PutObject()：
  • 明确上传的文件小于5GB，且不需要分块上传的额外特性
  • 追求代码极简，不想引入s3manager的额外依赖
  • 上传流程简单，无需断点续传、并行上传等能力
• 优先用Upload()：
  • 上传大文件（比如几十GB、几百GB的视频、压缩包等）
  • 不确定文件大小，希望SDK自动适配最优上传方式
  • 需要提升上传速度，利用并行分块减少耗时
  • 需要断点续传能力，避免上传中断后重新从头开始

内容的提问来源于stack exchange，提问作者Jackk-Doe