CloudflareR2对象存储 cloudflare-r2

---

name: cloudflare-r2 description: Cloudflare R2 S3兼容的对象存储。用于桶、上传、CORS、预签名URL，或遇到R2_ERROR、CORS失败、多部分问题。

关键词：r2, r2 storage, cloudflare r2, r2 bucket, r2 upload, r2 download, r2 binding, object storage, s3 compatible, r2 cors, presigned urls, multipart upload, r2 api, r2 workers, file upload, asset storage, R2_ERROR, R2Bucket, r2 metadata, custom metadata, http metadata, content-type, cache-control, aws4fetch, s3 client, bulk delete, r2 list, storage class license: MIT metadata: version: “3.0.0” last_verified: “2025-12-27” production_tested: true token_savings: “~65%” errors_prevented: 12 templates_included: 5 references_included: 11 agents_included: 5 commands_included: 4 scripts_included: 3 wrangler_version: “4.50.0” workers_types_version: “4.20251126.0” aws4fetch_version: “1.0.20”

Cloudflare R2 对象存储

状态: 生产就绪 ✅ | 最后验证: 2025-12-27 | v3.0.0

目录: 快速开始 • 新特性 • 核心R2 API • 关键规则 • 代理与命令 • 参考

---

快速开始（5分钟）

1. 创建R2桶

bunx wrangler r2 bucket create my-bucket

桶命名: 3-63字符，仅限小写字母、数字、连字符

2. 配置绑定

添加到 wrangler.jsonc:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",          // env.MY_BUCKET
      "bucket_name": "my-bucket",      // 实际桶
      "preview_bucket_name": "my-bucket-preview"  // 可选：开发桶
    }
  ]
}

关键: binding = 代码访问名称，bucket_name = 实际R2桶

3. 基础上传/下载

import { Hono } from 'hono';

type Bindings = {
  MY_BUCKET: R2Bucket;
};

const app = new Hono<{ Bindings: Bindings }>();

// 上传
app.put('/upload/:filename', async (c) => {
  const filename = c.req.param('filename');
  const body = await c.req.arrayBuffer();

  const object = await c.env.MY_BUCKET.put(filename, body, {
    httpMetadata: {
      contentType: c.req.header('content-type') || 'application/octet-stream',
    },
  });

  return c.json({
    success: true,
    key: object.key,
    size: object.size,
  });
});

// 下载
app.get('/download/:filename', async (c) => {
  const object = await c.env.MY_BUCKET.get(c.req.param('filename'));

  if (!object) {
    return c.json({ error: '未找到' }, 404);
  }

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream',
      'ETag': object.httpEtag,
    },
  });
});

export default app;

加载 references/setup-guide.md 获取完整设置指南。

---

R2 新特性（2025）

🆕 R2 SQL集成 - 使用分布式SQL查询CSV/Parquet/JSON数据。无ETL分析。加载 references/r2-sql-integration.md

🆕 数据目录（Apache Iceberg） - 表版本控制、时间旅行查询、模式演进。Spark/Snowflake集成。加载 references/data-catalog-iceberg.md

🆕 事件通知 - 在对象更改时触发Workers（上传/删除）。自动化图像处理、备份、webhook。加载 references/event-notifications.md

高级特性 - 存储类、桶锁（合规）、tus可恢复上传、SSE-C加密。加载 references/advanced-features.md

零信任安全 - Cloudflare Access集成SSO、MFA、身份策略、审计日志。加载 references/cloudflare-access-integration.md

性能调优 - 缓存策略、压缩、范围请求、ETag、监控最佳实践。加载 references/performance-optimization.md

---

核心R2 Workers API - 快速参考

put() - 上传对象

await env.MY_BUCKET.put(key, data, options?)

带元数据上传，使用 onlyIf 防止覆盖。加载 references/workers-api.md 获取完整R2PutOptions。

get() - 下载对象

const object = await env.MY_BUCKET.get(key, options?)

返回 R2ObjectBody | null。支持范围请求、条件操作。加载 references/workers-api.md 获取读取方法（text(), json(), arrayBuffer(), blob()）。

head() - 仅获取元数据

const object = await env.MY_BUCKET.head(key)

