操作背景
操作背景
跨域资源共享（Cross-Origin Resource Sharing，CORS）用于解决前后端域名均通过网关代理时出现的跨域访问问题。当浏览器发起跨域请求时，会在请求头中携带 Origin，并要求服务端返回匹配的 Access-Control-Allow-Origin 响应头；若二者不匹配，浏览器将丢弃响应，导致前端功能异常。
TSF 云原生智能网关支持服务级和路由级两个层级的 CORS 策略，二者使用相同的配置项，区别在于生效范围。本文分别介绍两个层级 CORS 策略的配置方式。
说明：
当同一路由同时存在服务级与路由级 CORS 策略时，路由级策略优先于服务级策略生效（遵循插件作用域优先级：路由级 > 服务级）。建议按需选择其一配置，避免两级策略取值不一致导致的排查困难。
前提条件
已购买网关实例，详情请参见 新建网关。
服务级 CORS
服务级 CORS 策略对服务下所有路由均生效，如需对路由配置 CORS 策略，您可以前往路由管理页配置。
步骤1：配置 CORS 策略
1. 登录 TSF 控制台，在左侧导航栏单击云原生网关 > 实例管理，进入实例列表页面。
2. 单击实例 ID/名称进入实例详情页面。
3. 单击服务路由，选择服务页签，单击服务名称，进入服务详情页面。
4. 在服务详情页面选择 CORS 策略页签，在服务级 CORS 区域单击立即配置，在新建 CORS 策略弹窗中配置以下参数：
参数 | 是否必选 | 说明 |
是否启用 | 是 | 开启后，CORS 策略将会生效。 |
允许的源地址 origins | 否 | 允许跨域访问的源地址，对应 Access-Control-Allow-Origin 响应头。多个值用英文逗号分隔，使用 * 表示允许所有源地址；不填写时允许所有来源。取值需包含协议（http/https），支持精确域名与正则表达式，origins 字段配置格式详见下方说明。 |
允许的 HTTP 方法 | 否 | 允许的跨域请求方法，对应 Access-Control-Allow-Methods 响应头。可勾选 GET、HEAD、PUT、PATCH、POST、DELETE、OPTIONS、TRACE、CONNECT。未指定时放通全部方法。 |
允许的请求头 | 否 | 允许客户端携带的请求头，对应 Access-Control-Allow-Headers 响应头。支持下拉选择预置选项（Authorization、X-Requested-With、User-Agent、Cache-Control、Content-Length、Keep-Alive）或自定义输入。 |
暴露的响应头 | 否 | 允许浏览器脚本访问的响应头，对应 Access-Control-Expose-Headers 响应头。支持下拉选择预置选项（Authorization、Content-Disposition、Content-Encoding）或自定义输入。 |
预检请求缓存时间 | 否 | 高级配置项。预检请求结果的缓存时间，单位为秒，对应 Access-Control-Max-Age 响应头。 |
允许凭证 | 否 | 高级配置项。开启后允许跨域请求携带凭证信息（Cookie 等），返回 Access-Control-Allow-Credentials: true。默认关闭。 |
预检请求处理 | 否 | 高级配置项。开启后将 OPTIONS 预检请求传递到上游服务处理；关闭时由网关直接响应预检请求。默认关闭。 |
说明：
1.
允许的源地址 origins
中的每个值必须为 * 或合法的正则表达式，多个值之间用英文逗号分隔。系统按取值内容自动判定匹配方式：格式 | 示例 | 说明 |
精确域名 | https://app.example.com | 当取值仅包含字母、数字及 . : / - 时，按字面精确匹配（此时 . 为普通字符，不作通配）。需包含协议与端口（如有）。 |
通配符 | * | 作为唯一值填写，或源地址完全不填写时，允许所有来源访问。不建议与开启允许凭证同时使用。 |
正则表达式 | https://.*\\.example\\.com | 当取值包含上述字符集之外的字符（如 *、\\、()）时，按 PCRE 正则匹配。上例可匹配 example.com 的所有子域名。 |
若需匹配某一主域名下的全部子域名，应使用正则表达式（如 https://.*\\.example\\.com），而非 https://*.example.com。后者中的 * 在 PCRE 语法中是作用于前一字符的量词，无法表达“任意子域名”的语义。系统会对正则表达式自动进行锚定（末尾补 $）。
2. 请勿在允许的源地址 origins 等字段的值末尾输入多余的空格。值末尾的空格会被作为源地址字符串的一部分参与匹配，导致来源无法命中，是跨域配置失败的常见原因。
3. 开启允许凭证时，若允许的源地址 origins 配置为 *，网关不会返回 Access-Control-Allow-Origin: *（依据 CORS 规范，Access-Control-Allow-Credentials: true 不能与 * 同时使用），而是回显请求实际携带的 Origin 值。此时相当于对所有来源放通并允许携带凭证，存在安全风险，建议在源地址中明确指定具体来源。
5. 单击确定，完成策略创建。
步骤2：验证策略是否生效
从已配置的前端源地址（例如 https://app.example.com）向网关代理的后端接口发起跨域请求，查看响应头中是否返回与请求 Origin 匹配的 Access-Control-Allow-Origin。若匹配，则跨域配置生效；若响应缺少该头或取值不匹配，请参见 常见问题排查。
路由级 CORS
路由级 CORS 策略仅对本路由生效，如需配置服务级 CORS 策略，您可以前往服务级 CORS 策略页配置。
步骤1：配置 CORS 策略
1. 登录 TSF 控制台，在左侧导航栏单击云原生网关 > 实例管理，进入实例列表页面。
2. 单击实例 ID/名称进入实例详情页。
3. 单击服务路由，在路由页签，单击路由名称进入路由详情页面。
4. 在路由管理页签，选择 CORS 策略页签，进入路由级 CORS 策略配置页面，单击立即配置。
参数 | 是否必选 | 说明 |
是否启用 | 是 | 开启后，CORS 策略将会生效。 |
允许的源地址 origins | 否 | 允许跨域访问的源地址，对应 Access-Control-Allow-Origin 响应头。多个值用英文逗号分隔，使用 * 表示允许所有源地址；不填写时允许所有来源。取值需包含协议（http/https），支持精确域名与正则表达式，origins 字段配置格式同上方说明。 |
允许的 HTTP 方法 | 否 | 允许的跨域请求方法，对应 Access-Control-Allow-Methods 响应头。可勾选 GET、HEAD、PUT、PATCH、POST、DELETE、OPTIONS、TRACE、CONNECT。未指定时放通全部方法。 |
允许的请求头 | 否 | 允许客户端携带的请求头，对应 Access-Control-Allow-Headers 响应头。支持下拉选择预置选项（Authorization、X-Requested-With、User-Agent、Cache-Control、Content-Length、Keep-Alive）或自定义输入。 |
暴露的响应头 | 否 | 允许浏览器脚本访问的响应头，对应 Access-Control-Expose-Headers 响应头。支持下拉选择预置选项（Authorization、Content-Disposition、Content-Encoding）或自定义输入。 |
预检请求缓存时间 | 否 | 高级配置项。预检请求结果的缓存时间，单位为秒，对应 Access-Control-Max-Age 响应头。 |
允许凭证 | 否 | 高级配置项。开启后允许跨域请求携带凭证信息（Cookie 等），返回 Access-Control-Allow-Credentials: true。默认关闭。 |
预检请求处理 | 否 | 高级配置项。开启后将 OPTIONS 预检请求传递到上游服务处理；关闭时由网关直接响应预检请求。默认关闭。 |
5. 单击确定，完成策略创建。
步骤2：验证策略是否生效
从已配置的前端源地址向网关代理的后端接口发起跨域请求，查看响应头中是否返回与请求 Origin 匹配的 Access-Control-Allow-Origin。若匹配，则跨域配置生效；若响应缺少该头或取值不匹配，请参见 常见问题排查。
常见问题排查
按照文档完成配置后仍出现跨域问题时，可参照以下方向排查：
1. 检查源地址末尾是否存在多余空格：允许的源地址 origins 等字段的值末尾若含空格，会导致字符串匹配失败。请逐一核对并删除多余空格后重新保存。
2. 验证正则表达式是否正确：确认源地址中的正则表达式能够匹配实际请求的 Origin（含协议、域名、端口），并注意对 . 等元字符按需转义。可先用请求实际携带的 Origin 值离线验证正则匹配结果。
3. 确认源地址包含协议：源地址取值需完整包含 http 或 https，仅填写域名（例如 app.example.com）无法与浏览器发送的 Origin 头匹配。
4. 检查凭证与通配符的冲突：若请求需要携带凭证（已开启允许凭证），确认源地址未使用 *，改用具体来源，以避免非预期的全来源放通与安全风险。
5. 确认多个源地址的分隔符：填写多个源地址时须使用英文逗号分隔，避免使用中文逗号或分号。
6. 确认预检请求能命中该路由：浏览器预检为 OPTIONS 请求，若目标路由的匹配方法未包含 OPTIONS（例如仅匹配 POST），预检请求将无法命中该路由并触发 CORS 策略。建议在路由匹配条件中包含 OPTIONS 方法，或确保路由按路径匹配。
7. 确认策略层级与优先级：若同一路由同时配置了服务级与路由级 CORS 策略，实际以路由级策略为准，请检查生效的层级配置是否符合预期。
