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

太长不看(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)
推荐
推荐服务 · 一站式办理
由云市场认证服务商承接,下单后按需沟通交付。
腾讯云市场
NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
各服务器环境 SSL 证书安装配置,教程看不懂?直接交给服务商办。
查看服务 →
阿里云市场
代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名 DV
单域名 DV 证书代购,主流品牌可选,比官网渠道更省。
查看服务 →
阿里云市场
Wildcard 通配符 SSL 证书安装部署续费申请
一张通配符保护全部一级子域名,含安装部署与续费服务。
查看服务 →
腾讯云市场
SSL证书申请+配置 · 宝塔/WDCP 面板全站加密(OV 企业单域名等规格)
付费证书云上签发、一键部署到宝塔/WDCP 站点,OV 企业单域名可选。
查看服务 →
阿里云市场
企业级 EV / OV 证书与代码、驱动签名服务
SSL EV/OV 证书 + 软件代码签名、驱动签名,企业级一站式办理。
查看服务 →
阿里云市场
GlobalSign 代码签名证书服务(OV/EV 企业版)
对 exe/dll/驱动等软件做数字签名,消除「未知发布者」警告,企业版含申请代办。
查看服务 →
阿里云市场
HTTPS证书申请 · SSL证书安装部署 · 证书续费
证书过期、部署报错、需要续期?申请+部署+续费一站式办理。
查看服务 →
发表回复