检查存在性，获取大小、etag、元数据而无需下载主体。适用于验证和缓存。

delete() - 删除对象

await env.MY_BUCKET.delete(key | keys[])  // 单个或批量（最多1000个）

批量删除最多1000个键，单次调用。总是成功（幂等）。

list() - 列出对象

const listed = await env.MY_BUCKET.list(options?)

带游标分页、前缀过滤、分隔符用于文件夹。加载 references/workers-api.md 获取R2ListOptions。

createMultipartUpload() - 大文件（>100MB）

const multipart = await env.MY_BUCKET.createMultipartUpload(key, options?)

用于文件>100MB。加载 references/common-patterns.md 获取完整多部分工作流，包括部分上传和完成。

加载 references/workers-api.md 当: 需要完整API参考、接口定义（R2Object, R2ObjectBody, R2PutOptions, R2GetOptions）、条件操作、校验和或高级选项时。

---

关键规则

始终做 ✅

1. 上传时设置contentType - 否则文件将以二进制下载
2. 多个对象使用批量删除（最多1000个键）
3. 静态资源设置缓存头（cacheControl）
4. 大客户端上传使用预签名URL
5. 文件>100MB使用多部分上传
6. 浏览器上传前设置CORS策略
7. 预签名URL上设置过期时间（1-24小时）
8. 错误处理使用try/catch
9. 仅需元数据时使用head()（非get()）
10. 使用条件操作防止覆盖

永远不要做 ❌

1. 永远不要在客户端代码中暴露R2访问密钥
2. 永远不要跳过contentType（文件将以二进制下载）
3. 永远不要在循环中删除（使用批量删除）
4. 永远不要无错误处理上传
5. 永远不要浏览器上传跳过CORS
6. 永远不要小文件使用多部分（<5MB开销）
7. 永远不要单次调用删除>1000个键（会失败）
8. 永远不要假设上传成功（始终检查响应）
9. 永远不要跳过预签名URL过期（安全风险）
10. 永远不要硬编码桶名（使用绑定）

---

顶级用例

用例1：图像/资源存储

app.put('/api/upload/image', async (c) => {
  const file = await c.req.parseBody();
  const image = file['image'] as File;

  await c.env.MY_BUCKET.put(`images/${image.name}`, image.stream(), {
    httpMetadata: {
      contentType: image.type,
      cacheControl: 'public, max-age=31536000, immutable',
    },
  });

  return c.json({ success: true });
});

用例2：直接客户端上传（预签名URL）

为客户端上传生成安全上传URL。见 templates/r2-presigned-urls.ts 使用aws4fetch的完整实现。

参考中其他模式

加载 references/common-patterns.md 用于:

• 多部分上传（文件>100MB） - 带部分管理的完整工作流
• 批量操作 - 批量删除、带分页的清理模式
• 自定义元数据跟踪 - 用户文件、版本、审批工作流
• 版本化文件存储 - 带最新指针模式的版本历史
• 备份与归档模式 - 带保留策略的自动备份
• 缩略图生成与缓存 - 按需图像处理
• 静态网站托管 - SPA回退和缓存策略
• CDN与源回退 - R2作为缓存层

加载 templates/r2-multipart-upload.ts 获取完整多部分示例。

---

可用代理与命令

自主代理

代理自动处理复杂多步骤工作流:

• r2-setup-automator - 完整R2设置（桶创建 → 绑定 → TypeScript类型 → 部署）
• multipart-orchestrator - 大文件上传，带分块、错误恢复和进度跟踪
• cors-debugger - 系统化CORS故障排除，带配置生成和测试
• s3-migration-planner - AWS S3到R2迁移规划、数据传输和成本分析
• event-notification-setup - 事件驱动工作流，带Workers、Queues和自动化

快速命令

快速访问常见R2操作:

• /r2-setup - 在wrangler.jsonc中创建桶和配置绑定
• /r2-presigned-url - 为安全客户端上传/下载生成预签名URL
• /r2-cors-debug - 诊断和修复CORS配置问题
• /r2-multipart-init - 为大文件初始化多部分上传工作流

---

何时加载参考

核心参考（现有特性）

