01 它是干嘛的
R2 是兼容 S3 API 的对象存储。它最大的卖点是「零出网费（Zero Egress Fees）」：把数据读出去不收费。这直接击中了所有使用对象存储的用户最痛的地方——数据存进去很便宜，取出来很贵。
02 为什么会有它
为什么云存储的账单里，最贵的一行往往是「流量费」
对象存储的定价结构是：存储费便宜（每 GB 每月几分钱），但把数据读出去（出网流量）要按 GB 收费。这对视频站、下载站、SaaS 备份这类「写一次、读无数次」的业务是灾难——数据放着不动很便宜，一被访问账单就爆炸。这就是业界流传的「数据重力」与「供应商锁定」：存进去容易，搬出来贵得让你不想搬。
Cloudflare 自己并不建存储硬件。它利用一个事实：在对象存储的成本结构里，存储本身很便宜，贵的是把数据从存储搬出来经过运营商的带宽。Cloudflare 与全球各地的存储机房有互联，把文件存在这些机房，用户读取时走 Cloudflare 的网络，边际成本极低。
因此 R2 的商业模式是「用存储费赚钱、把出网费免掉」，同时因为它兼容 S3 API，迁移只需改一个 endpoint，历史代码几乎不用动。
03 它怎么工作
对象存储不提供文件系统，而是「桶（Bucket）+ 对象（Object）」的扁平结构，大文件被切成多块并发上传，读取时通过 API 或 CDN 分发。
一个文件从上传到被全球访问：分片、元数据与边缘缓存
- 1① 客户端申请上传
前端或后端向 R2 请求上传凭证，通常由服务端签发临时签名 URL，避免把密钥暴露给浏览器。
- 2② 大文件分片并发上传
文件被切成若干 MB 的分片并行传输，单片失败只需重传该片，几百 GB 的文件也能稳定上传。
- 3③ 服务端合并并写入元数据
所有分片合并成一个对象，同时记录大小、类型、哈希、自定义标签等元数据，用于检索与管理。
- 4④ 读取走边缘缓存
读请求先命中 Cloudflare 边缘缓存，热点文件不必回源到存储，访问速度接近静态 CDN。
- 5⑤ 生命周期策略自动整理
可按规则把冷数据降级、30 天后自动删除、或复制到其他桶做备份。
04 谁在用它
用户上传的头像、附件、商品图，存进 R2 后由 CDN 分发，省钱且快。
作为视频点播的原始文件仓库，播放时经 CDN 分发，避免按 GB 计费的出网账单。
数据库备份、日志归档长期存放，出网费为零使「需要时才取回」的策略变得可行。
用 S3 兼容 API 把既有数据平滑迁移，或做双写以获得跨云容灾。
05 怎么用
会 S3 就会 R2，主要差异只有 endpoint 与密钥体系。
- 01控制台进入 R2，创建一个桶（Bucket），命名需全局唯一。
- 02创建 API Token（访问密钥），注意最小权限原则，只授予所需桶的读写。
- 03用 aws-cli、rclone 或 SDK 指向 R2 的 endpoint 进行读写。
- 04为需要公网访问的内容绑定自定义域名，并开启缓存以加速与降低成本。
- 05配置生命周期规则：自动删除临时文件、把冷数据转为低频存储。
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
const r2 = new S3Client({
region: 'auto',
endpoint: 'https://<accountid>.r2.cloudflarestorage.com',
credentials: {
accessKeyId: process.env.R2_ACCESS_KEY_ID!,
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!
}
})
await r2.send(new PutObjectCommand({
Bucket: 'my-assets',
Key: 'avatars/user-1.png',
Body: fileBuffer,
ContentType: 'image/png'
}))避坑提示
- !不要把长期密钥写进前端代码，公网访问请用签名 URL 或自定义域名 + 访问策略。
- !对象存储没有「重命名」，改名等于复制后删除，大文件操作前先评估耗时与费用。
- !桶名全局唯一且不可改，命名时带上业务与环境的语义（如 prod-assets-cn）。
06 关键概念
- 对象存储
- 用「桶 + 键」的方式存文件的仓库，不支持目录树，也不能像磁盘一样随机改写。
- 出网流量费
- 把数据从云上读出去时按 GB 收的网络费，是云账单里最容易失控的一项。
- 预签名 URL
- 服务端临时签发的带权限与有效期的下载地址，让客户端直传而不用暴露密钥。
- 生命周期规则
- 按时间自动转移或删除对象的策略，用于控制长期成本。