5.5 跨域资源共享

概述

CORS 由中间件链第一层处理（middleware/cors.go）。开发环境前端经 Vite 代理天然同源；跨域直连场景由 cors.allowOrigin 配置控制，支持全放行与指定来源两种模式。

配置

cors:
  allowOrigin: "*"     # 允许的来源，为空或 * 时使用框架内置策略

两种模式

模式一：allowOrigin 为空或 "*"
  → r.Response.CORSDefault()（框架内置全放行策略）

模式二：allowOrigin 为具体来源
  → 显式回显：
     Access-Control-Allow-Origin: <配置值>
     Access-Control-Allow-Credentials: true
     Access-Control-Allow-Headers: Origin,Authorization,Content-Type,Accept,Token,X-Requested-With
     Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
  → OPTIONS 预检直接 204 返回

允许的请求头

Origin
Authorization      ← JWT Bearer 令牌
Content-Type       ← JSON / multipart
Accept
Token
X-Requested-With

与认证的配合

1. CORS 中间件在链首——预检 OPTIONS 在进入 JWT 前就完成响应
2. 带令牌的跨域请求：Authorization 头已在 Allow-Headers 白名单
3. 前端开发环境走 Vite proxy（同源），生产建议 Nginx 同域反代——
   同域部署时 CORS 实际不生效，最安全

生产建议

安全取舍

• allowOrigin: "*" + 凭证（Cookie 类）组合是危险配置——本系统用 Bearer 头（非 Cookie），风险较低，但公网服务仍建议配置具体来源域名。
• 前端与后端同域部署（Nginx 反代 /api）是推荐方案，从根上消除 CORS 需求。
• 修改来源配置后需重启后端生效（中间件启动时读取）。

排障

症状	检查
浏览器报 CORS blocked	前端是否直连后端且 allowOrigin 不含该来源；推荐改同域反代
预检通过但正式请求 401	非 CORS 问题——是 JWT（令牌缺失/过期/黑名单）
带 cookie 报凭证错误	本系统不用 Cookie 会话，检查前端是否误带 credentials
生产偶发跨域失败	多域名场景确认 allowOrigin 是否支持多值（逗号分隔需验证）；或收敛到同域