Cloudflare R2 中文文档

本文参照 Cloudflare 官方手册结构，对 R2 做系统化梳理（数据截至 2026-10，配额/价格以官方最新页面为准）。技术术语保留英文原词以便对照官方资料。

1. 概述

Cloudflare R2 Storage 是 Cloudflare 的对象存储，与 S3 兼容。它最大的卖点是不收数据出网（egress）带宽费——这正是传统云存储最贵的部分。适合存放大量非结构化数据。

一句话定位：零出网费、S3 兼容的对象存储。

适用场景包括但不限于：云原生应用存储、Web 内容/媒体托管、播客音频、数据湖（分析/大数据）、机器学习产物与数据集。

2. 核心概念

2.1 Bucket / Object / Key

• Bucket（桶）：数据容器，容量与对象数均无限。
• Object（对象）：存进去的数据单元，由「数据 + 元数据」组成，用 Key（键） 寻址。
• Key（键）：对象的唯一路径名，长度上限 1,024 字节。

2.2 S3 兼容

R2 提供 S3 兼容 API，可复用大量现成的 S3 工具、SDK 与生态。

2.3 Class A / Class B 操作

• Class A（A 类）：偏「状态变更」，更贵——如 PutObject、CopyObject、UploadPart、ListObjects 等。
• Class B（B 类）：偏「读取」，更便宜——如 GetObject、HeadObject 等。
• 免费操作：DeleteObject、DeleteBucket、AbortMultipartUpload 不计费。

2.4 存储类别（Storage Class）

• Standard（标准）：默认类，免费额度适用此类。
• Infrequent Access（低频访问）：存储更便宜，但取回收费，且有 30 天最低存储时长（提前删/移仍按 30 天计费）。免费额度不适用于此类。

2.5 Location Hints

建桶时可指定数据主要访问区域，优化局部延迟。

2.6 公开访问

• r2.dev** 托管公开端点**：仅供测试，有可变限流（数百请求/秒级），超限临时节流并返回 429。
• 自定义域名公开桶：生产推荐，可配置缓存、重写规则、分析。

3. 架构与工作原理

• 对象以「桶 → 键」组织；读/写均为对象级强一致。
• 同 key 的并发写入被限到 1 次/秒，更快会返回 429。
• 大文件用多分片上传（最多 10,000 分片），单分片 5 GiB。
• 从 R2（含 Workers API、S3 API、r2.dev）直接出网到互联网免费。

4. 快速开始

# 1. 创建桶
wrangler r2 bucket create my-bucket

# 2. （可选）绑定到 Worker，见第 5 节
wrangler deploy

5. 使用方式（Workers API）

在 wrangler.jsonc 中绑定：

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ]
}

读取与写入对象：

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const key = url.pathname.slice(1); // 例如 "hello/index.html"

    if (request.method === "PUT") {
      const body = await request.arrayBuffer();
      await env.BUCKET.put(key, body, {
        httpMetadata: { contentType: "text/html" },
      });
      return new Response("stored");
    }

    const obj = await env.BUCKET.get(key);
    if (!obj) return new Response("not found", { status: 404 });
    return new Response(obj.body, {
      headers: { "content-type": obj.httpMetadata?.contentType ?? "application/octet-stream" },
    });
  },
} satisfies ExportedHandler<Env>;

也可使用 S3 兼容 API（通过 endpoint + Access Key/Secret）从任意环境访问，或使用 Cloudflare REST API（限流 1,200 次 / 5 分钟，适合低频管理操作）。

6. 配额与限制

• Cloudflare REST API 对 R2 限流：1,200 次 / 5 分钟（跨所有 R2 REST 操作）。
• r2.dev 公开端点可变限流（数百请求/秒级），超限临时节流并返回 429。

7. 定价

• Infrequent Access（低频访问）：存储 $0.01 / GB·月，Class A $9.00 / 百万，Class B $0.90 / 百万，取回收费，30 天最低存储时长。免费额度不适用于该类。
• 免费操作：DeleteObject、DeleteBucket、AbortMultipartUpload 不计费。

8. 最佳实践

• 大文件 / 媒体 / 静态 HTML 放 R2，比 D1 划算得多。
• 生产环境务必绑自定义域名，别用 r2.dev。
• 单对象上限 5 TiB、单分片 5 GiB；超大文件用多分片上传（最多 10,000 分片）。
• 给同一 key 的高频并发写入要限流到 ≤ 1 次/秒，否则会被 429。
• 评估成本时记住：读（Class B）极便宜、出网免费，真正的变量通常是存储与 Class A 写入。

9. 适用场景与选型

• 云原生应用存储、Web 内容/媒体托管、播客、数据湖、ML 产物。
• 需要存大文件、静态资源、备份 → 选 R2。
• 需要 SQL 关系查询 → 选 D1；需要全球低延迟、读多写少的全局小配置 → 选 KV。