cloudflare-r2

Cloudflare R2 是 Cloudflare 提供的对象存储服务，具备 S3 兼容 API，部署在 Cloudflare 边缘网络上。本资料围绕在 Workers 中使用 R2 展开，整理其用途、主要能力、使用方式、适用场景与限制。

一、用途 R2 用于存储对象（文件），典型用途包括：上传与下载文件、配置 CORS、生成预签名 URL，以及在 Workers 中读写对象。资料中列出的依赖为 cloudflare-worker-base（用于 Worker 初始化），涉及的最新版本为 wrangler@4.59.2、@cloudflare/workers-types@4.20260109.0、aws4fetch@1.0.20。

二、主要能力

1. Worker 绑定 API：提供 put()（上传）、get()（下载）、head()（仅读取元数据）、delete()（单个或批量删除，批量最多 1000 个）、list()（列举，支持 prefix、limit、cursor、delimiter 以及 include 参数按需返回元数据）。
2. 条件操作：put() 支持 onlyIf 条件，用于避免覆盖已有对象。
3. 范围请求：get() 支持 range，用于部分下载。
4. 分段上传（Multipart Upload）：适用于大于 100MB 的文件或需要可恢复上传的场景，可通过 createMultipartUpload、resumeMultipartUpload、uploadPart、complete、abort 完成流程；每个分片 5MB 至 100MB，单次上传最多 10,000 个分片；不建议用于小于 5MB 的文件。
5. 预签名 URL：借助 aws4fetch 库，允许客户端直接上传或下载，绕过 Worker；需要设置过期时间。
6. 元数据：支持 httpMetadata（contentType、cacheControl、contentDisposition、contentEncoding 等）与 customMetadata（总量最大 2KB，键值必须为字符串）。
7. 校验：put() 支持 md5 校验。
8. 自定义域名：用于生产环境，可配合 Cloudflare 缓存与缓存规则。

三、使用方式 快速开始步骤：

1. 创建存储桶：npx wrangler r2 bucket create my-bucket
2. 在 wrangler.jsonc 中配置绑定，包含 binding、bucket_name，以及可选的 preview_bucket_name。
3. 在 Worker 中使用 env.MY_BUCKET.put() 上传，get() 下载，并通过 Response 返回对象内容与 ETag。
4. 部署：npx wrangler deploy

预签名 URL 示例使用 aws4fetch 的 AwsClient.sign()，通过 signQuery 生成带签名的请求 URL；上传示例使用 PUT 方法，下载使用 GET 方法。资料强调：预签名 URL 仅适用于 S3 API 域名（如 https://{accountId}.r2.cloudflarestorage.com/），不能用于自定义域名；典型做法是上传用预签名 S3 URL，访问用自定义域名。

Wrangler 的 API Token 需要「Admin Read & Write」权限，而非「Object Read & Write」，后者用于 S3 API 直接访问，使用错误权限会出现 403 Forbidden。

CORS 需要在存储桶设置中配置。资料特别指出 wrangler CLI 与 Dashboard UI 使用不同的 CORS 格式：Dashboard 格式为顶层对象数组（AllowedOrigins 等字段），CLI 格式则要求包含 rules 数组。使用 wrangler r2 bucket cors set 时若用 Dashboard 格式会报「The CORS configuration file must contain a 'rules' array」。自定义域名场景下，CORS 分两层处理：R2 存储桶 CORS（适用于预签名 URL 或直接 S3 访问）与 Transform Rules CORS（适用于经由自定义域名）。

四、适用场景

• 在 Worker 中实现文件上传与下载。
• 浏览器端直接上传或下载（通过预签名 URL）。
• 大文件、可恢复上传或需要并行上传的场景（分段上传）。
• 静态资源托管并配合缓存头。
• 使用自定义域名对外提供访问。

五、限制与注意事项

1. 安全性：绝不可在客户端代码中暴露 R2 访问密钥；预签名 URL 必须由服务端生成，并始终设置过期时间并先做鉴权。
2. r2.dev 域名（{bucket}.{account}.r2.cloudflarestorage.com）不适用于生产：存在可变速率限制（起始约每秒数百请求）、带宽限流、无 SLA，高负载下会出现 429；生产环境应始终使用自定义域名。
3. 并发写限制：对同一对象键的高频并发写入会触发 HTTP 429；应通过时间戳或 ID 分片写入，或改用 Durable Objects、Queues 批处理。
4. 重试：资料提到 R2 在 2025 年第一季度出现过两次较大中断（2 月 6 日 59 分钟、3 月 21 日 1 小时 7 分钟），建议对 5xx 与网络、超时等暂时性错误实现指数退避重试。
5. 其他注意：不要为所有上传遗漏 contentType；不要循环单个删除，使用批量删除；批量删除不超过 1000 个键；list() 需要显式 include 才能返回元数据；不要用分段上传处理小于 5MB 的文件；不要用自定义域名做预签名。

资料中还列出了 2025 年的若干更新，包括 R2 SQL 公开测试、Pipelines GA、远程绑定 GA、Dashboard 改版、Super Slurper 提速、R2 Data Catalog 公开测试、事件通知公开测试、存储桶上限提升到 100 万、CRC-64/NVME 校验和、使用客户密钥的服务端加密、低频访问存储类（测试）、大洋洲区域以及 S3 API 增强等。具体价格、计费与性能指标本文暂未提供。