面向中文开发者的 AWS 实战知识库 代维服务
上云咨询

如何将文件上传到 AWS S3 存储桶(切实可行的 CLI 步骤)

导出 PDF 浅色排版、带版权水印,可在打印窗口另存为 PDF
如何将文件上传到 AWS S3 存储桶(切实可行的 CLI 步骤)

太长不看(TL;DR)

  • aws s3 cp ./file.txt s3://my-bucket/ 就是全部命令;90% 的失败源于区域填错、缺少 s3:PutObject,或者 KMS 密钥策略在上传时把你挡住——尽管 IAM 上写的是 "Allow"。
  • 需要可重复的部署就用 aws s3 sync,一次性拷贝整个目录就用 aws s3 cp --recursive —— sync 会比较大小和最后修改时间并跳过未变更的文件,这正是 4 秒部署和 4 分钟部署之间的差别。
  • 始终用 aws s3api head-object 做验证:检查 ContentLength、ContentType 和 ETag 后缀,因为文件可能以 binary/octet-stream "成功"上传,然后让每一个加载你 CSS 的浏览器都出问题。

真正会卡住你首次上传的前置条件

在第一个字节开始传输之前,你需要对齐三件事:存储桶所在的区域、具备 s3:PutObject 权限的凭证,以及(如果存储桶使用 SSE-KMS)密钥本身的权限。

先从显式固定区域开始。存储桶名称全局唯一,但一个桶只存在于一个区域,而 CLI 会很乐意用你默认的 us-east-1 配置去访问一个位于 eu-west-1 的桶:

aws sts get-caller-identity            # 我是谁,属于哪个账户
aws s3api get-bucket-location --bucket my-bucket --output text
# us-east-1 会返回 "None" —— 这不是 bug,AWS 就是这么报的


如果你还没装 CLI,`aws --version` 应该打印 `aws-cli/2.x`。v1 仍存在于较老的 AMI 上,并且在分片上传和错误输出上行为不同,所以在调试任何奇怪问题之前先升级。

一次可用上传所需的最小 IAM 权限很小,我宁愿授予这些权限也不愿给 `s3:*`:

```json
{
  "Effect": "Allow",
  "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
  "Resource": "arn:aws:s3:::my-bucket/*"
}


`AbortMultipartUpload` 在实践中并不是可选项。没有它,一次失败的传输会留下不完整的分片,而且在生命周期规则清理之前你一直要为这些存储付费——我见过一次中断的视频上传留下 40 GB 的孤儿分片。

## 上传单个文件:aws s3 cp 和值得敲的那些参数

先说顺利路径:

```bash
aws s3 cp ./index.html s3://my-bucket/index.html 
  --content-type "text/html; charset=utf-8" 
  --cache-control "public, max-age=300"


成功时这条命令只会打印一行:


upload: ./index.html to s3://my-bucket/index.html


其中两个参数的重要性远超表面。`--content-type` 会覆盖 CLI 基于扩展名的猜测——对 `.html` 没问题,但对 `.mjs`、`.wasm` 或任何要提供给浏览器的东西就不太妙了。`--cache-control` 决定了 CloudFront 是每 5 分钟回源验证一次还是一年一次;带哈希的文件名(`app.9f2c1a.js`)值得用 `max-age=31536000, immutable`,而 `index.html` 永远不该享受这种待遇。

对于超过 5 GB 的任何文件,单次 PUT 根本不被允许——S3 单个请求上限为 5 GB,而 CLI 在超过 8 MB 时会自动切换到分片上传。你可以调整这个阈值:

```bash
aws configure set default.s3.multipart_threshold 64MB
aws configure set default.s3.multipart_chunksize 16MB
aws configure set default.s3.max_concurrent_requests 20


在带宽充足的情况下,把并发数从 10 提到 20 大致能把大文件的墙钟时间减半;在一条 50 Mbps 的办公室线路上,除了内存占用之外什么都不会变。在把它固化进 CI 镜像之前先测一测。

当文件是在你的应用内部生成的,不要再去调 shell——用 SDK 的托管传输:

```python
import boto3
s3 = boto3.client("s3", region_name="us-east-1")
s3.upload_file(
    Filename="export.csv",
    Bucket="my-bucket",
    Key="exports/2026-02/export.csv",
    ExtraArgs={"ContentType": "text/csv", "ServerSideEncryption": "AES256"},
)


`upload_file` 会替你处理分片、重试和线程池。`put_object` 不会,而且它对无法测量长度的流会静默失败。

## 批量上传:cp --recursive 与 s3 sync 的区别

这两个命令看起来可以互换,实际上并不能。

`aws s3 cp ./dist s3://my-bucket/ --recursive` 每次都会拷贝每一个文件。对一个 900 个文件的静态构建来说,每次部署就是 900 次 PUT,而请求是按每 1000 次计费的——PUT 这一行费用在涨,存储那一行却纹丝不动。

`aws s3 sync ./dist s3://my-bucket/` 会先列出目标端,然后只上传大小或最后修改时间不同的文件。同样 900 个文件的构建,第二次部署:上传 3 个文件,六秒。而一次完整重建后的首次部署:所有文件都要上传,因为每个 mtime 都变了。

过滤器顺序是这里的陷阱。`--exclude` 和 `--include` 按从左到右的顺序求值,所以 include 必须写在它想要"救回来"的那个 exclude *之后*:

