cloudflare-r2

用途

Cloudflare R2 是兼容 S3 的对象存储服务，其显著特点是零出口流量费用（egress free）。它既可以通过 Cloudflare Workers 的 Binding API 访问，也可以通过标准 S3 API 访问，适合在 Workers、Pages 等应用中存储和读取文件对象。

主要能力

存储桶与对象管理：创建、删除、列出存储桶；对对象执行 head、get、put、delete、list 等操作。
Workers Binding API（R2Bucket）：提供 head(key)、get(key, options?)、put(key, value, options?)、delete(key | keys[])、list(options?)、createMultipartUpload(key, options?)、resumeMultipartUpload(key, uploadId) 等方法。
S3 API 兼容：端点格式为 https://<ACCOUNT_ID>.r2.cloudflarestorage.com，region 固定为 "auto"（或 "us-east-1" 别名）。
预签名 URL：可生成下载与上传的预签名 URL，需注意仅适用于 S3 端点，不适用于自定义域名。
分片上传：适用于大于 100 MB 的对象，支持创建、上传分片、完成或中止，以及断点续传。
CORS 配置：可通过 JSON 文件与 wrangler 命令设置跨域规则。
生命周期策略：支持按天数过期删除、转为低频访问类别、按前缀应用规则、中止未完成的分片上传。
存储类别：Standard 与 InfrequentAccess 两种。
事件通知：对象创建或删除时推送到 Cloudflare Queues。
公开访问：支持自定义域名（推荐）与 r2.dev 开发用公开 URL。
数据迁移：Super Slurper 用于批量迁移，Sippy 用于按需增量迁移。
条件操作与加密：支持 onlyIf 条件（etagMatches、etagDoesNotMatch、uploadedBefore、uploadedAfter）以及 SSE-C 服务端加密。

使用方式

快速开始：

npx wrangler r2 bucket create my-bucket

在 wrangler.jsonc 中配置绑定：

{
  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }]
}

Worker 中通过 env.MY_BUCKET 访问，示例代码展示了 PUT 上传与 GET 读取对象并写出 HTTP 元数据与 etag 的写法。

绑定配置还支持可选的 preview_bucket_name（本地开发用）与 jurisdiction（如 "eu"，用于 GDPR）。

带范围读取：

const partial = await env.MY_BUCKET.get("large.bin", {
  range: { offset: 0, length: 1024 },
});

带元数据写入：

await env.MY_BUCKET.put("file.txt", "Hello!", {
  httpMetadata: { contentType: "text/plain" },
  customMetadata: { author: "Alice" },
  storageClass: "InfrequentAccess",
});

分页列出：

const listed = await env.MY_BUCKET.list({ prefix: "images/", limit: 100 });
for (const obj of listed.objects) console.log(obj.key, obj.size);
if (listed.truncated) {
  /* use listed.cursor for next page */
}

S3 客户端示例：

import { S3Client } from "@aws-sdk/client-s3";

const S3 = new S3Client({
  region: "auto",
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: { accessKeyId: ACCESS_KEY_ID, secretAccessKey: SECRET_ACCESS_KEY },
});

预签名 URL 示例：

import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const downloadUrl = await getSignedUrl(S3, new GetObjectCommand({ Bucket: "my-bucket", Key: "file.pdf" }), { expiresIn: 3600 });

const uploadUrl = await getSignedUrl(S3, new PutObjectCommand({ Bucket: "my-bucket", Key: "file.pdf", ContentType: "application/pdf" }), { expiresIn: 3600 });

分片上传示例：

const mpu = await env.MY_BUCKET.createMultipartUpload("large.zip");
const part1 = await mpu.uploadPart(1, chunk1); // Min 5 MiB
const part2 = await mpu.uploadPart(2, chunk2);
await mpu.complete([part1, part2]);
// or: await mpu.abort();

CORS 配置示例：

[
  {
    "AllowedOrigins": ["https://example.com"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedHeaders": ["Content-Type"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

npx wrangler r2 bucket cors set my-bucket --file cors.json

生命周期策略示例：

# Delete after 90 days
npx wrangler r2 bucket lifecycle add my-bucket --id "cleanup" --expire-days 90

# Transition to Infrequent Access
npx wrangler r2 bucket lifecycle add my-bucket --id "archive" --transition-days 30 --transition-class STANDARD_IA

# With prefix
npx wrangler r2 bucket lifecycle add my-bucket --id "logs" --prefix "logs/" --expire-days 7

# Abort incomplete multipart
npx wrangler r2 bucket lifecycle add my-bucket --id "mpu" --abort-incomplete-days 1

事件通知示例：

npx wrangler queues create r2-events
npx wrangler r2 bucket notification create my-bucket --event-type object-create --queue r2-events

事件类型包括 object-create 与 object-delete。

Wrangler 命令涵盖存储桶、对象、CORS、生命周期、通知与 Sippy 等子命令。

适用场景

在 Cloudflare Workers 或 Pages 应用中存储与读取文件对象。
需要兼容 S3 接口、且关注出口流量成本的存储需求。
大文件上传（分片上传）、浏览器直传（预签名 URL + CORS）。
需要生命周期自动清理、低频归档、事件驱动处理（配合 Queues）的场景。
从 S3/GCS 等兼容存储迁移数据。

限制与注意事项

预签名 URL 仅适用于 S3 端点，不适用于自定义域名。
r2.dev 仅用于开发，有速率限制，生产环境应使用自定义域名。
分片上传每片最小 5 MiB，最大 5 GiB，最多 10,000 片，对象最大约 5 TiB。
单次上传最大 5 GiB；键长度最大 1,024 字节；元数据最大 8,192 字节；批量删除最多 1,000 个键。
每账户最多 1,000,000 个存储桶；每桶最多 1,000 条生命周期规则、100 条通知规则。
浏览器访问需配置 CORS；不要将加密密钥写入代码；SSE-C 密钥丢失即数据丢失。
定价方面：Standard 存储 $0.015/GB，InfrequentAccess 存储 $0.01/GB 且有 $0.01/GB 取回费用与 30 天最短存储期；Class A 操作 Standard $4.50/百万、IA $9.00/百万；Class B 操作 Standard $0.36/百万、IA $0.90/百万；取回 Standard 免费、IA $0.01/GB；出口流量免费。免费额度为 10 GB 存储、1M Class A、10M Class B。Class A 包括 PUT、COPY、LIST、CreateMultipartUpload；Class B 包括 GET、HEAD；DELETE、AbortMultipartUpload 免费。
Super Slurper 迁移会跳过大于 1 TB 的对象。

以上内容均来自所提供资料，未提供的细节暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项