必须将Cookie的Domain属性设为以点开头的父域(如.example.com),并统一配置Path=/、Secure(HTTPS下必需)、SameSite=Lax或None;服务端Set-Cookie与前端document.cookie均需显式声明,不可依赖默认行为。

Cookie Domain 设置必须带前导点
Echo 框架本身不干预 Domain 属性的设置逻辑,但浏览器只在明确指定带前导点(如 .example.com)时,才将 Cookie 共享给所有子域名(api.example.com、www.example.com 等)。若只写 example.com,现代浏览器(Chrome 120+、Firefox 115+)默认视为不匹配子域名,仅限精确匹配。
正确做法是:调用 c.SetCookie() 时,传入的 *http.Cookie 实例中 Domain 字段必须为 ".example.com"(注意开头的点),且不能省略;同时确保该域名已通过 DNS 解析并可被客户端访问。
-
Domain值区分大小写,建议全小写 - 本地开发用
localhost无法设子域名 Cookie,必须改用类似app.test并配 hosts 文件 - 如果后端部署在
api.example.com,但前端在www.example.com,则 Cookie 必须由api.example.com发送且Domain设为".example.com",否则www侧收不到
Path 配置影响子域名下路径可见性
即使 Domain 正确设置了前导点,Path 属性仍会进一步限制 Cookie 的作用范围。比如设了 Path: "/api",那该 Cookie 在 www.example.com/ 或 admin.example.com/dashboard 下都不可见。
要实现跨子域名全站共享,Path 必须设为 "/" —— 这是唯一能覆盖所有路径的取值,且不能留空或设为 "." 等无效值。
- 多个子域名共用同一套登录态时,
Path必须为"/",否则Set-Cookie头会被浏览器静默忽略 - 若业务需要隔离路径(如
/admin专用 Cookie),应单独命名并设对应Path,避免和主站 Cookie 冲突 -
Path不影响跨子域名能力,只约束同域名下的路径层级
Secure 和 HttpOnly 要配合子域名 HTTPS 部署
当启用子域名共享后,Secure 属性变得关键:只要任一子域名(如 blog.example.com)走 HTTP,而 Cookie 又设了 Secure: true,那么该 Cookie 在 HTTP 子域名下根本不会被发送,导致状态丢失。
真实线上环境应确保所有子域名都启用 HTTPS,并统一配置 Secure: true;开发阶段若混用 HTTP,需临时设为 false,但上线前必须改回。
-
HttpOnly: true建议始终开启,防止任意子域名 XSS 泄露主站 Cookie(例如forum.example.com被注入脚本,仍无法读取.example.com下的HttpOnlyCookie) - SameSite 属性推荐设为
Lax,既防 CSRF,又不影响正常跨子域名跳转(如从www跳到checkout) - 测试时可用
curl -I https://api.example.com/login查看响应头中Set-Cookie的完整字段,确认Domain、Path、Secure是否符合预期
Session ID Cookie 共享需同步处理后端存储
子域名 Cookie 共享只是第一步。如果用 echo-contrib/session 管理会话,光靠 Domain: ".example.com" 不够——Session ID 是 Cookie 的值,但 Session 数据本身存在后端(Redis、文件等)。若不同子域名请求打到不同服务实例,而 Redis 没共用,就会出现“能读 Cookie 却查不到 Session”的现象。
必须确保所有子域名后端共用同一套 Session 存储后端,并在初始化 session.Middleware() 时显式传入该存储实例。
- 文件系统存储(
sessions.NewFilesystemStore)不适用于多实例,仅限单机调试 - Redis 是最常用选择,连接地址、DB、密码必须完全一致
- 别忘了检查密钥(
session.NewCookieStore(key)中的key)是否所有服务实例相同,否则解密失败导致sess == nil
子域名 Cookie 共享真正卡住人的地方,往往不在框架调用,而在 DNS 解析、HTTPS 证书覆盖范围、以及后端存储的一致性上。浏览器看到 Domain=".example.com" 就认,但服务端能不能对得上,得一层层对齐。











