写在前面

使用R2之前，你最好有个VISA卡：例如 招商全币种信用卡（后来了解到去闲鱼搜索”代绑“”虚拟卡“也可以成功通过），因为用存储虽然有免费额度，但是Cloudflare担心你可能用超，所以需要录入下支付方式才能使用R2；

项目使用Cloudflare R2支撑图片生成的存储

Cloudflare R2 亮点：免费量大

第 1 步：创建一个 Bucket

1. 打开 Cloudflare 控制台 并登录。
2. 在左侧找到 R2 Object Storage。
3. 点击 Create bucket，输入一个名称，例如 pixany-images，然后创建。
4. 把这个名称记下来，后面会填到项目的 Bucket Name（存储桶名称）。

第 2 步：给 Bucket 绑定图片访问域名

R2 的接口地址只给服务器上传和读取文件使用，浏览器显示图片时要用一个公开域名。因此这一步不要跳过。

1. 打开刚才创建的 Bucket。
2. 找到 Custom Domains（自定义域），点击添加域名。
3. 选择或输入你的子域名，例如 cdn.example.com，按 Cloudflare 提示完成绑定。
4. 绑定完成后，在浏览器打开的地址应类似 https://cdn.example.com。

只记录域名本身，不要在后面加 Bucket 名称、uploads 或最后的 /。

没有域名时，需要先购买一个域名并接入 Cloudflare；图片域名通常使用主域名下的子域名，例如 cdn.example.com。

第 3 步：创建上传用的 Access Key 和 Secret Key

这两个值是项目上传图片到 R2 的密码，只能放在管理员后台，不能发到前端、截图或代码仓库。

1. 回到 R2 页面，找到 Manage R2 API Tokens。
2. 点击 Create User API Token。
3. 给 Token 选择刚创建的 Bucket，并授予对象读取、写入权限。
4. 创建后复制并安全保存 Access Key ID 和 Secret Access Key；Secret Access Key 通常只会完整显示这一次。
5. 同一页还会显示 S3 API Endpoint，也复制下来。

选择 Create User API Token：

点击 Create User API Token：

Endpoint 一般长这样：

https://<你的 Cloudflare Account ID>.r2.cloudflarestorage.com

Endpoint 后面不要加 Bucket 名称。项目会自动拼上 Bucket 和文件路径。

第 4 步：填入 admin 后台

使用管理员账号打开 http://localhost:3000/admin/settings，点击 存储，找到 Cloudflare R2 / S3 卡片，按下面对应关系填写：

填写后点击页面的保存。保存后立即生效，不需要重启 pnpm dev。

这里的 Domain 很重要：项目会把图片地址拼成：

https://cdn.example.com/uploads/文件名

所以 Domain 必须是已经绑定到该 Bucket 的公开自定义域名，不能填写 S3 API Endpoint，也不要把 Bucket 名称填进去。

第 5 步：点击“测试”确认

1. 仍在“存储”页，点击 Cloudflare R2 / S3 卡片右上角的 测试。
2. 保持默认测试文件名，点击运行。
3. 成功时会显示 Key、Location 和 URL；点击 URL，能打开测试文本就表示配置完成。

测试会在 R2 中真实写入一个小文件，位置类似：

uploads/settings-test/时间戳-shipany-settings-test.txt

之后在项目中上传图片，文件会出现在同一个 Upload Path 下，也可以直接在 R2 Bucket 的对象列表中看到。

常见报错

• 提示 R2 未配置：确认 Access Key、Secret Key、Bucket Name 已填好并点击保存。
• 403 / Signature 错误：Endpoint 填错、Access Key 与 Secret Key 不是同一组，或 Token 没有目标 Bucket 的对象读取和写入权限。
• 测试上传成功，但打开 URL 看不到文件：检查 Custom Domain 是否已绑定成功；后台的 Domain 应是 https://cdn.example.com 这种地址，不能填 S3 API Endpoint。
• 不知道 Upload Path 填什么：直接留空即可，项目默认使用 uploads。