Cloudflare R2 CORS 配置完全指南

本文介绍如何在 Cloudflare R2 中配置 CORS（跨域资源共享），包括公共存储桶、预签名 URL 和自定义域名的 CORS 配置方法。

什么是 CORS

跨域资源共享（CORS）是一种标准化方法，用于防止域名 X 访问域名 Y 的资源。它通过在域名 Y 的 HTTP 响应中使用特殊头部，允许浏览器验证域名 Y 是否允许域名 X 访问这些资源。

虽然 CORS 可以帮助保护数据免受恶意网站攻击，但它也用于与存储桶中的对象交互和配置存储桶策略。

使用场景

当你从 Web 浏览器与存储桶交互时，有两种选择：

1. 设置公共存储桶

此选项使存储桶在 Internet 上可公开只读访问，意味着任何人都可以在其浏览器或其他地方请求和加载存储桶中的对象。如果你的存储桶包含公共博客中使用的图片，此选项是理想选择。

2. 预签名 URL

允许任何有权访问唯一 URL 的人在存储桶上执行特定操作。

前提条件

在配置 CORS 之前，你必须具备：

• 一个至少包含一个对象的 R2 存储桶
• 可用于访问对象的域名（也可以是 localhost）
• （可选）访问密钥（仅在创建预签名 URL 时需要）

公共存储桶使用 CORS

要使用公共存储桶的 CORS，请确保你的存储桶设置为允许公共访问。然后，向存储桶添加 CORS 策略以允许文件共享。

预签名 URL 使用 CORS

预签名 URL 允许临时访问以在存储桶上执行特定操作，而无需暴露凭证。虽然预签名 URL 处理身份验证，但从浏览器发出请求时仍需要配置 CORS。

当浏览器向不同源的预签名 URL 发出请求时，浏览器会强制执行 CORS。如果没有 CORS 策略，即使预签名 URL 本身有效，基于浏览器的上传和下载也会失败。

要启用基于浏览器的访问：

1. 向存储桶添加 CORS 策略，允许来自应用程序源的请求
2. 将 AllowedMethods 设置为与预签名 URL 执行的操作匹配，使用 GET、PUT、HEAD 和/或 DELETE
3. 将 AllowedHeaders 设置为包含客户端使用预签名 URL 时将发送的任何头部，例如内容类型、校验和、缓存或自定义元数据的头部
4. （可选）设置 ExposeHeaders 以允许 JavaScript 读取响应头部，如包含对象哈希的 ETag，可用于验证上传
5. （可选）设置 MaxAgeSeconds 以缓存预检响应并减少浏览器发出的预检请求数量

以下示例允许从 https://example.com 进行基于浏览器的上传，并带有 Content-Type 头部：

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

自定义域名使用 CORS

连接到具有 CORS 策略的 R2 存储桶的自定义域名会自动为跨域请求返回 CORS 响应头部。

跨域请求必须包含有效的 Origin 请求头部，例如 Origin: https://example.com。如果你直接测试或使用 curl 等命令行工具，除非请求中包含 Origin 请求头部，否则你不会看到 CORS Access-Control-* 响应头部。

缓存和 CORS 头部

如果你在使用自定义域名的存储桶上设置 CORS 策略，任何现有的缓存资源在缓存刷新之前不会反映 CORS 响应头部。在进行任何与 CORS 策略相关的更改后，使用缓存清除来清除该主机名的缓存。

从仪表板添加 CORS 策略

1. 在 Cloudflare 仪表板中，转到 R2 对象存储页面
2. 从列表中找到并选择你的存储桶
3. 选择 设置
4. 在 CORS 策略下，选择 添加 CORS 策略
5. 从 JSON 选项卡，手动输入或复制粘贴你的策略到文本框中
6. 完成后，选择 保存

你的策略将显示在存储桶的设置页面上。

通过 Wrangler CLI 添加 CORS 策略

你可以使用 Wrangler CLI 配置 CORS 规则：

1. 创建包含 CORS 配置的 JSON 文件：

{
  "rules": [
    {
      "allowed": {
        "origins": ["https://example.com"],
        "methods": ["GET"]
      }
    }
  ]
}

2. 将 CORS 策略应用到存储桶：

npx wrangler r2 bucket cors set <BUCKET_NAME> --file cors.json

3. 验证 CORS 策略是否已应用：

npx wrangler r2 bucket cors list <BUCKET_NAME>

响应头部

R2 CORS 策略中的以下字段映射到 HTTP 响应头部。这些响应头部仅在传入的 HTTP 请求是有效的 CORS 请求时返回。

示例

此示例显示为包含 Roboto-Light.ttf 对象（字体文件）的存储桶添加的 CORS 策略。

AllowedOrigins 指定正在使用的 Web 服务器，localhost:3000 是运行 Web 服务器的主机名。AllowedMethods 指定仅允许 GET 请求，可以读取存储桶中的对象。

[
  {
    "AllowedOrigins": ["http://localhost:3000"],
    "AllowedMethods": ["GET"]
  }
]

一般来说，确保设置了正确的 CORS 规则的一个好策略是查看被浏览器阻止的网络请求：

• 确保规则的 AllowedOrigins 包含发出请求的来源（如 http://localhost:3000 或 https://yourdomain.com）
• 确保规则的 AllowedMethods 包含被阻止请求的方法
• 确保规则的 AllowedHeaders 包含被阻止请求的头部

另请注意，CORS 规则传播在极少数情况下可能需要长达 30 秒。

常见问题

• 只有跨域请求才会包含 CORS 响应头部

  • 跨域请求由 Origin HTTP 请求头部的存在标识，Origin 的值表示由 CORS 策略的 AllowedOrigins 字段定义的有效允许来源
  • 没有 Origin HTTP 请求头部的请求不会返回任何 CORS 响应头部。来源值必须完全匹配

• AllowedOrigins 的值必须是有效的 HTTP Origin 头部值

  • 有效的 Origin 头部不包含路径组件，只能由 scheme://host[:port] 组成（其中端口是可选的）
  • 有效的 AllowedOrigins 值：https://static.example.com - 包含方案和主机。端口是可选的，由方案隐含
  • 无效的 AllowedOrigins 值：https://static.example.com/ 或 https://static.example.com/fonts/Calibri.woff2 - 错误地包含了路径组件

• 如果你需要在源页面上通过 JavaScript 访问特定的头部值

  • 例如在使用视频播放器时，确保正确设置 Access-Control-Expose-Headers 并包含 JavaScript 需要访问的头部，例如 Content-Length

原文链接: https://developers.cloudflare.com/r2/buckets/cors/
更新日期: 2025年12月12日