```bash
aws s3 sync ./dist s3://my-bucket/ 
  --exclude "*" --include "*.js" --include "*.css" --include "*.html" 
  --cache-control "public, max-age=31536000, immutable" 
  --dryrun


始终先跑 `--dryrun`。它会打印出确切的 `upload:` 行而不碰 S3,这是抓住 `./dist/` 与 `./build/` 这类路径笔误最便宜的办法。

## 关键参数一览

| 参数 | 控制什么 | 建议值 |
|---|---|---|
| `--region` | CLI 签名所针对的端点 | 脚本中始终显式设置 |
| `--content-type` | `Content-Type` 响应头 | 对 `.mjs`、`.wasm`、`.json`、`.svg` 手动设置 |
| `--cache-control` | 浏览器/CDN 缓存 | 带哈希的资源用 `max-age=31536000, immutable`;`index.html` 用 `max-age=0` |
| `--storage-class` | 存储层级 | 活跃资源用 `STANDARD`;访问模式不可预测且大于 128 KB 的对象用 `INTELLIGENT_TIERING` |
| `--sse` | 服务端加密 | 合规要求客户托管密钥时用 `aws:kms`,否则用桶默认值 |
| `--acl` | 遗留的按对象 ACL | 省略 —— Object Ownership 默认是 bucket-owner-enforced,会拒绝 ACL |
| `--dryrun` | 仅预览 | 在 CI 中或新目录下永远先跑一次 |
| `--delete` | 删除目标端在本地已不存在的对象 | 只配合 `sync` 使用,且必须在 `--dryrun` 之后 |

## 如何验证上传确实落地

`aws s3 ls` 只能证明某个键存在,不能证明字节是对的。

```bash
aws s3api head-object --bucket my-bucket --key dist/app.js 
  --query '{Size:ContentLength,Type:ContentType,ETag:ETag,Meta:Metadata}'


小文件的预期输出:

```json
{
    "Size": 48213,
    "Type": "application/javascript",
    "ETag": ""5d41402abc4b2a76b9719d911017c592"",
    "Meta": {}
}


带 `-3` 后缀的 ETag 意味着该对象是以三个分片上传的,因此 ETag 不再是 MD5,拿它和本地的 `md5sum` 比较永远对不上。改为比较大小,或者使用 `aws s3api get-object-attributes --object-attributes ObjectSize,Checksum`。自 2020 年 12 月起 S3 的写后读就是强一致的,所以只要 `head-object` 显示的是新大小,对象就是真的在那里——没必要像 2019 年那样写 sleep 循环反复重试。

要做整桶的完整性检查,`aws s3 ls s3://my-bucket/dist/ --recursive --summarize` 会打印对象总数和总字节数,你可以拿它和 `find ./dist -type f | wc -l` 做对比。

## 什么时候不该用 S3 上传(或不该用这个方法)

不要用 CLI 去同步一个装着 20 万个碎文件的目录。在这种规模下,单对象的开销会占据主导;每次 PUT 都是一次往返,而 `sync` 还得先 LIST 目标端,每页只返回 1,000 个键。用 SDK 的 `upload_fileobj` 在线程池里批量处理,或者把它们合并成更少、更大的对象。

不要把 S3 当作数据库或 Git 仓库的挂载文件系统。对象是不可变的,只能整体替换;没有原地写入,也没有文件锁。

不要为了建站就把存储桶公开。通过带 Origin Access Control 的 CloudFront 分发资源,保持 Block Public Access 开启,私有下载发预签名 URL——记住 SigV4 预签名 URL 最长只能 7 天。

## 坑、真实的报错字符串,以及我凌晨 02:10 追查的那个 KMS AccessDenied

先说最要命的那个。存储桶的默认加密设成了客户托管的 KMS 密钥,IAM 角色对桶有 `s3:PutObject`,但每次上传都失败于:


An error occurred (AccessDenied) when calling the PutObject operation: Access Denied


报错信息里没有一个字提到 KMS。我最初的假设是桶策略里有 Deny,于是把策略拉出来看——干干净净。然后我用 `--debug` 重跑,读到真正的请求:`x-amz-server-side-encryption: aws:kms`。这就是线索。单靠 `s3:PutObject` 对 SSE-S3 就够了,但 SSE-KMS 还需要密钥上的 `kms:GenerateDataKey`,而这个角色没有。确认只花了一次 CloudTrail 查询,查 `GenerateDataKey` 事件,其 `errorCode` 字段显示 `AccessDenied`。修复就是在密钥策略上加一条语句:

```json
{
  "Effect": "Allow",
  "Principal": {"AWS": "arn:aws:iam::123456789012:role/deploy"},
  "Action": ["kms:GenerateDataKey", "kms:Decrypt"],
  "Resource": "*"
}


`kms:Decrypt` 同样重要,因为 `sync` 和 `cp --recursive` 会读取目标端的对象元数据,一个没有 Decrypt 权限的密钥会让比较步骤直接崩掉。

第二常见,看起来比实际可怕:


An error occurred (PermanentRedirect) when calling the PutObject operation: The bucket you are trying to access must be addressed using the specified endpoint.


桶在 `eu-west-1`,而你的配置默认是 `us-east-1`。加上 `--region eu-west-1` 或设置 `AWS_REGION`。什么都没坏,你只是签到了错误的端点。

第三:`aws s3 sync` 每次运行都打印 `upload: ./dist/app.js to ...`,尽管什么都没变。这是 mtime 漂移——某个 CI 步骤用新时间戳重写了文件,或者一次 `cp -p` 把它们丢掉了。`--size-only` 能暂时糊过去,但真正的修复是让构建变得确定,或者让 `sync` 使用 `--exact-timestamps`。

如果你不想自己维护这套 IAM/KMS 权限矩阵,awsgood.com 的运维团队会把这类存储桶基线配置作为其托管 AWS 服务的一部分一并搭好。

## 参考资料

- [AWS CLI `s3 cp` 参考](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html)
- [将对象上传到 Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)
- [在 S3 中检查对象完整性](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html)
- [使用预签名 URL 共享对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注