cloudflare-r2

用途

Cloudflare R2 是兼容 S3 API 的对象存储服务，具备零出口流量费用，构建在 Cloudflare 全球网络之上。根据资料，它适合以下用途：存储用户上传内容、媒体文件、备份或静态资源；在读取密集型工作负载中替代 AWS S3 以消除出口费用；通过 Workers 或公共存储桶访问在边缘提供文件；构建避免厂商锁定的多云存储（兼容 S3 API）；存储机器学习模型产物、训练数据或推理结果。

前提条件

具有 R2 功能并已订阅的 Cloudflare 账户（控制台 > R2 > subscribe）。
已安装 Wrangler CLI v3+：npm install -g wrangler。
通过 wrangler login 或 CLOUDFLARE_API_TOKEN 完成认证。
如需使用 S3 API：在 R2 > Manage R2 API Tokens 下创建 R2 API 令牌。

主要能力

存储桶管理（Wrangler）

创建存储桶：npx wrangler r2 bucket create app-assets
在指定区域创建：npx wrangler r2 bucket create eu-uploads --location=eu
列出所有存储桶：npx wrangler r2 bucket list
删除空存储桶：npx wrangler r2 bucket delete old-bucket

对象操作（Wrangler）

上传单个文件：npx wrangler r2 object put app-assets/images/logo.png --file=./logo.png
带内容类型上传：npx wrangler r2 object put app-assets/data/report.json --file=./report.json --content-type="application/json"
下载对象：npx wrangler r2 object get app-assets/images/logo.png --file=./downloaded-logo.png
删除对象：npx wrangler r2 object delete app-assets/images/old-logo.png
查询对象元数据：npx wrangler r2 object head app-assets/images/logo.png

S3 兼容 API 访问

R2 支持 S3 API，现有工具（AWS CLI、boto3、s3cmd）可直接使用。生成 R2 API 令牌的步骤：进入 R2 > Manage R2 API Tokens > Create API token；选择权限（Object Read & Write 或 Object Read only）；尽量限定到特定存储桶；保存 Access Key ID 与 Secret Access Key。

AWS CLI 配置示例：

aws configure --profile r2
# Access Key ID: <your-r2-access-key>
# Secret Access Key: <your-r2-secret-key>
# Region: auto
# Output: json

export R2_ENDPOINT="https://<ACCOUNT_ID>.r2.cloudflarestorage.com"

aws s3 ls --endpoint-url=$R2_ENDPOINT --profile=r2

Python boto3 客户端示例：

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    aws_access_key_id="<R2_ACCESS_KEY>",
    aws_secret_access_key="<R2_SECRET_KEY>",
    region_name="auto",
)

s3.upload_file("./report.pdf", "app-assets", "reports/report.pdf")

url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "app-assets", "Key": "reports/report.pdf"},
    ExpiresIn=3600,
)

Worker 绑定

可将 R2 存储桶绑定到 Workers 或 Pages Functions，实现无需 API 令牌的服务端访问。wrangler.toml 配置示例：

name = "asset-worker"
main = "src/index.ts"
compatibility_date = "2024-09-01"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "app-assets"

[[r2_buckets]]
binding = "UPLOADS"
bucket_name = "user-uploads"

资料提供了完整的 Worker 示例，覆盖 GET 读取并返回文件（写入 httpMetadata、etag、cache-control）、PUT 上传（含 contentType 与 customMetadata）、DELETE 删除等操作。

在 Worker 中生成预签名 URL

资料示例使用 aws4fetch 的 AwsClient，通过环境变量 R2_ACCESS_KEY、R2_SECRET_KEY、R2_ACCOUNT_ID 对请求进行签名（signQuery: true），返回带签名的 URL。

公共存储桶访问

在 R2 > bucket > Settings > Public access 中启用，并可设置自定义域名（如 assets.example.com），对象通过 https://assets.example.com/<key> 访问。也可通过 r2.dev 子域启用（用于测试），URL 形如 https://pub-<hash>.r2.dev/<key>。

生命周期规则

可配置对象自动过期或转换。资料提供了通过 API 设置规则的示例，例如对 tmp/ 前缀在创建 7 天后删除、对 logs/ 前缀在创建 90 天后删除。也可通过控制台 R2 > bucket > Settings > Object lifecycle rules 配置。

CORS 配置

可通过 API 设置 CORS 策略以支持浏览器上传，示例允许来源 https://example.com，方法 GET、PUT、HEAD，允许头 Content-Type、Authorization，maxAgeSeconds 为 3600。

常见问题排查

资料列出以下症状与处理方式：

NoSuchBucket（S3 API）：端点或存储桶名错误，确认端点为 https://<ACCOUNT_ID>.r2.cloudflarestorage.com。
SignatureDoesNotMatch：密钥错误或端点不匹配，重新生成 R2 API 令牌，确保 region 为 auto。
上传成功但 GET 返回 404：键路径不匹配（前导斜杠），R2 键不应以 / 开头。
大文件上传缓慢：使用分段上传，配合 wrangler 的 --expected-size。
浏览器 CORS 错误：存储桶缺少 CORS 配置，为来源域添加 CORS 规则。
Worker 绑定返回 undefined：wrangler.toml 绑定名不匹配，确认与 Env 接口属性一致。
公共访问返回 403：未启用公共访问，在存储桶 Settings > Public access 中启用。

限制说明

资料未提供 R2 的计费价格、配额上限、具体区域覆盖范围以及除上述示例外的其他能力说明，这些内容暂未提供。

技能介绍

用途