跨源资源共享 (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 会返回 403 ExpiredRequest 响应。对于这种响应,R2 不会包含 CORS 响应头,因此浏览器 JavaScript 无法读取错误响应体。请在预签名 URL 过期前更新它;如果浏览器需要直接处理过期错误,请让请求经过应用程序服务器。
要启用基于浏览器的预签名 URL 访问:
-
向存储桶添加 CORS 策略,允许来自应用源站的请求。
-
将
AllowedMethods设置为与预签名 URL 执行的操作匹配,使用GET、PUT、HEAD和/或DELETE。 -
将
AllowedHeaders设置为包含客户端使用预签名 URL 时将发送的请求头,例如内容类型、校验和、缓存或自定义元数据的请求头。 -
(可选)设置
ExposeHeaders,允许 JavaScript 读取ETag等响应请求头,其中包含对象哈希,可用于验证上传。 -
(可选)设置
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-* 响应请求头。
-
在 Cloudflare 仪表板中,前往 R2 object storage(R2 对象存储) 页面。
前往 Overview(概览) ↗ -
从列表中找到并选择您的存储桶。
-
选择 Settings(设置)。
-
在 CORS Policy(CORS 策略) 下,选择 Add CORS policy(添加 CORS 策略)。
-
在 JSON 选项卡中,手动输入或复制粘贴策略到文本框。
-
完成后,选择 Save(保存)。
策略会显示在存储桶的 Settings(设置) 页面上。
您可以使用 Wrangler CLI 配置 CORS 规则。
- 创建包含 CORS 配置的 JSON 文件:
{
"rules": [
{
"allowed": {
"origins": ["https://example.com"],
"methods": ["GET"]
}
}
]
}- 将 CORS 策略应用到存储桶:
npx wrangler r2 bucket cors set <BUCKET_NAME> --file cors.json- 验证 CORS 策略已应用:
npx wrangler r2 bucket cors list <BUCKET_NAME>R2 CORS 策略中的以下字段映射到 HTTP 响应请求头。这些响应请求头仅在传入 HTTP 请求为有效 CORS 请求时返回。
| 字段名称 | 描述 | 示例 |
|---|---|---|
AllowedOrigins |
指定从浏览器请求存储桶中对象时 R2 设置的 Access-Control-Allow-Origin 请求头值。 |
若 www.test.com 上的网站需要访问 自定义域名 static.example.com 上的资源(例如字体、脚本),应将 https://www.test.com 设为 AllowedOrigin。 |
AllowedMethods |
指定从浏览器请求存储桶中对象时 R2 设置的 Access-Control-Allow-Methods 请求头值。 |
GET, POST, PUT |
AllowedHeaders |
指定从浏览器请求此存储桶中对象时 R2 设置的 Access-Control-Allow-Headers 请求头值。包含自定义请求头(例如 x-user-id)的跨源请求应将这些请求头指定为 AllowedHeaders。 |
x-requested-by, User-Agent |
ExposeHeaders |
指定可暴露给发起跨源请求的 JavaScript 并可访问的请求头。若需访问安全列表响应请求头 ↗以外的请求头(例如 Content-Encoding 或 cf-cache-status),须在此指定。 |
Content-Encoding, cf-cache-status, Date |
MaxAgeSeconds |
指定浏览器可缓存 CORS 预检响应的时长(秒)。即使指定最大值 (86400),浏览器也可能限制为 2 小时或更短。 | 3600 |
此示例为包含 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 响应头。R2 通过
OriginHTTP 请求头识别此类请求。请求头的值必须与你策略的AllowedOrigins字段中的某个来源匹配。没有Origin请求头的请求不会返回 CORS 响应头。 - CORS 策略中的
AllowedOrigins值必须是*,或基于 HTTP Origin 请求头值 ↗的有效模式。有效的Origin请求头 不 包含路径部分,只能包含scheme://host[:port](端口可选)。- 使用
*允许来自任意来源的请求。 - 来源模式最多可包含一个
*通配符。该通配符可以跨越句点。例如,https://*.example.com同时匹配https://api.example.com和https://a.b.example.com,但不匹配https://example.com。 - 不含通配符的来源值必须与请求的
Origin请求头完全匹配。 - 端口不能包含通配符。要允许多个 localhost 端口,请分别列出每个来源,例如
http://localhost:3000和http://localhost:5173。 - 有效的
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。