配置 CORS

跨源资源共享 (CORS) ↗ 是一种标准化方法，用于防止域 X 访问域 Y 的资源。它通过域 Y 的 HTTP 响应中的特殊请求头实现，允许浏览器验证域 Y 是否允许域 X 访问这些资源。

CORS 可在保护数据免受恶意网站侵害的同时，也用于与存储桶中的对象交互及配置存储桶策略。

从 Web 浏览器与存储桶交互时使用 CORS，您有两种选择：

将存储桶设为公开： 此选项使存储桶在 Internet 上只读可访问，即任何人都可以在浏览器或其他地方请求和加载存储桶中的对象。若存储桶包含公开博客使用的图片，此选项非常合适。

预签名 URL： 允许拥有唯一 URL 的任何人执行存储桶上的特定操作。

配置 CORS 前，您必须拥有：

• 至少包含一个对象的 R2 存储桶。若需创建存储桶，请参阅 创建公开存储桶。
• 用于访问对象的域名。也可以是 localhost。
• （可选）访问密钥。创建预签名 URL 时才需要访问密钥。

要在公开存储桶上使用 CORS，请确保存储桶已允许公开访问。

接下来，向存储桶添加 CORS 策略以允许共享文件。

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

当浏览器向不同源上的预签名 URL 发起请求时，浏览器会强制执行 CORS。若无 CORS 策略，使用预签名 URL 的浏览器上传和下载会失败，即使预签名 URL 本身有效。

要启用基于浏览器的预签名 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 策略的 R2 存储桶的自定义域名会自动为跨源请求 ↗返回 CORS 响应请求头。

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

1. 在 Cloudflare 仪表板中，前往 R2 object storage（R2 对象存储） 页面。

   Go to Overview ↗

2. 从列表中找到并选择您的存储桶。

3. 选择 Settings（设置）。

4. 在 CORS Policy（CORS 策略） 下，选择 Add CORS policy（添加 CORS 策略）。

5. 在 JSON 选项卡中，手动输入或复制粘贴策略到文本框。

6. 完成后，选择 Save（保存）。

策略会显示在存储桶的 Settings（设置） 页面上。

您可以使用 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 响应请求头。Origin 值必须完全匹配。
• CORS 策略中 AllowedOrigins 的值必须是有效的 HTTP Origin 请求头值 ↗。有效的 Origin 请求头不包含路径组件，只能由 scheme://host[:port] 组成（port 可选）。
  • 有效的 AllowedOrigins 值：https://static.example.com——包含 scheme 和 host。port 可选，由 scheme 隐含。
  • 无效的 AllowedOrigins 值：https://static.example.com/ 或 https://static.example.com/fonts/Calibri.woff2——错误地包含了路径组件。
• 若需通过 JavaScript 在源页面上访问特定请求头值（例如使用视频播放器时），请正确设置 Access-Control-Expose-Headers，并包含 JavaScript 需要访问的请求头，例如 Content-Length。