cloudflare-r2

Cloudflare R2 对象存储

状态：已可用于生产环境 ✅ | 上次验证：2025-12-27 | v3.0.0

目录：快速开始 • 新功能 • R2 核心 API • 关键规则 • Agent 和命令 • 参考文档

---

快速开始（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",      // Actual bucket
      "preview_bucket_name": "my-bucket-preview"  // Optional: dev bucket
    }
  ]
}

重要：binding = 代码访问名称，bucket_name = 实际的 R2 存储桶

3. 基本上传/下载

import { Hono } from 'hono';

type Bindings = {
  MY_BUCKET: R2Bucket;
};

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

// Upload
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,
  });
});

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

  if (!object) {
    return c.json({ error: 'Not found' }, 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 防止覆盖。如需完整的 R2PutOptions，请加载 references/workers-api.md。

get() - 下载对象

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

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

head() - 仅获取元数据

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

无需下载对象主体即可检查对象是否存在并获取大小、etag 和元数据。适用于验证和缓存。

delete() - 删除对象

await env.MY_BUCKET.delete(key | keys[])  // Single or bulk (max 1000)

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

list() - 列出对象

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

支持使用游标进行分页、按前缀筛选，以及使用分隔符表示文件夹。如需了解 R2ListOptions，请加载 references/workers-api.md。

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，查看完整的分段上传示例。

---

可用的 Agent 与命令

自主 Agent

Agent 可自动处理复杂的多步骤工作流：

• 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 数据（CSV/Parquet/JSON）执行 SQL 查询、分析模式、性能调优

references/data-catalog-iceberg.md——Apache Iceberg 表、时间点查询、架构演进、Spark/Snowflake 集成

references/cloudflare-access-integration.md——Zero Trust 安全、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')) {
    // Generic R2 error
  } else if (message.includes('exceeded')) {
    // Quota exceeded
  } else if (message.includes('precondition')) {
    // Conditional operation failed (onlyIf)
  }

  console.error('R2 Error:', message);
  return c.json({ error: 'Storage operation failed' }, 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 命令

# Bucket management
wrangler r2 bucket create <BUCKET_NAME>
wrangler r2 bucket list
wrangler r2 bucket delete <BUCKET_NAME>

# Object management
wrangler r2 object put <BUCKET>/<KEY> --file=<PATH>
wrangler r2 object get <BUCKET>/<KEY> --file=<OUTPUT>
wrangler r2 object delete <BUCKET>/<KEY>

# List objects
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/ 获取可运行的代码示例