S3存储的CORS跨域要怎么配置

一、结论

通过在S3兼容的对象存储桶的权限配置中添加自定义CORS规则，明确指定允许的请求来源、请求方法、请求头、暴露响应头和缓存时间，保存后等待规则生效即可实现跨域资源访问，整个过程无需修改业务代码，仅在存储侧操作即可完成配置。

二、准备工作

1. 拥有S3兼容对象存储服务的有效账号，例如AWS S3或七彩云对象存储账号；

2. 账号具备目标存储桶的配置管理权限（至少需要s3:PutBucketCORS和s3:GetBucketCORS权限，普通只读账号无法修改配置）；

3. 提前梳理好业务需要的跨域规则参数：包括允许跨域访问的业务域名、需要支持的HTTP请求方法、前端请求会携带的自定义请求头、前端需要读取的自定义响应头，以及预检请求的缓存时长；

4. 若使用控制台操作，只需准备Chrome、Edge等主流现代浏览器；若使用命令行批量操作，需提前安装配置好AWS CLI工具。

三、操作步骤

3.1 控制台可视化操作（推荐新手使用）

1. 登录对应对象存储服务的控制台，进入目标存储桶的配置页面：

• 若使用AWS S3：登录AWS控制台后进入S3服务页，在存储桶列表中点击目标桶名称，切换到「权限」标签页，下拉找到「跨源资源共享(CORS)」板块，点击「编辑」按钮进入配置页；
• 若使用七彩云对象存储：登录控制台后在左侧导航栏选择「对象存储」-「存储桶列表」，点击目标桶名称进入详情页，在左侧「权限配置」分类下选择「CORS跨域设置」，点击「新增规则」按钮即可开始配置。

2. 逐条填写CORS规则参数，每个参数的填写要求如下：

• 允许的来源（AllowedOrigins）：填写需要允许跨域访问的业务域名，必须带http://或https://前缀，不需要加路径后缀，例如https://www.example.com；
• 允许的请求方法（AllowedMethods）：勾选业务实际用到的HTTP方法，常用的包括GET（读取资源）、POST（提交表单）、PUT（上传文件）、DELETE（删除资源）、HEAD（检测资源存在）；
• 允许的请求头（AllowedHeaders）：填写前端请求会携带的自定义头，例如Content-Type、x-amz-meta-token等，不确定的情况下可以临时填*允许所有请求头；
• 暴露的响应头（ExposeHeaders）：填写前端JS需要读取的自定义响应头，例如ETag、Content-Length、x-amz-meta-custom等，浏览器默认只暴露6种基础响应头，未填写的自定义头前端无法读取；
• Max-Age缓存时间：填写预检请求的缓存时长，单位为秒，建议填写86400（即1天），可以减少重复的OPTIONS预检请求，提升访问速度。

3. 保存规则并验证生效：

• 所有参数填写完成后点击「保存」按钮，等待1-5分钟规则全局生效；
• 验证方式：打开业务页面按F12打开开发者工具，切换到「网络」标签页，触发跨域请求，若请求状态码为200且没有CORS Missing Allow Origin类报错即为配置成功；也可以用curl命令模拟预检请求验证：curl -H "Origin: 你的业务域名" -H "Access-Control-Request-Method: GET" -X OPTIONS 你的存储桶资源地址，若返回头中包含Access-Control-Allow-Origin字段且值为你的业务域名即为配置正确。

3.2 命令行操作（适合批量配置场景）

1. 打开终端执行aws configure，按提示输入AccessKey、SecretKey、桶所在区域、默认输出格式，完成AWS CLI的初始化配置；

2. 本地新建cors.json文件，将梳理好的CORS规则按JSON格式写入文件；

3. 执行配置命令：aws s3api put-bucket-cors --bucket 你的桶名 --cors-configuration file://cors.json --endpoint-url 你的存储服务endpoint，若使用七彩云对象存储，endpoint可以在桶详情页的「基础信息」板块直接复制；

4. 执行验证命令：aws s3api get-bucket-cors --bucket 你的桶名 --endpoint-url 你的存储服务endpoint，若返回你填写的CORS规则即为配置成功。

四、常见错误