references/setup-guide.md - 首次设置、绑定配置、TypeScript类型、部署指南

references/workers-api.md - 完整API参考（所有方法 + 选项）、条件操作、校验和

references/common-patterns.md - 多部分上传、带回退的重试逻辑、批量操作、缓存策略

references/s3-compatibility.md - S3迁移指南、S3客户端库使用、aws4fetch预签名URL签名

references/cors-configuration.md - 浏览器访问设置、CORS调试、安全策略、Dashboard配置

新特性参考（2025）

references/event-notifications.md - 事件驱动自动化、Queue集成、图像处理、webhook触发器

references/advanced-features.md - 存储类（成本优化）、桶锁（合规）、tus可恢复上传、SSE-C加密

references/r2-sql-integration.md - R2数据的SQL查询（CSV/Parquet/JSON）、分析模式、性能调优

references/data-catalog-iceberg.md - Apache Iceberg表、时间旅行查询、模式演进、Spark/Snowflake集成

references/cloudflare-access-integration.md - 零信任安全、SSO（Google/Okta/Azure AD）、身份策略、MFA、审计日志

references/performance-optimization.md - 缓存（浏览器/CDN/Workers）、压缩（gzip/Brotli）、范围请求、ETag、监控

---

使用捆绑资源

参考（references/）

• setup-guide.md - 完整设置指南（桶创建 → 部署）
• workers-api.md - 完整Workers API参考（所有方法 + 选项）
• common-patterns.md - 高级模式（多部分、重试、批量、性能）
• s3-compatibility.md - S3兼容性指南（迁移、aws4fetch、S3客户端）
• cors-configuration.md - CORS设置指南（Dashboard、场景、故障排除、安全）

模板（templates/）

• r2-simple-upload.ts - 基础上传/下载Worker
• r2-multipart-upload.ts - 完整多部分上传实现
• r2-presigned-urls.ts - 预签名URL生成（上传 + 下载）
• r2-cors-config.json - CORS配置示例
• wrangler-r2-config.jsonc - 带R2绑定的完整wrangler.jsonc

---

CORS配置

为浏览器上传/下载配置CORS。加载 references/cors-configuration.md 获取完整指南，包括Dashboard设置、常见场景、故障排除和安全最佳实践。

---

错误处理

try {
  await env.MY_BUCKET.put(key, data);
} catch (error: any) {
  const message = error.message;

  if (message.includes('R2_ERROR')) {
    // 通用R2错误
  } else if (message.includes('exceeded')) {
    // 配额超限
  } else if (message.includes('precondition')) {
    // 条件操作失败（onlyIf）
  }

  console.error('R2错误:', message);
  return c.json({ error: '存储操作失败' }, 500);
}

加载 references/common-patterns.md 获取带指数回退的重试逻辑、断路器模式和高级错误恢复。

---

已预防的已知问题

问题	描述	解决方案
CORS错误	浏览器无法上传/下载	在桶设置中配置CORS
文件以二进制下载	缺少content-type	始终设置 httpMetadata.contentType
预签名URL安全	URL永不过期	始终设置 X-Amz-Expires（1-24小时）
多部分限制	部分>100MB或>10,000部分	保持部分5MB-100MB，最多10,000
批量删除限制	>1000个键失败	将删除分块为每批1000个
元数据溢出	>2KB自定义元数据	保持总计低于2KB

---

Wrangler命令

# 桶管理
wrangler r2 bucket create <BUCKET_NAME>
wrangler r2 bucket list
wrangler r2 bucket delete <BUCKET_NAME>

# 对象管理
wrangler r2 object put <BUCKET>/<KEY> --file=<PATH>
wrangler r2 object get <BUCKET>/<KEY> --file=<OUTPUT>
wrangler r2 object delete <BUCKET>/<KEY>

# 列出对象
wrangler r2 object list <BUCKET>
wrangler r2 object list <BUCKET> --prefix="folder/"

---

官方文档

• 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/

---

有问题？有疑问？

1. 检查 references/setup-guide.md 获取设置指南
2. 查看 references/workers-api.md 获取API参考
3. 见 references/common-patterns.md 获取高级模式
4. 加载 templates/ 获取工作代码示例