网页从一个域名读取阿里云 OSS 中的图片、字体或文件时,如果页面和资源的协议、域名或端口不同,浏览器就会按跨域请求处理。文件能直接打开,不代表网页里的 JavaScript 一定能读取它;浏览器还会检查响应中的跨域资源共享(CORS)信息。
阿里云 OSS 跨域配置的作用,是告诉浏览器哪些页面来源可以发起请求、哪些方法和请求头可以使用,以及前端能读取哪些响应头。它不负责授予文件访问权限:私有 Bucket 仍需通过签名 URL 或其他有效凭证访问,CORS 配置不会让未授权用户自动拿到文件。
配置前先确认请求经过哪里
排查时先在浏览器开发者工具的 Network 面板里找到失败请求,记下完整 URL、请求方法和 Origin。请求可能走 OSS 默认域名,也可能经过自定义域名、CDN、反向代理或重定向。浏览器检查的是最终收到的响应,因此源站规则正确,并不保证 CDN 返回的响应也带有正确的 CORS 响应头。
也要分清请求发生在哪里。服务器调用 OSS 通常不受浏览器同源策略限制;只有浏览器发起跨域请求,且页面需要读取响应时,CORS 才是主要排查方向。若是服务端请求报错,应继续检查服务端日志和访问凭证,别只改 Bucket 规则。
OSS CORS 规则需要匹配哪些内容
- 允许的来源(Allowed Origins):对应发起请求的页面来源,通常由协议、域名和端口组成。生产环境应填写实际站点地址;测试和生产域名可以分别管理,避免把测试来源长期留在生产规则里。
- 允许的方法(Allowed Methods):按业务需要设置 GET、HEAD、PUT 或 POST 等方法。前端直传文件常用 PUT 或 POST;浏览器需要先发 OPTIONS 预检时,也要检查预检是否能获得符合规则的响应。
- 允许的请求头(Allowed Headers):规则要覆盖请求实际使用的头,例如 Content-Type、Authorization 或自定义头。浏览器在预检请求的 Access-Control-Request-Headers 中会列出所需请求头,可用它核对配置。
- 暴露的响应头(Expose Headers):若前端 JavaScript 需要读取 ETag 等响应头,应将其加入暴露列表。没有配置时,响应头可能存在,但页面脚本仍无法读取。
- 预检缓存时间(Max Age):浏览器可在设定时间内复用预检结果,减少重复 OPTIONS 请求。修改规则后,旧的预检缓存可能暂时影响测试结果。
规则按实际需求收窄即可:不要为了让一次请求通过,就把所有来源、方法和请求头都开放。尤其是多个环境共用 Bucket 时,逐项确认哪些域名和请求方法确实需要访问。
在控制台添加跨域规则
- 登录阿里云控制台,进入对象存储 OSS,打开需要配置的 Bucket。
- 找到跨域设置(CORS),新增一条规则。
- 填写允许的来源、方法、请求头、暴露响应头和预检缓存时间,范围与业务请求保持一致。
- 保存后,从实际页面重新发起请求,在 Network 面板检查 OPTIONS 预检和后续请求的状态及响应头。
控制台入口或字段名称可能随版本调整,判断配置是否生效,不能只看规则是否保存。要确认浏览器发出的 Origin、请求方法和请求头能匹配规则,也要检查最终响应是否经过了正确的服务链路。
案例:前端直传文件时 OPTIONS 失败
某电商后台运行在 https://admin.example.com,商品图片存放在 OSS。前端先向后端获取签名 URL,再用 PUT 将文件直传到 Bucket。测试时,图片下载正常,上传却报跨域错误。检查请求后发现,浏览器在 PUT 前发送了 OPTIONS 预检,而 Bucket 规则只覆盖 GET,也没有放行上传请求实际使用的 Content-Type。
处理时,团队将管理站点的来源加入规则,开放业务需要的 PUT 方法,并按实际请求补齐允许的请求头。随后又检查了 CDN 和自定义域名链路,确认中间层没有移除 OSS 返回的 CORS 响应头。预检通过后,浏览器才继续发送 PUT,上传恢复正常。
这个场景里,签名 URL 和 CORS 解决的是两件事:签名用于验证请求是否有权限访问 OSS,CORS 用于决定浏览器是否允许页面完成跨域交互。两项条件都要满足,不能拿其中一个替代另一个。
常见错误及排查方法
Origin 和实际页面地址不一致
Origin 通常包含协议、域名和非默认端口。http 与 https 不同,带端口和不带端口也可能不匹配。不要凭印象填写来源,直接查看请求头中的 Origin,再与规则逐项核对。
只看 PUT 或 POST,漏查预检
请求使用 PUT,或带有自定义请求头时,浏览器可能先发送 OPTIONS。先检查这条预检请求的状态码和响应头;如果它没有通过,后续实际请求通常不会发出。此时只盯着 PUT 报错,容易把问题归到签名或文件内容上。
前端新增请求头后规则失效
加入 Authorization、自定义业务头,或更改 Content-Type 后,原有规则可能不再适用。查看预检请求里的 Access-Control-Request-Headers,确认浏览器要求允许哪些头,再据此调整规则。
把 CORS 当成文件权限
CORS 不是防止资源被下载的权限控制。资源不应公开时,应使用私有读权限和签名访问,并在服务端妥善管理凭证。需要携带 Cookie 或其他凭证时,也不要随意使用通配来源;来源和响应配置必须符合浏览器要求,并限制在业务所需范围内。
缓存或 CDN 让新规则看起来没生效
浏览器可能缓存预检结果,CDN 也可能缓存响应。可以用无痕窗口辅助验证,并分别对比 OSS 源站和 CDN 域名的响应头。如果源站正常、CDN 路径失败,就检查 CDN 的缓存策略、回源行为和响应头转发设置。
上线前检查
- 浏览器实际发送的 Origin 与允许来源匹配,协议、域名和端口都正确。
- 规则只开放业务需要的方法和请求头,前端直传场景已检查 OPTIONS 预检。
- 需要由 JavaScript 读取的响应头已加入暴露列表。
- 私有文件仍通过签名或其他授权方式访问,没有用 CORS 代替权限控制。
- 经 CDN 或自定义域名访问时,已核对浏览器最终收到的响应头。
阿里云 OSS 跨域排查可以从浏览器实际请求开始:先看 Origin 和 OPTIONS 预检,再核对请求头、响应头以及 CDN 等中间链路。确认具体是哪一项不匹配后再调整规则,通常比直接放宽权限更省事,也更稳妥。