# Cloudflare R2 对象存储 **状态**：生产就绪 ✅ **最后更新**：2025-10-21 **依赖项**：cloudflare-worker-base（用于 Worker 设置） **最新版本**：wrangler@4.43.0、@cloudflare/workers-types@4.20251014.0、aws4fetch@1.0.20 ** ** ## 快速入门（5 分钟） ### 1\.创建 R2 存储桶 # 通过 Wrangler CLI（推荐） npx 牧马人 r2 存储桶创建我的存储桶 # 或通过 Cloudflare 仪表板 # https://dash.cloudflare.com → R2 对象存储 → 创建存储桶 **桶命名规则：** * 3-63个字符 * 仅限小写字母、数字、连字符 * 必须以字母或数字开头/结尾 * 在您的帐户内全球唯一 ### 2\.配置 R2 绑定添加到您的“wrangler.jsonc”： { “姓名”：“我的工人”， "main": "src/index.ts", “兼容性日期”：“2025-10-11”， “r2_buckets”：[ { "binding": "MY_BUCKET", // 在您的 Worker 中可用作 env.MY_BUCKET "bucket_name": "my-bucket", // 来自 wrangler r2 存储桶创建的名称 "preview_bucket_name": "my-bucket-preview" // 可选：用于开发的单独存储桶 } ] } **关键：** * `binding` 是您在代码中访问存储桶的方式 (`env.MY_BUCKET`) * `bucket_name` 是实际的 R2 存储桶名称 * `preview_bucket_name` 是可选的，但建议用于单独的开发/生产数据 ### 3\.基本上传/下载 // src/index.ts 从'hono'导入{Hono}；类型绑定 = { MY_BUCKET：R2Bucket； }; const app = new Hono<{ 绑定: 绑定 }>(); // 上传文件 app.put('/upload/:文件名', async (c) => { const 文件名 = c.req.param('文件名'); const body =等待c.req.arrayBuffer(); 尝试{ const 对象 = 等待 c.env.MY_BUCKET.put(文件名, 正文, { http元数据：{ contentType: c.req.header('内容类型') || '应用程序/八位字节流', }, }); 返回 c.json({ 成功：真实， key: 对象.key, 大小：对象.大小， etag：对象.etag， }); } catch（错误：任何）{ console.error('R2上传错误:', error.message); return c.json({ error: '上传失败' }, 500); } }); // 下载文件 app.get('/download/:文件名', async (c) => { const 文件名 = c.req.param('文件名'); 尝试{ const 对象 = 等待 c.env.MY_BUCKET.get(文件名); 如果（！对象）{ return c.json({ error: '找不到文件' }, 404); } 返回新的响应（对象.body，{ 标题：{ '内容类型'：object.httpMetadata?.contentType || '应用程序/八位字节流', 'ETag': 对象.httpEtag, '缓存控制'：object.httpMetadata？.cacheControl || '公共，最大年龄=3600'， }, }); } catch（错误：任何）{ console.error('R2 下载错误:', error.message); return c.json({ error: '下载失败' }, 500); } }); 导出默认应用程序； ### 4\.部署和测试 # 部署 npx 牧马人部署 # 测试上传 curl -X PUT https://my-worker.workers.dev/upload/test.txt \ -H“内容类型：文本/纯文本”\ -d“你好，R2！” # 测试下载卷曲 https://my-worker.workers.dev/download/test.txt ** ** ## R2 工人 API ### 类型定义 // 添加到 env.d.ts 或worker-configuration.d.ts 接口环境{ MY_BUCKET：R2Bucket； // ...其他绑定 } // 对于霍诺类型绑定 = { MY_BUCKET：R2Bucket； }; const app = new Hono<{ 绑定: 绑定 }>(); ### put() - 上传对象 **签名：** put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob, options?: R2PutOptions): Promise **基本用法：** // 从请求体上传等待 env.MY_BUCKET.put('path/to/file.txt', request.body); // 上传字符串等待 env.MY_BUCKET.put('config.json', JSON.stringify({ foo: 'bar' })); // 上传ArrayBuffer 等待 env.MY_BUCKET.put('image.png', 等待 file.arrayBuffer()); **带有元数据：** const object = wait env.MY_BUCKET.put('document.pdf', fileData, { http元数据：{ contentType: '应用程序/pdf', 内容语言：'en-US'， contentDisposition: '附件;文件名=“报告.pdf”', 内容编码：'gzip', 缓存控制：'公共，最大年龄= 86400'， }, 自定义元数据：{ 用户 ID: '12345', uploadDate: new Date().toISOString(), 版本：'1.0'， }, }); **有条件上传（防止覆盖）：** // 仅当文件不存在时才上传 const object = wait env.MY_BUCKET.put('file.txt', data, { 仅当：{ uploadedBefore: new Date('2020-01-01'), // R2 之前存在的任何日期 }, }); 如果（！对象）{ // 文件已存在，禁止上传 return c.json({ error: '文件已存在' }, 409); } // 仅当 etag 匹配时才上传（更新特定版本） const object = wait env.MY_BUCKET.put('file.txt', data, { 仅当：{ etag匹配：现有Etag， }, }); **带校验和：** // R2将验证校验和 const md5Hash =等待 crypto.subtle.digest('MD5', fileData); 等待 env.MY_BUCKET.put('file.txt', fileData, { md5：md5哈希值， }); ### get() - 下载对象 **签名：** 获取（键：字符串，选项？：R2GetOptions）：Promise **基本用法：** // 获取完整对象 const object = wait env.MY_BUCKET.get('file.txt'); 如果（！对象）{ return c.json({ 错误: '未找到' }, 404); } // 作为响应返回返回新的响应（对象.body，{ 标题：{ '内容类型'：object.httpMetadata?.contentType || '应用程序/八位字节流', 'ETag': 对象.httpEtag, }, }); **读取为不同的格式：** const object = wait env.MY_BUCKET.get('data.json'); 如果（对象）{ const text = await object.text(); // 作为字符串 const json = 等待 object.json(); // 作为 JSON 对象 const buffer =等待object.arrayBuffer(); // 作为数组缓冲区 const blob = await object.blob(); // 作为斑点 } **范围请求（部分下载）：** // 获取文件的前 1MB const object = wait env.MY_BUCKET.get('大文件.mp4', { 范围：{ 偏移量：0，长度：1024 * 1024 }， }); // 获取字节100-200 const object = wait env.MY_BUCKET.get('file.bin', { 范围：{偏移量：100，长度：100}， }); // 获取从offset到end的位置 const object = wait env.MY_BUCKET.get('file.bin', { 范围：{偏移量：1000}， }); **有条件下载：** // 仅当 etag 匹配时才下载 const object = wait env.MY_BUCKET.get('file.txt', { 仅当：{ etag匹配：cachedEtag， }, }); 如果（！对象）{ // Etag不匹配，文件被修改 return c.json({ error: '文件已更改' }, 412); } ### head() - 仅获取元数据 **签名：** 头（键：字符串）：Promise **用途：** // 获取对象元数据而不下载主体 const object = wait env.MY_BUCKET.head('file.txt'); 如果（对象）{ 控制台.log({ key: 对象.key, 大小：对象.大小， etag：对象.etag，已上传：对象.已上传， contentType: object.httpMetadata?.contentType, 自定义元数据：对象.自定义元数据， }); } **使用案例：** * 检查文件是否存在 * 下载前获取文件大小 * 检查最后修改日期 * 验证缓存的 etag ### delete() - 删除对象 **签名：** 删除（键：字符串|字符串[]）：Promise **单个删除：** // 删除单个对象等待 env.MY_BUCKET.delete('file.txt'); // 如果文件不存在则不会出错（幂等） **批量删除（最多 1000 个键）：** // 一次删除多个对象 const 要删除的键 = [ '旧文件-1.txt', '旧文件2.txt', '临时/缓存数据.json', ]; 等待 env.MY_BUCKET.delete(keysToDelete); // 比单独删除快得多 **确认删除：** app.delete('/files/:文件名', async (c) => { const 文件名 = c.req.param('文件名'); // 先检查是否存在 const 存在 = 等待 c.env.MY_BUCKET.head(文件名); 如果（！存在）{ return c.json({ error: '找不到文件' }, 404); } 等待 c.env.MY_BUCKET.delete(文件名); return c.json({ 成功: true, 删除: 文件名 }); }); ### list() - 列出对象 **签名：** 列表（选项？：R2ListOptions）：Promise **基本清单：** // 列出所有对象（最多 1000 个） const 列出=等待 env.MY_BUCKET.list(); 控制台.log({ 对象：listed.objects，//R2Object数组 truncated:listed.truncated, // 如果存在更多结果则为 true 光标：列出的.cursor，//用于分页 }); // 处理对象 for (listed.objects 的 const 对象) { console.log(`${object.key}: ${object.size} 字节`); } **分页：** app.get('/api/files', async (c) => { const 游标 = c.req.query('游标'); const 列出 = 等待 c.env.MY_BUCKET.list({ 限制：100，光标：光标||未定义， }); 返回 c.json({ 文件：listed.objects.map(obj => ({ 名称: obj.key, 大小：对象大小，已上传：obj.已上传， etag：obj.etag， }）），有更多：列出。截断， nextCursor：列出的.cursor， }); }); **前缀过滤（按目录列出）：** // 列出“images/”文件夹中的所有文件 const 图像 = 等待 env.MY_BUCKET.list({ 前缀：'图像/'， }); // 列出所有用户文件 const userFiles = 等待 env.MY_BUCKET.list({ 前缀：`users/${userId}/`, }); **分隔符（类似文件夹的列表）：** // 仅列出“uploads/”中的顶级项目 const 列出 = 等待 env.MY_BUCKET.list({ 前缀：'上传/'，分隔符：'/', }); console.log('文件：',列出的.objects); // 文件直接上传/ console.log('文件夹：',列出的.delimitedPrefixes); // 子文件夹，如 uploads/2024/ ** ** ## 分段上传对于大于 100MB 的文件或可断点续传的文件，请使用分段上传 API。 ### 何时使用分段上传 ✅ **在以下情况下使用多部分：** * 文件大小 > 100MB * 需要断点续传 * 想要并行上传 * 从浏览器/客户端上传 ❌ **在以下情况下不要使用多部分：** * 文件大小 < 5MB（开销不值得） * Worker内上传（直接使用put()） ### 基本分段上传流程 app.post('/api/upload/start', 异步 (c) => { const { 文件名 } = 等待 c.req.json(); // 创建分段上传 const multipart = 等待 c.env.MY_BUCKET.createMultipartUpload(文件名, { http元数据：{ contentType: '应用程序/八位字节流', }, }); 返回 c.json({ key: 多部分.key, uploadId: multipart.uploadId, }); }); app.put('/api/upload/part', async (c) => { const { key, uploadId, partNumber } = wait c.req.json(); const body =等待c.req.arrayBuffer(); // 恢复分段上传 const multipart = c.env.MY_BUCKET.resumeMultipartUpload(key, uploadId); // 上传一部分 const uploadedPart = wait multipart.uploadPart(partNumber, body); 返回 c.json({ 零件编号：上传零件.零件编号， etag：uploadedPart.etag， }); }); app.post('/api/upload/complete', async (c) => { const { key, uploadId, parts } = wait c.req.json(); // 恢复分段上传 const multipart = c.env.MY_BUCKET.resumeMultipartUpload(key, uploadId); // 完成上传 const object =等待multipart.complete(parts); 返回 c.json({ 成功：真实， key: 对象.key, 大小：对象.大小， etag：对象.etag， }); }); app.post('/api/upload/abort', 异步 (c) => { const { key, uploadId } = wait c.req.json(); const multipart = c.env.MY_BUCKET.resumeMultipartUpload(key, uploadId); 等待 multipart.abort(); 返回 c.json({ 成功: true }); }); ### 完整的分段上传示例 // Full Worker 实现分段上传 API 接口环境{ MY_BUCKET：R2Bucket； } 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { const url = 新 URL(request.url); const key = url.pathname.slice(1); const action = url.searchParams.get('action'); 开关（请求方法）{ 案例'POST'：{ 开关（动作）{ case 'mpu-create': { // 创建分段上传 const multipart =等待 env.MY_BUCKET.createMultipartUpload(key); 返回 Response.json({ key: 多部分.key, uploadId: multipart.uploadId, }); } case 'mpu-complete': { // 完成分段上传 const uploadId = url.searchParams.get('uploadId')!; const multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId); const parts =等待request.json(); const object =等待multipart.complete(parts); 返回 Response.json({ key: 对象.key, etag：对象.etag，大小：对象.大小， }); } 默认： return new Response(`未知操作：${action}`, { status: 400 }); } } 案例“放置”：{ 开关（动作）{ case 'mpu-uploadpart': { // 上传一部分 const uploadId = url.searchParams.get('uploadId')!; const partNumber = parseInt(url.searchParams.get('partNumber')!); const multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId); const uploadedPart = wait multipart.uploadPart(partNumber, request.body!); 返回 Response.json({ 零件编号：上传零件.零件编号， etag：uploadedPart.etag， }); } 默认： return new Response(`未知操作：${action}`, { status: 400 }); } } 案例“删除”：{ 开关（动作）{ case 'mpu-abort': { // 中止分段上传 const uploadId = url.searchParams.get('uploadId')!; const multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId); 等待 multipart.abort(); 返回新的响应（null，{状态：204}）； } 默认： return new Response(`未知操作：${action}`, { status: 400 }); } } 默认： return new Response('方法不允许', { status: 405 }); } }, } 满足 ExportedHandler; ** ** ## 预签名 URL 预签名 URL 允许客户端直接向 R2 上传/下载对象，而无需通过您的 Worker。 ### 何时使用预签名 URL ✅ **在以下情况下使用预签名 URL：** * 客户端直接上传到R2（节省Worker带宽） * 临时访问私有对象 * 分享有期限的下载链接 * 避免 Worker 请求大小限制 ❌ **在以下情况下不要使用预签名 URL：** * 您需要处理/验证上传 * 文件已经公开 * 使用自定义域（预签名 URL 仅适用于 R2 端点） ### 使用 aws4fetch 生成预签名 URL npm 安装 aws4fetch 从'aws4fetch'导入{AwsClient}；接口环境{ R2_ACCESS_KEY_ID：字符串； R2_SECRET_ACCESS_KEY：字符串； ACCOUNT_ID：字符串； MY_BUCKET：R2Bucket； } const app = new Hono<{ 绑定: Env }>(); app.post('/api/presigned-upload', async (c) => { const { 文件名 } = 等待 c.req.json(); // 为 R2 创建 AWS 客户端 const r2Client = 新 AwsClient({ accessKeyId：c.env.R2_ACCESS_KEY_ID，秘密访问密钥：c.env.R2_SECRET_ACCESS_KEY， }); const BucketName = '我的存储桶'; const accountId = c.env.ACCOUNT_ID; 常量 url = 新 URL( `https://${bucketName}.${accountId}.r2.cloudflarestorage.com/${filename}` ）； // 设置过期时间（1小时） url.searchParams.set('X-Amz-Expires', '3600'); // 对 PUT 的 URL 进行签名 const 签名 = 等待 r2Client.sign( 新请求（url，{方法：'PUT'}）， { aws: { signQuery: true } } ）；返回 c.json({ uploadUrl: 签名.url, 过期时间：3600， }); }); app.post('/api/presigned-download', async (c) => { const { 文件名 } = 等待 c.req.json(); const r2Client = 新 AwsClient({ accessKeyId：c.env.R2_ACCESS_KEY_ID，秘密访问密钥：c.env.R2_SECRET_ACCESS_KEY， }); const BucketName = '我的存储桶'; const accountId = c.env.ACCOUNT_ID; 常量 url = 新 URL( `https://${bucketName}.${accountId}.r2.cloudflarestorage.com/${filename}` ）； url.searchParams.set('X-Amz-Expires', '3600'); const 签名 = 等待 r2Client.sign( 新请求(url, { 方法: 'GET' }), { aws: { signQuery: true } } ）；返回 c.json({ 下载网址：签名的.url，过期时间：3600， }); }); ### 使用预签名 URL 进行客户端上传 // 1. 从您的 Worker 获取预签名 URL const 响应 = 等待 fetch('https://my-worker.workers.dev/api/presigned-upload', { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ 文件名: 'photo.jpg' }), }); const { uploadUrl } = 等待响应.json(); // 2. 直接上传文件到R2 const file = document.querySelector('input[type="file"]').files[0]; 等待获取（uploadUrl，{ 方法：'放置'，正文：文件，标题：{ '内容类型'：文件类型， }, }); ### 预签名 URL 安全 **关键：** * ❌ **绝不** 在客户端代码中公开 R2 访问密钥 * ✅ **始终** 在服务器端生成预签名 URL * ✅ **始终** 设置适当的到期时间（通常为 1-24 小时） * ✅ **考虑**在生成 URL 之前添加身份验证 * ✅ **考虑** 速率限制预签名 URL 生成 // 带有身份验证检查的示例 app.post('/api/presigned-upload', async (c) => { // 验证用户是否已通过身份验证 const authHeader = c.req.header('授权'); 如果（！authHeader）{ return c.json({ error: '未经授权' }, 401); } // 验证用户是否有权限 const userId = 等待 verifyToken(authHeader); if (!userId) { return c.json({ error: '无效令牌' }, 401); } // 只允许上传到用户自己的文件夹 const { 文件名 } = 等待 c.req.json(); const key = `users/${userId}/${filename}`; // 生成预签名 URL... }); ** ** ## CORS 配置配置 CORS 以允许浏览器向您的 R2 存储桶发出请求。 ### 公共存储桶 CORS { “CORSR规则”：[ { “AllowedOrigins”：[“https://example.com”]， “允许的方法”：[“GET”，“HEAD”]， “AllowedHeaders”：[“*”]， “最大年龄秒”：3600 } ] } ### 允许所有来源（公共资产） { “CORSR规则”：[ { “允许的来源”：[“*”]， “允许的方法”：[“GET”，“HEAD”]， “AllowedHeaders”：[“范围”]， “最大年龄秒”：3600 } ] } ### 使用 CORS 上传 { “CORSR规则”：[ { “AllowedOrigins”：[“https://app.example.com”]， “允许的方法”：[“GET”，“PUT”，“POST”，“DELETE”，“HEAD”]， “允许的标头”：[ “内容类型”， “内容-MD5”， “x-amz-元-*” ], "ExposeHeaders": ["ETag"], “最大年龄秒”：3600 } ] } ### 通过仪表板应用 CORS 1. 转到 Cloudflare 仪表板 → R2 2. 选择您的存储桶 3. 转到“设置”选项卡 4. 在 CORS 策略下 → 添加 CORS 策略 5.粘贴JSON配置 6. 保存 ### 预签名 URL 的 CORS 当使用预签名 URL 时，CORS 由 R2 直接处理。在存储桶上配置 CORS，而不是在您的 Worker 中。 ** ** ## HTTP 元数据 ### 内容类型 // 设置上传内容类型等待 env.MY_BUCKET.put('image.jpg', imageData, { http元数据：{ 内容类型：'图像/jpeg'， }, }); // 下载时会在 Content-Type header 中返回 ### 缓存控制 // 设置缓存头等待 env.MY_BUCKET.put('static/logo.png', logoData, { http元数据：{ 内容类型：'图像/png'， cacheControl: '公共，最大年龄=31536000，不可变', }, }); // 对于经常更新的内容等待 env.MY_BUCKET.put('api/data.json', jsonData, { http元数据：{ 内容类型：'应用程序/json'， cacheControl: 'public, max-age=60, 必须重新验证', }, }); ### 内容处置 // 使用特定文件名强制下载等待 env.MY_BUCKET.put('report.pdf', pdfData, { http元数据：{ contentType: '应用程序/pdf', contentDisposition: '附件;文件名=“每月报告.pdf”', }, }); // 内嵌显示等待 env.MY_BUCKET.put('image.jpg', imageData, { http元数据：{ 内容类型：'图像/jpeg'， contentDisposition: '内联', }, }); ### 内容编码 // 表示gzip压缩等待 env.MY_BUCKET.put('data.json.gz', gzippedData, { http元数据：{ 内容类型：'应用程序/json'，内容编码：'gzip', }, }); ** ** ## 自定义元数据使用对象存储任意键值元数据。 ### 设置自定义元数据等待 env.MY_BUCKET.put('文档.pdf', pdfData, { 自定义元数据：{ 用户 ID: '12345', 部门：“工程”， uploadDate: new Date().toISOString(), 版本：'1.0'，批准：“真实”， }, }); ### 读取自定义元数据 const object = wait env.MY_BUCKET.head('document.pdf'); 如果（对象）{ console.log(object.customMetadata); // { // 用户ID: '12345', // 部门: '工程', // 上传日期: '2025-10-21T10:00:00.000Z', // 版本: '1.0', // 批准: 'true' // } } ### 限制 * 所有自定义元数据的最大总大小为 2KB * 键和值必须是字符串 * 按键不区分大小写 * 密钥数量无限制（总计2KB以内） ** ** ## 错误处理 ### 常见 R2 错误尝试{ 等待 env.MY_BUCKET.put(key, data); } catch（错误：任何）{ const 消息=错误.消息； if (message.includes('R2_ERROR')) { // 通用 R2 错误 } else if (message.includes('超过')) { // 超出配额 } else if (message.includes('前提条件')) { // 条件操作失败 } else if (message.includes('multipart')) { // 分段上传错误 } console.error('R2 错误：', message); return c.json({ error: '存储操作失败' }, 500); } ### 重试逻辑异步函数 r2WithRetry( 操作： () => Promise, 最大重试次数 = 3 ): 承诺 { for (让尝试 = 0;尝试 < maxRetries;尝试++) { 尝试{ 返回等待操作（）； } catch（错误：任何）{ const 消息=错误.消息； // 发生暂时性错误时重试 const 可重试 = message.includes('网络') || message.includes('超时') || message.includes('暂时不可用'); if (!isRetryable || attempts === maxRetries - 1) { 抛出错误； } // 指数退避 const 延迟 = Math.min(1000 * Math.pow(2, 尝试), 5000); 等待新的 Promise(解决 => setTimeout(解决, 延迟)); } } throw new Error('重试逻辑失败'); } // 用法 const 对象 = 等待 r2WithRetry(() => env.MY_BUCKET.get('重要文件.txt') ）； ** ** ## 性能优化 ### 批量操作 // ❌不要：逐个删除文件 for (filesToDelete 的常量文件) { 等待 env.MY_BUCKET.delete(文件); } // ✅ DO：批量删除（最多 1000 个键）等待 env.MY_BUCKET.delete(filesToDelete); ### 大文件的范围请求 // 仅下载大视频的前 10MB const object = wait env.MY_BUCKET.get('video.mp4', { 范围：{ 偏移量：0，长度：10 * 1024 * 1024 }， }); // 返回范围给客户端返回新的响应（对象.body，{ status: 206, // 部分内容标题：{ '内容类型': '视频/mp4', '内容范围': `字节 0-${10 * 1024 * 1024 - 1}/${object.size}`, }, }); ### 缓存标头 // 不可变资产（散列文件名）等待 env.MY_BUCKET.put('static/app.abc123.js', jsData, { http元数据：{ contentType: '应用程序/javascript', cacheControl: '公共，最大年龄=31536000，不可变', }, }); // 动态内容等待 env.MY_BUCKET.put('api/latest.json', jsonData, { http元数据：{ 内容类型：'应用程序/json'， cacheControl: 'public, max-age=60, stale-while-revalidate=300', }, }); ### 数据完整性校验和 // 计算MD5校验和 const md5Hash =等待 crypto.subtle.digest('MD5', fileData); // R2 将验证上传时的校验和等待 env.MY_BUCKET.put('重要的.dat', fileData, { md5：md5哈希值， }); // 如果校验和不匹配，则上传失败 ** ** ## 最佳实践总结 ### ✅ 始终这样做： 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. **切勿对存储桶名称进行硬编码**（使用绑定） ** ** ## 已预防的已知问题问题 |描述 |如何避免 ---|---|--- **浏览器中的 CORS 错误** |由于缺少 CORS 策略，浏览器无法上传/下载 |浏览器访问前在存储桶设置中配置 CORS **文件下载为二进制** |缺少内容类型导致浏览器下载文件而不是显示 |上传时始终设置“httpMetadata.contentType” **预签名 URL 过期** | URL永不过期，存在安全风险 |始终设置“X-Amz-Expires”（通常为 1-24 小时） **分段上传限制** |零件超过 100MB 或 >10,000 个零件 |保留部分 5MB-100MB，每次上传最多 10,000 个部分 **批量删除限制** |尝试删除 >1000 个密钥失败 | Chunk 删除为 1000 个批次 **自定义元数据溢出** |元数据超过 2KB 限制 |将自定义元数据总计控制在 2KB 以下 ** ** ## Wrangler 命令参考 # 存储桶管理牧马人 r2 存储桶创建牧马人 R2 遗愿清单牧马人 r2 存储桶删除 # 对象管理牧马人 r2 对象 put / --file= 牧马人 r2 对象 get / --file= 牧马人 r2 对象删除 / # 列出对象牧马人 r2 对象列表牧马人 r2 对象列表 --prefix="folder/" ** ** ## 官方文档 * **R2 概述**： * **开始** ： * **Workers API** ： * **分段上传** : * **预签名 URL** ： * **CORS 配置**： * **公共存储桶**： ** ** **准备好用 R2 存储！** 🚀

Cloudflare R2

包含技能