Gin跨域配置教程详解

本文深入剖析了Golang Gin框架中跨域（CORS）配置的常见陷阱与最佳实践，强调必须使用gin-contrib/cors中间件而非手动设置Header——因为手写c.Header()无法处理预检请求（OPTIONS）、会导致凭据失效、易被Nginx覆盖，且在AllowCredentials为true时与通配符Origin共存会引发浏览器静默丢弃响应；文章详解了如何正确配置白名单（禁用"*"、支持动态origin函数校验）、暴露头字段、设置MaxAge，以及Nginx反向代理下必须透传CORS头的关键配置要点，直击上线前高频踩坑场景，助你一次配对、稳定运行。

直接用 gin-contrib/cors，别手写 c.Header() —— 预检漏掉、凭据失效、Nginx 覆盖 header 这三类问题，在上线前几乎必踩。

为什么不能在 handler 里手动设 CORS header

手写 c.Header("Access-Control-Allow-Origin", "*") 看似快，但实际只覆盖了简单请求；OPTIONS 预检请求根本不会进你的 handler，Gin 默认返回 405，前端直接卡死。更隐蔽的是：AllowCredentials: true 和 AllowOrigins: ["*"] 共存时，浏览器会静默丢弃整个响应，连错误都不报。

• 预检（OPTIONS）必须由中间件统一拦截并提前终止流程，不能依赖路由逻辑
• c.Header() 必须在 c.Next() 前调用，且对 OPTIONS 请求要 c.AbortWithStatus(204)，否则可能触发副作用
• 多个中间件叠加时，header 写入顺序错一次，Access-Control-Allow-Origin 就会被后写的覆盖

生产环境必须用 cors.New(config) 显式配置

cors.Default() 只适合本地调试：它默认开 AllowAllOrigins，自动禁用 AllowCredentials，且不设 MaxAge，导致每次非简单请求都触发预检，白白增加延迟。

• config.AllowCredentials = true 时，config.AllowOrigins 必须是完整域名列表，例如 []string{"https://app.example.com", "http://localhost:3000"}，不能含 "*"
• config.ExposeHeaders 要精确列出前端 JS 实际读取的字段，比如 "X-Total-Count" 或 "New-Token"，没列的即使后端返回了也拿不到
• config.MaxAge 建议设为 12 * time.Hour，减少重复预检

动态 origin 白名单得用 AllowOriginFunc，不是填数组

填 []string{"https://*.example.com"} 是无效的 —— gin-contrib/cors 不支持通配符匹配，只做完全相等或前缀比对（且前缀匹配需以 "https://" 开头并带斜杠）。真要从数据库或配置中心查白名单，必须用函数式配置：

config := cors.Config{
    AllowOriginFunc: func(origin string) bool {
        // 这里查 DB / Redis / cache，返回 true/false
        return isInWhitelist(origin)
    },
    AllowCredentials: true,
}

• 注意：该函数会在每个请求时执行，高频场景要考虑缓存或本地白名单兜底
• 函数返回 false 时，中间件会直接返回 403，不进后续 handler
• 仍需确保 AllowCredentials: true 时不返回 "*"，函数内应返回具体 origin 字符串

Nginx 后面跑 Gin？必须透传 Access-Control-Allow-Origin 等 header

Gin 返回了正确的 header，但浏览器仍报错？90% 是 Nginx 拦截了。Nginx 默认不透传自定义响应头，尤其当你用了 add_header，它会清空上游已设的所有 header。

• 必须在 location 块加：add_header 'Access-Control-Allow-Origin' '$sent_http_access_control_allow_origin' always;
• 禁用继承行为：在子 location 中也要加 add_header ... always，否则父块 header 丢失
• OPTIONS 请求不能被 Nginx 直接 return 204，必须透传给 Gin，否则预检失败

最易忽略的一点：Nginx 的 $sent_http_* 变量只在响应头已生成后才可用，若 Gin 中间件没正确设置 header，这个变量就是空的 —— 所以问题根源永远在 Go 侧配置是否真正生效，而不是 Nginx 没配好。

到这里，我们也就讲完了《Gin跨域配置教程详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！