cloudflare-r2

用途

Cloudflare R2 是兼容 S3 协议的对象存储服务。本技能围绕在 Cloudflare Workers 中使用 R2 展开，用于处理存储桶管理、对象上传下载、CORS 配置、预签名 URL、分片上传等任务，并针对 R2_ERROR、CORS 失败、分片异常等常见问题提供排查与规避说明。

主要能力

核心 Workers API 包括：

put()：上传对象，可携带元数据，支持通过 onlyIf 防止覆盖。
get()：下载对象，返回 R2ObjectBody 或 null，支持范围请求与条件操作，并提供 text()、json()、arrayBuffer()、blob() 等读取方法。
head()：仅获取元数据，用于检查对象是否存在以及获取大小、etag、元数据，无需下载内容。
delete()：删除对象，支持单个或批量，批量单次最多 1000 个键，操作幂等。
list()：列出对象，支持游标分页、前缀过滤与分隔符模拟文件夹。
createMultipartUpload()：用于大于 100MB 的文件分片上传。

此外资料还提及若干 R2 特性内容，包括 R2 SQL 集成、Apache Iceberg 数据目录、事件通知、存储类别、存储桶锁（合规）、tus 可续传上传、SSE-C 加密、Cloudflare Access 零信任集成以及性能调优等，均以参考文档形式提供，正文未展开具体细节。

使用方式

创建存储桶：

bunx wrangler r2 bucket create my-bucket

存储桶命名规则为 3 至 63 个字符，仅允许小写字母、数字与连字符。

配置绑定，在 wrangler.jsonc 中添加：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "my-bucket",
      "preview_bucket_name": "my-bucket-preview"
    }
  ]
}

其中 binding 是代码中访问用的名称，bucket_name 是实际存储桶名称。

在 Worker 中通过 env.MY_BUCKET 调用上传下载逻辑。资料给出以 Hono 为例的上传与下载示例代码，上传时设置 httpMetadata.contentType，下载时返回对象 body 并附带 Content-Type 与 ETag 头。

Wrangler 命令还包括存储桶列表、删除，以及对象上传、下载、删除与按前缀列出等操作。

适用场景

图片与静态资源存储（设置 cacheControl 缓存头）。
客户端直传（使用预签名 URL，参考模板 r2-presigned-urls.ts，基于 aws4fetch）。
大文件上传（超过 100MB 使用分片上传）。
批量操作与清理（批量删除、分页清理）。
版本化文件存储、备份归档、缩略图生成与缓存、静态站点托管、以 R2 作为缓存层的 CDN 回源等，均在参考文档中作为模式列出。

资料还列出可用的自动化代理与快捷命令，例如 r2-setup-automator、multipart-orchestrator、cors-debugger、s3-migration-planner、event-notification-setup，以及 /r2-setup、/r2-presigned-url、/r2-cors-debug、/r2-multipart-init 等命令。

限制与注意事项

关键规则方面，务必设置 contentType，否则文件会以二进制形式下载；静态资源应设置缓存头；预签名 URL 需设置有效期（1 至 24 小时）；浏览器上传前需配置 CORS；多对象删除应使用批量删除；仅在需要元数据时使用 head()。禁止事项包括：不得在客户端代码暴露 R2 访问密钥，不得使用循环逐个删除，不得对小于 5MB 的文件使用分片上传，单次删除不得超过 1000 个键，不得硬编码存储桶名称。

已知问题与规避：CORS 错误需在存储桶设置中配置；缺少 content-type 会导致二进制下载；预签名 URL 不设过期存在安全风险；分片需保持在 5MB 至 100MB 之间且不超过 10000 片；批量删除超过 1000 个键会失败；自定义元数据总大小需低于 2KB。

错误处理方面，资料建议使用 try/catch，并根据错误信息中的 R2_ERROR、exceeded、precondition 等关键字区分错误类型；重试逻辑、指数退避与熔断等模式在参考文档中提供。

官方文档链接：R2 概览 https://developers.cloudflare.com/r2/ ；Workers API https://developers.cloudflare.com/r2/api/workers/workers-api-reference/ ；分片上传 https://developers.cloudflare.com/r2/api/workers/workers-multipart-usage/ ；预签名 URL https://developers.cloudflare.com/r2/api/s3/presigned-urls/ ；CORS 配置 https://developers.cloudflare.com/r2/buckets/cors/ 。

关于收费、价格与具体配额，资料未提供明确信息。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项