• endpoint填写错误：使用非AWS的S3兼容服务时，误填AWS官方endpoint导致配置请求失败，例如使用七彩云对象存储时需要填写控制台提供的专属endpoint，不能直接用s3.us-east-1.amazonaws.com；
• region错误：命令行配置的区域和桶实际所在区域不一致，导致请求路由错误返回400；
• 权限不足：当前账号没有存储桶的CORS配置权限，保存规则时返回403拒绝访问，需要联系管理员给账号开通对应桶的配置权限；
• 规则匹配顺序错误：S3的CORS规则是按从上到下的顺序匹配，命中第一条符合条件的规则就会停止匹配，如果前面的规则范围比后面的小，会导致后面的规则无法生效；
• 来源填写不规范：允许的来源漏加http:///https://前缀，或者末尾多加了斜杠，导致和实际请求的Origin不匹配，触发跨域报错；
• 自定义请求头未放行：前端请求携带了自定义头，但CORS规则的「允许的请求头」中没有添加对应头名称，导致预检请求被拒绝。

五、示例说明

以下是电商业务的常用CORS规则示例：业务前端部署在https://shop.example.com，需要从对象存储读取图片、上传用户头像、下载订单凭证，对应的CORS规则JSON如下：

```json

[

{

"AllowedOrigins": ["https://shop.example.com", "https://admin.example.com"],

"AllowedMethods": ["GET", "POST", "PUT", "HEAD"],

"AllowedHeaders": ["Content-Type", "x-amz-meta-user-token"],

"ExposeHeaders": ["ETag", "Content-Length", "x-amz-meta-file-md5"],

"MaxAgeSeconds": 86400

}

]

```

该规则的含义是：允许电商前端和管理后台两个域名跨域访问，支持读取、上传、检测资源的请求，允许携带Content-Type和自定义的用户鉴权头，前端可以读取文件MD5、ETag等自定义响应头，预检请求缓存1天。

六、更简单的方案

如果不想处理AWS S3复杂的权限策略和区域配置，可以选择兼容S3 API的对象存储服务简化配置流程，例如七彩云对象存储，其天生完全兼容S3的所有API和CORS配置语法，已经使用S3 SDK开发的业务不需要修改任何代码，只需要将endpoint和密钥替换为七彩云的参数即可无缝迁移。同时七彩云对象存储提供可视化的CORS规则配置界面，支持直接点选请求方法、自动校验域名格式，还预设了静态站点、文件上传等常用场景的CORS模板，新手直接套用即可完成配置，无需手动编写JSON规则，配置后1分钟内即可全局生效。

七、FAQ

1. CORS配置完成后多久生效？

绝大多数S3兼容对象存储的CORS规则生效时间为1-5分钟，七彩云对象存储的规则生效时间为1分钟以内。如果配置后依然出现跨域报错，建议先清除浏览器缓存或者使用无痕模式测试，避免本地缓存的旧规则影响验证结果。

2. 能不能同时允许多个域名或者泛域名跨域？

可以，在AllowedOrigins数组中添加多个域名条目即可，例如["https://a.example.com", "https://b.example.com"]；也支持使用通配符匹配二级域名，例如["https://*.example.com"]，可以匹配所有example.com的二级域名。

3. 生产环境可以用*作为允许的来源吗？

不建议，使用*作为允许来源会放行所有域名的跨域请求，可能导致存储资源被恶意站点盗刷，存在安全风险。生产环境建议只填写实际用到的业务域名，最小化权限范围。

4. 为什么OPTIONS预检请求返回403错误？

通常是因为CORS规则没有匹配到请求的Origin或者请求方法，首先检查允许的来源是否和请求头中的Origin完全一致，有没有漏写协议前缀或者多写路径；其次检查请求使用的HTTP方法是否在允许的请求方法列表中。

八、总结

S3存储的CORS跨域配置整体流程可以总结为：梳理业务跨域规则参数→登录存储控制台进入目标桶的CORS配置页→填写规则保存→验证生效。新手首次配置时建议优先选择可视化操作界面，避免手动编写JSON出现格式错误，也可以使用七彩云对象存储等简化版S3兼容服务，套用预设模板快速完成配置。配置完成后一定要用实际业务场景做全量测试，覆盖所有用到的请求方法和自定义头，避免上线后出现跨域异常影响业务运行。如果需要多环境测试，可以在规则中添加测试环境的域名，验证通过后再调整为生产环境的规则。