第16章 R2对象存储集成指南
文档 R2 是对象存储。Worker 通过 r2_buckets binding 访问一个 bucket。celld 把对象存入节点用 --bucket 打开的 fleet bucket,因此 R2 具备该对象存储的持久性。在没有 fleet bucket 的节点上,所有 R2 方法都会失败。API 详情请阅读 Workers API 参考。
示例 R2 示例演示了在 R2 bucket 中读取、写入和删除对象。
index.js export default { async fetch(request, env) { const key = new URL(request.url).pathname.slice(1); if (!key) return new Response("Use /KEY.", { status: 400 });
if (request.method === "PUT") { await env.FILES.put(key, request.body, { httpMetadata: { contentType: request.headers.get("content-type") ?? "application/octet-stream", }, }); return new Response(null, { status: 204 }); }
if (request.method === "DELETE") { await env.FILES.delete(key); return new Response(null, { status: 204 }); }
if (request.method === "GET") { const object = await env.FILES.get(key); if (object === null) return new Response("Not found.", { status: 404 });
const headers = new Headers(); object.writeHttpMetadata(headers); headers.set("etag", object.httpEtag); return new Response(object.body, { headers }); }
return new Response("Method not allowed.", { status: 405 }); }, };
wrangler.jsonc { "name": "r2", "main": "index.js", "compatibility_date": "2026-01-01", "r2_buckets": [ { "binding": "FILES", "bucket_name": "example-files" } ] }
API
get(key, { range, onlyIf }) 返回一个带流式 body 的 R2ObjectBody,或 null。range 可以是 offset、length、suffix 或 Range header。 head(key) 返回对象记录,但不包含 body。 put(key, value, { httpMetadata, customMetadata, onlyIf }) 接受 string、ArrayBuffer、typed array、Blob 或 ReadableStream。条件被拒绝时返回 null。 delete(keys) 删除一个 key 或一组 key。 list({ prefix, delimiter, cursor, startAfter }) 返回一页对象。 createMultipartUpload(key) 返回一个 handle。uploadPart(number, value) 上传一个 part,complete(parts) 组装对象。
Key 与存储
每个 binding 有自己的 bucket_name,celld 将 key
对象存储会把部分 key 以百分号编码形式保存:包含非 ASCII 字符、控制字符,或 % \ { } ^ ` [ ] " < > ~ # | * ? 之一的 key。例如 přehled.html 会变成 r2/
celld 0.5.1 及更早版本会从 key 中去掉空 segment。这类版本写入 photos/ 下的对象会留在 photos 下,list() 也把它作为 photos 返回。
Multipart upload 一个 multipart upload 存在于开启它的那个节点上。part 规则请阅读 Multipart upload。在 predecessor 之前到达的 part 会先驻留内存,上限 256 MiB,超过后 celld 会拒绝后续 part。等待中的 part 可以被替换;已写入对象存储的 part 则不行,celld 会拒绝这类写入。
与 Cloudflare 的差异
R2 binding 使用 fleet bucket 中 r2/
Cloudflare 兼容性页面列出了运行时 API 和不支持的服务。