现在的浏览器开发者工具里Application 面板下的 Cookies 一栏大概是后端和前端吵架时最常被截图的地方。我这些年排查过的“登录状态莫名其妙丢了”“接口突然 401”“换个环境 Cookie 就带不上”这类问题十次里有八次根子都在 Cookie 的某个属性上。Cookie 这东西看着简单——不就是浏览器存的一小段键值对吗但真要把它用明白你得同时搞清楚四件事它是怎么被写进去的、浏览器什么时候会带上它、服务端怎么判断它可信、以及它在什么情况下会悄悄失效。这篇东西我打算把 Cookie 从结构、属性、读写链路、选型、安全加固到故障排查完整过一遍既讲清楚每个开关背后的为什么也给可以直接抄的代码和排查路径。不管你是刚接触 Web 开发、被跨域 Cookie 搞得头大的新手还是做了几年依然会在 SameSite 上翻车的老手下面这些内容应该都能对上你的某个记忆点。1. 从一次登录莫名掉线聊起Cookie 到底解决了什么问题1.1 HTTP 为什么天生需要 Cookie 这个东西HTTP 是个无状态协议这句话刚学的时候没什么感觉真上手写业务才知道它有多要命。浏览器发一个请求服务端处理完返回响应连接关了两边就当没见过。你登录成功了下一次请求商品列表服务端根本不知道“你”是谁——因为协议层面压根没有身份这个概念每个请求都是陌生访客。最早的土办法是在 URL 上挂参数比如每次跳转都带着?sidxxx。这招能用但很脏链接一分享身份就泄露用户复制粘贴地址栏也会把凭证带出去而且每个请求都得手工拼。另一种办法是隐藏表单域表单提交时把凭证塞进去可一旦用户点的是普通超链接凭证就断了。这两种方案共同的毛病是把“状态”这个职责压给了页面本身页面一换就没了。Cookie 的思路完全不一样它把这层状态交给浏览器托管。服务端在响应头里说一句“帮我把这串东西存下来”浏览器就按域名存进本地的一个小仓库之后凡是发往这个域名的请求浏览器自动从仓库里取出对应的键值对塞进请求头一起发出去。整个过程中页面代码不用做任何事用户也感知不到。这才是 Cookie 真正的价值——它不是一个存储 API它是浏览器和服务端之间一条自动化的、有作用域约束的状态通道。理解了这一点后面所有关于 Domain、Path、SameSite 的规则就都好解释了它们本质上都是在回答同一个问题——这条自动通道应该对哪些请求生效。注意Cookie 是浏览器行为不是 HTTP 协议强制的。你自己写个脚本发请求不手动加 Cookie 头服务端一样收不到。这也是为什么接口调试工具里总有一个“手动填 Cookie”的输入框。1.2 一条 Cookie 的完整结构逐字段拆开看很多人对 Cookie 的印象停留在namevalue实际上一条完整的 Cookie 由键值对加一串属性组成属性之间用分号加空格分隔。服务端下发时的原始形态长这样Set-Cookie: sid8f3a1c9e2b; Path/; Domainexample.com; Max-Age604800; Secure; HttpOnly; SameSiteLax拆开看sid8f3a1c9e2b是名字和值后面每一个分号段都是一个属性。这些属性分两类一类决定浏览器什么时候把它带上Domain、Path、Secure、SameSite另一类决定它活多久、谁能读到Expires、Max-Age、HttpOnly。值本身也有约束。名字和值里不能出现分号、逗号、空格、等号这些分隔符所以业务上如果要存中文、JSON、带特殊字符的 token必须做一次编码。前端用encodeURIComponent服务端对应解码这是最省事的做法。我见过有人直接把 base64 塞进去结果 base64 里的和/在某些解析器下会出问题保险起见还是编码一遍。还有一个容易被忽略的点Cookie 的值不是加密的它就是明文存在用户机器上的。除非你走的 HTTPS 且中途没被截否则打开开发者工具就能看见全部内容。所以任何“把权限信息编码一下放 Cookie 里就安全了”的想法都是自欺欺人编码不等于加密后面第 5 节会专门讲这块。1.3 浏览器把它存在哪、什么时候清理不同浏览器的落盘位置不一样有的存在一个 SQLite 数据库里有的存在独立文件中但对开发者来说更重要的是可见性规则你在开发者工具的 Application 或 Storage 面板里看到的 Cookie 列表是按域名分组展示的每条会明确标出 Domain、Path、Expires、Size、HttpOnly、Secure、SameSite 这些列。排查问题的第一步永远是打开这个面板看一眼 Cookie 到底存不存在、属性对不对。清理时机分三种。会话 Cookie没设 Expires 和 Max-Age理论上关浏览器就清但现代浏览器普遍有“恢复上次会话”的功能重启后会话 Cookie 可能被保留下来所以别把“关浏览器就没了”当成安全保证。持久化 Cookie 到期自动清。还有一种是被顶掉的每个域名能存的 Cookie 数量有上限主流浏览器大约在 50 条上下超出后会按某种淘汰策略把最久没用的踢掉。这个机制造成的 bug 极其隐蔽——你的 Cookie 明明设置成功了过一会儿就没了查半天以为是代码问题其实是数量超限被挤掉了。2. 六个属性决定 Cookie 的死活作用域、生命周期与安全开关2.1 Domain 与 Path为什么你的 Cookie 在子域读不到Domain 决定这条 Cookie 对哪些主机生效。规则是这样的如果你不写 Domain浏览器会把 Cookie 绑定到当前请求的完整主机名上这叫 host-only也就是说a.example.com设的 Cookieb.example.com读不到example.com也读不到。如果你写了Domainexample.com那么example.com以及它的所有子域都能读到反过来a.example.com设的 Cookie 想把 Domain 写成example.com是允许的向父域扩展但写成一个跟当前域无关的域会被浏览器直接拒绝。还有个硬约束不能把 Domain 设成顶级域或公共后缀。你写Domaincom或者Domainco.uk浏览器一律拒收。这个判断依据的是公共后缀列表所以像某些国家二级域下的托管服务各个子站之间其实是互相隔离的这个细节在做多租户系统时会踩到。Path 决定这条 Cookie 对哪些路径生效规则是前缀匹配但有个容易记错的边界Path/admin能匹配/admin、/admin/、/admin/user/list但不匹配/administrator。因为规范要求要么完全相等要么 Cookie 的 path 以斜杠结尾并且是请求路径的前缀要么请求路径在对应位置上的字符正好是斜杠。这个细节决定了你不能靠Path/admin去“保护”所有以 admin 开头的路径。注意Path 经常被误当成权限边界这是很危险的认知。Path 只影响浏览器要不要发送完全不阻止用户在控制台里改 Cookie 的 Path 再手工发请求。真正的权限校验必须在服务端做一丝一毫都不能省。2.2 Expires 与 Max-Age会话态和持久化的取舍这两个属性都在控制生命周期但形式不同。Expires 是一个绝对时间点格式必须是 GMT 字符串前端用new Date(...).toUTCString()生成。Max-Age 是一个相对秒数从收到响应那一刻开始倒计时。两个同时出现时Max-Age 优先级更高Expires 会被忽略。实际用哪个我的习惯是需要精确控制绝对过期时间比如配合服务端的 token 过期时间就用 Expires其余一律用 Max-Age。原因很实在——Max-Age 不受客户端时钟影响。用户机器时间如果被手动改过或者时区错乱Expires 的判断就会失准我见过客户端时间比服务器快两小时导致 Cookie 一设上就过期的案例排查了半天才发现是系统时间的问题。删除 Cookie 也是靠这两个属性实现的把 Max-Age 设为 0或者把 Expires 设成一个过去的时间点浏览器收到后就会把对应 Cookie 删掉。这里藏着一个高频坑删除时必须保证 name、Domain、Path 三者与当初设置时完全一致只要有一项对不上浏览器就认为你在操作另一条 Cookie结果就是“删了但没删掉”。很多人本地调试时给 Cookie 设了Domain.example.com删除时忘了带这个 Domain删了一万次都没用。2.3 Secure、HttpOnly、SameSite三个安全开关的联动关系Secure 的含义很直接这条 Cookie 只在 HTTPS 请求中发送HTTP 环境下浏览器不会带上它甚至在 HTTP 响应里出现的Set-Cookie: ...; Secure也会被直接丢弃。所以本地用 HTTP 调试时如果代码里硬编码了 Secure表现就是“Cookie 怎么都存不进去”这是新手最常见的困惑之一。HttpOnly 的作用是禁止 JavaScript 通过document.cookie读取这条 Cookie。它挡的是 XSS 场景下的凭证窃取——脚本能改页面、能发请求但读不到这个 HttpOnly 的 Cookie也就没法把会话凭证原样偷走。记住它只防“读”不防“用”攻击者依然可以在你的页面上下文里发请求浏览器会自动带上 Cookie这就是 CSRF 存在的空间。SameSite 是这三个里最晚普及、也是坑最多的。它有三个取值取值跨站请求是否携带典型用途Strict完全不携带高敏感操作、支付类页面Lax顶层导航的 GET 请求携带其余跨站请求不携带绝大多数业务默认值None携带但必须同时设置 Secure需要跨站嵌入的第三方场景Lax 现在基本是浏览器默认值也就是说如果你什么都不写拿到的就是 Lax。这个默认值挽救了很多老系统它天然挡掉了大部分跨站 POST 的 CSRF但也制造了大量新问题如果你的前端和后端分属不同站点登录接口是 POST 跨站调用那服务端下发的 Cookie 在后续请求里根本带不上表现就是“登录成功但立刻又变成未登录”。想跨站就必须显式写SameSiteNone; Secure。这里还有个隐蔽的坑本地开发跑的是 HTTPSameSiteNone强制要求 Secure浏览器就会静默丢弃这条 Cookie。localhost通常被当作安全上下文对待所以本地能跑但你一旦换成局域网 IP 或者自定义 hosts 去手机上调Cookie 立刻就没了而且控制台往往只在被丢弃时给一条警告很容易被忽略。3. 手把手跑通读写链路前端封装、后端 Set-Cookie、跨域携带3.1 原生 document.cookie 的坑与一套可靠封装原生的document.cookie用起来非常反直觉你读它拿到的是当前域名下所有非 HttpOnlyCookie 拼成的一个字符串形如a1; b2; c3你写它不是覆盖整个字符串而是“追加或更新一条”。也就是说读写语义完全不对称这让很多人第一次用的时候一头雾水。基于这个特性读取必须自己解析。下面这套封装我在好几个项目里都用过处理了 URL 编码和名字前缀误匹配的问题function setCookie(name, value, options {}) { const { days, path /, domain, secure false, sameSite Lax } options; let str ${encodeURIComponent(name)}${encodeURIComponent(value)}; if (typeof days number) { const expires new Date(Date.now() days * 86400000).toUTCString(); str ; Expires${expires}; } str ; Path${path}; if (domain) str ; Domain${domain}; if (secure) str ; Secure; if (sameSite) str ; SameSite${sameSite}; document.cookie str; } function getCookie(name) { const target encodeURIComponent(name) ; const parts document.cookie ? document.cookie.split(; ) : []; for (const item of parts) { if (item.indexOf(target) 0) { return decodeURIComponent(item.slice(target.length)); } } return null; } function removeCookie(name, options {}) { setCookie(name, , { ...options, days: -1 }); }getCookie里用indexOf(target) 0而不是includes是为了避免把user_token误判成token。这个 bug 我在早期项目里真踩过两个 Cookie 名字互为后缀结果读出来的值永远是错的那个排查时盯着代码看了半小时才反应过来。注意前端能读写的 Cookie 一定是非 HttpOnly 的。如果某个 Cookie 你在控制台里怎么读都是 null先去看它的 HttpOnly 列是不是打了勾别急着怀疑代码。3.2 服务端下发 Cookie 的报文细节服务端设置 Cookie 靠的是响应头Set-Cookie。这个头有两个必须知道的行为一是一次响应可以带多个Set-Cookie头每条对应一个 Cookie二是它不能用逗号合并成一行因为 Cookie 的值里可能包含逗号合并后无法可靠解析。一个规范的登录响应大致是这样HTTP/1.1 200 OK Content-Type: application/json Set-Cookie: sid8f3a1c9e2b7d4f10; Path/; Max-Age604800; HttpOnly; Secure; SameSiteLax Set-Cookie: themedark; Path/; Max-Age31536000; SameSiteLax {ok:true,user:{id:1024,name:demo}}注意这里两条 Cookie 的属性是不一样的会话凭证那条带了 HttpOnly 和 Secure主题偏好那条没带 HttpOnly因为前端要读它来渲染也没带 Secure因为它不敏感HTTP 下也能用。这种“按敏感度分条下发”的习惯很重要把不敏感的数据和会话凭证混在一条里等于白白放弃了 HttpOnly 的保护。还有一个经常被忽略的细节304 响应也可以带 Set-Cookie。也就是说即便页面走的是协商缓存服务端依然有机会刷新 Cookie 的过期时间。反过来说如果你在 304 分支里漏掉了 Cookie 续期的逻辑用户就可能遇到“一直在用页面但会话在某刻突然到期”的诡异现象。3.3 跨域携带凭证的完整配置链条跨域带 Cookie 是最容易翻车的场景因为它需要三处配置同时正确缺一处就静默失败。我用一张表把链条列清楚位置需要做的配置漏掉的后果前端请求fetch加credentials: include请求不携带 Cookie服务端 CORSAccess-Control-Allow-Credentials: true浏览器拦截响应服务端 CORSAccess-Control-Allow-Origin必须是具体源不能是*浏览器直接拒绝服务端 CORSAccess-Control-Allow-Headers需包含实际用到的头预检失败Cookie 属性跨站场景需要SameSiteNone; SecureCookie 不下发或被丢弃原生 fetch 的写法const res await fetch(https://api.example.com/login, { method: POST, credentials: include, headers: { Content-Type: application/json }, body: JSON.stringify({ user: demo, pass: ****** }) });有个衍生问题值得单独说在跨站场景下预检请求OPTIONS本身不带 Cookie这是规范行为。所以服务端如果在全局中间件里做“无 Cookie 即拒绝”的拦截预检请求会被直接打回前端看到的就是一个没头没脑的 CORS 错误。正确做法是让 OPTIONS 请求在鉴权中间件之前就被放行返回 204 并带上 CORS 头即可。3.4 容量实测4KB 不是随便说说的数字单个 Cookie 的大小上限大约是 4KB这个数字包含了 name、value 和所有属性不只是 value 的长度。超限时浏览器的处理方式不是截断而是整条丢弃而且多数情况下只给一条警告级日志。我做过一次简单的实测生成一段纯 ASCII 字符串塞进 value逐步加长观察写入是否成功。结果是 4096 字节附近开始失败考虑到属性占用的空间实际留给 value 的余量大概在 4000 字节出头。如果 value 里含中文经过encodeURIComponent编码后每个汉字会膨胀到 9 个字符左右%E4%B8%AD这种形式可用容量会急剧缩水400 多个汉字就顶满了。数量上限同样值得关注。主流浏览器单域名大约 50 条左右超出后按最近最少使用淘汰。这在多子系统共用主域的项目里很容易出事A 系统写十几条、B 系统写十几条、埋点 SDK 再写十来条、第三方组件再塞几条加起来逼近上限然后某个凌晨你的会话 Cookie 就被挤掉了表现为“用户偶发掉线”日志里什么都查不到。我的处理原则是单条 Cookie 控制在 1KB 以内单个域下的 Cookie 总数控制在 20 条以内。理由不只是存储限制更因为每个 Cookie 都会跟着每一个同域请求发出去。你在主域下挂 3KB 的 Cookie等于给每个静态资源请求都加了 3KB 的头上开销这个成本在移动端弱网下非常明显。4. Cookie、Session、LocalStorage不同场景下的选型对照4.1 四类存储方案的横向对比“Cookie 和 LocalStorage 到底用哪个存 token”这个问题隔三差五就会在群里被问一次。答案不是二选一而是要看你更怕什么。我整理了一张对照表把关键差异拉平了看维度CookieLocalStorageSessionStorage服务端 Session容量约 4KB/条50 条/域约 5MB约 5MB取决于服务端存储生命周期可精确控制手动清除永久关闭标签页即清由服务端控制是否自动随请求发送是否否依赖 Cookie 存 sessionIdJS 可读非 HttpOnly 可读可读可读不可直接读跨标签页共享是是否是防 XSS 窃取HttpOnly 可挡完全无防护完全无防护HttpOnly 可挡防 CSRF需要 SameSite 或 Token天然免疫天然免疫需要 SameSite 或 Token这张表读下来最关键的一行是最后两行它们是一对矛盾Cookie 天然扛 CSRF 弱但扛 XSS 强LocalStorage 天然扛 CSRF 强但扛 XSS 弱到几乎没有。把 token 放 LocalStorage任何一处 XSS 都能直接把 token 读走并外传而且这个 token 是长期的放 HttpOnly Cookie脚本读不到但浏览器会自动带上需要额外防 CSRF。我个人的判断是会话凭证走 HttpOnly Secure SameSite 的 Cookie配合 CSRF Token 或自定义请求头做二次校验。这套组合在两边都留了防线是目前综合风险最低的做法。LocalStorage 我会用来放那些丢了也不致命的东西——主题、语言、上次访问的列表页位置、前端缓存的一些静态配置。4.2 我的划分原则什么数据该进 Cookie抛开技术细节我用一套很土但很好用的判断流程来决定数据往哪放。第一问这份数据需要在服务端被读到吗如果不需要服务端完全不关心用户选的是深色还是浅色那就别浪费 Cookie 配额直接 LocalStorage。一旦放进 Cookie它就会白白跟着每一个请求飘到服务器服务器再原样丢掉纯属浪费带宽。第二问这份数据敏感吗能直接换取权限、身份、资金操作的一律 Cookie HttpOnly。哪怕它只是一串随机 ID只要服务端认它它就等同于密码。第三问这份数据需要跨标签页共享吗比如登录态必须所有标签页一致那就不能用 SessionStorage。反过来某个表单的草稿只属于当前标签页用 SessionStorage 更干净还能顺带解决“用户开了五个标签页互相覆盖”的问题。第四问这份数据有多大超过 1KB 就认真考虑一下是不是该换个方案。我见过把整份用户权限菜单 JSON 塞进 Cookie 的实现一段 3KB 的字符串每个请求都带用户在弱网下打开首页要多等将近一秒。还有个隐藏维度是过期策略的一致性。如果你的 token 有效期是 7 天Cookie 的 Max-Age 也应该是 7 天两者不一致就会出现“Cookie 还在但服务端已经不认”或者“服务端还认但 Cookie 已经没了”的错位状态。我现在的习惯是把服务端的过期时间下发到前端前端照着设绝不各写各的。5. 安全加固偷 Cookie 与伪造请求的两条攻击链5.1 XSS 场景下的 Cookie 暴露面XSS 的攻击链条很清楚攻击者想办法让你的页面执行他注入的脚本脚本第一件事就是document.cookie或者localStorage.getItem把凭证打包发到自己的服务器然后拿着这份凭证冒充用户。整个过程不需要破解任何加密因为浏览器本来就把明文凭证交给了页面。HttpOnly 就是在这条链上切一刀。设了之后document.cookie里根本不会出现这条 Cookie脚本读不到。但要清楚它的边界HttpOnly只防读取不防利用。脚本依然可以在你的页面里发一个带 Cookie 的请求把用户的余额转到别处或者调一个删除接口。所以 HttpOnly 是必要不充分的它降低的是“凭证被批量窃取”的风险不能阻止“当前会话被滥用”。因此真正要解决 XSS还是得靠输出编码、内容安全策略、依赖库的定期审计这些基本功。Cookie 属性只是在最后一道位置上减少损失。我见过团队把 HttpOnly 当成 XSS 的解决方案结果注入点一直没修攻击者虽然偷不到 Cookie但依然能通过脚本调用业务接口把钱转走损失的金额一分没少。顺带说一个常见误解Secure属性跟 XSS 没有关系它管的是传输层。你设了 Secure 但页面存在 XSS该被偷还是被偷只是攻击者拿到的是一个 HTTPS 传输过来的凭证而已。5.2 CSRF 的攻击链条与防御组合拳CSRF 的逻辑和 XSS 反过来攻击者不需要读你的页面他只需要诱导你的浏览器向目标站点发一个请求。因为浏览器会自动带上目标站点的 Cookie服务端看到凭证有效就认为这是用户本人操作。典型的攻击场景是这样的用户登录了某个后台Cookie 还在有效期内然后访问了一个被植入恶意代码的第三方页面那个页面里藏着一个自动提交的表单目标地址是后台的“添加管理员”接口参数都填好了浏览器提交表单时自动带上了后台域的 Cookie请求合法通过。防御这套东西需要多层叠加单靠一层都不够稳第一层是 SameSite。设成 Lax 之后跨站的 POST 请求默认不带 Cookie绝大部分传统的 CSRF 手法直接失效。这是成本最低、收益最大的一层也是这几年浏览器默认值改成 Lax 之后老系统的 CSRF 问题少了很多的原因。第二层是 CSRF Token。服务端在渲染页面时下发一个随机 token可以放在页面里也可以放在一个非 HttpOnly 的 Cookie 里前端提交时把它放到请求体或自定义头里。服务端比对两者是否匹配。这个方案的巧妙之处在于攻击者的页面能发出请求但读不到 token因为跨域读不到响应内容也无法预知随机值。第三层是校验 Origin 或 Referer。服务端检查请求来源域是否在白名单里。这层很轻但要注意有些场景下这些头可能缺失比如某些隐私设置所以适合作为兜底而不是唯一防线。第四层是敏感操作二次验证。改密码、转账、删数据这类操作强制要求重新输入密码或验证码。这层不解决技术问题但它把单次请求被利用的损失控制住了。注意双提交 Cookie 方案同一个随机值既放 Cookie 又放请求头服务端比对两者相等实现简单但它有一个前提——攻击者无法往目标域写 Cookie。如果目标站存在任何子域接管或 Cookie 注入问题这层就被绕过了。所以它更适合作为 Token 方案的补充而不是替代。5.3 业务层签名与 Cookie 前缀的实战用法前面说过 Cookie 是明文用户可以随便改。所以只要服务端会信任 Cookie 里的某段内容就必须加签名。做法很简单服务端用密钥对namevalue加上过期时间做一次 HMAC把签名一起放进 Cookie下次收到时重新计算一遍比对。用户改了 value 但算不出签名校验就失败。签名能防篡改但不防读取。如果 Cookie 里存的东西本身就不能让用户看到比如内部 ID、角色标识那就得加密不是签名。这两件事经常被混为一谈实际上职责完全不同签名保证完整性加密保证机密性。除了自己加签名浏览器还提供了两个 Cookie 名前缀可以让浏览器帮你做一层属性校验前缀强制要求作用__Secure-必须带Secure属性防止被 HTTP 响应覆盖写入__Host-必须带Secure、Path/且不能有Domain进一步锁定到当前主机避免被子域覆盖__Host-这层保护在多子域的环境里价值很大。假设你的主站和一堆业务子域共用同一个父域某个子域如果被攻陷它理论上可以往父域写一条同名 Cookie 来覆盖你的会话凭证这叫 Cookie 固定。用了__Host-前缀浏览器会强制要求这条 Cookie 不能带 Domain子域就写不进来了。这个细节知道的人不多但在做安全评审时经常能加分。还有一类进阶场景是分区 Cookie浏览器会把不同顶级站点下嵌入的第三方 Cookie 按站点隔离存两份避免跨站追踪。这对广告和第三方嵌入的统计影响很大如果你的业务里有第三方组件依赖 Cookie 做状态保持需要提前评估这个变化。6. 高频故障排查实录Cookie 不生效的十种可能6.1 排查顺序先看响应头再看请求头Cookie 出问题的排查有一条固定路径按这个顺序走能省掉大部分瞎猜。第一步看响应头。打开开发者工具的 Network 面板找到那次设置 Cookie 的请求点开 Response Headers确认Set-Cookie这一行到底存不存在、内容是什么。如果压根没有这一行问题在后端可能是被某个中间件覆盖了响应头或者是网关把 Cookie 头过滤了。如果存在但属性看起来不对问题在配置。第二步看 Application 面板。切换到 Cookie 列表确认那条 Cookie 有没有真的落库。如果响应头里有但列表里没有几乎全是属性问题Secure 在 HTTP 下被丢弃、SameSiteNone 缺 Secure、Domain 不合法、Path 写得离谱、或者体积超限。第三步看下一个请求的请求头。发起一次需要带 Cookie 的请求看 Request Headers 里Cookie这一行有没有对应的键值。这里有就说明浏览器发送正常问题在服务端解析或校验环节没有就说明是作用域问题——域不对、路径不对、或者请求根本没走同源。第四步查后端日志。如果请求头里确实带了但服务端说没有那就是解析层的问题。常见的是反向代理把Cookie头丢了有些配置在转发时只保留白名单头或者后端框架的 Cookie 解析中间件没启用或者有两个同名 Cookie 导致取到了错的那个。这套顺序的核心逻辑是沿着数据流一段段确认而不是一上来就猜代码哪里写错了。我带的同学里凡是按这个顺序走的平均定位时间能压到十分钟以内。6.2 速查表十类典型症状与对应处置下面这张表是我这些年攒下来的遇到问题先对号入座能覆盖大部分情况症状最可能原因处置方式响应头有 Set-Cookie但列表里没有Secure 属性配了但走的是 HTTP本地调试临时去掉 Secure或用 HTTPS列表里有但下个请求不带Domain 或 Path 不匹配检查 Domain 是否漏写父域、Path 是否覆盖该接口跨站请求带不上SameSite 默认 Lax 且是跨站 POST改SameSiteNone; Secure跨站登录成功但立刻变未登录前端没加credentials: include补上同时确认 CORS 允许凭证本地能跑换 IP 就失效IP 被视为非安全上下文Secure 失效用域名访问或用隧道映射域名Cookie 设了删不掉删除时 Path 或 Domain 与设置时不一致三者完全对齐或用 Max-Age0JS 读不到但请求能带上设了 HttpOnly属正常行为需要前端读就别设 HttpOnly上线后偶发掉线Cookie 数量或体积超限被淘汰精简 Cookie把非必要数据移出值里带中文变乱码没有做 URL 编码写入时 encodeURIComponent读取时解码服务端收到的 Cookie 少了反向代理过滤或请求头超限检查代理配置与请求头大小限制表格之外还有两个偏门的症状值得单独提。一个是两个同名 Cookie 同时存在一条 Path/一条 Path/api浏览器会把两条都发出去服务端解析时取第一个结果取到的是旧值。这种情况在经历过路径调整的项目里很常见处置办法是两条路径下都执行一次删除或者干脆换一个 Cookie 名做迁移。另一个是时间格式错误Expires 必须是Wed, 21 Oct 2026 07:28:00 GMT这种格式写成 ISO 8601 或者带时区偏移的格式部分浏览器会静默忽略这个属性Cookie 就退化成会话 Cookie表现是“用户关一次浏览器就要重新登录”。6.3 我在实际项目里踩过的几个坑说几个印象深的都是文档里不太会写、但真能让人加班的东西。第一个是 Cookie 不区分端口。当时我在本地起了两个服务一个跑在前端端口一个跑在后端端口都在同一个主机上。我天真地以为不同端口是不同的源Cookie 应该隔离结果两边的 Cookie 互相覆盖调试了整整一个下午。后来才确认Cookie 的隔离维度是主机名和路径不包含端口也不包含协议HTTP 和 HTTPS 共享同一份 Cookie只是 Secure 的那条后者才发送。这个规则在容器化部署、多环境共存的时候特别容易踩。第二个是删除失败的连锁反应。有个项目的退出登录逻辑一直有偶发失效用户点了退出页面跳转到登录页但下次刷新又变成已登录。查了很久才发现退出接口里删除 Cookie 时没带 Domain而登录时是带了父域的。浏览器认为那是两条不同的 Cookie删掉的是不存在的那条。修复方式就一行代码但这个 bug 上线了两周才被发现因为用户点完退出通常会直接关页面不会刷新。第三个是关于过期时间的心智模型。我早期一直以为“Cookie 的过期时间到了服务端的会话也就结束了”实际上两者完全独立。Cookie 过期只是浏览器不再携带它服务端如果自己维护了一份会话记录那份记录还在一直有效直到自己的超时机制触发。反过来也一样服务端会话过期了Cookie 还在客户端飘着用户看到的是一个“带着失效凭证不停请求失败”的状态。现在的做法是让服务端把剩余有效期随响应下发前端按这个值同步刷新 Cookie两边的心跳尽量对齐用户体验会平稳很多。最后一个跟排查工具有关。遇到“Chrome 里正常、另一个浏览器里不对”这类问题别急着怀疑内核差异先确认两边的 Cookie 是不是同一时刻创建的。我遇到过一次是因为测试机的系统时间慢了十几分钟导致 Expires 判断出现偏差表现就是某些浏览器里 Cookie 一写进去就过期。看起来像兼容性问题根子其实在时钟同步。提示调试 Cookie 时养成一个习惯——每次改完属性先在开发者工具里手动清一次该域下的所有 Cookie再重新走一遍流程。残留的旧 Cookie 造成的干扰远比想象中多尤其是同名不同 Path 的情况肉眼在列表里根本分辨不出来。这些都是纯经验性的东西文档不会写但只要在真实项目里跑过一轮大概率都会遇到。Cookie 这个技术的门槛不在于理解它是什么而在于把它身上那十几个属性和浏览器的各种默认行为组合起来之后还能准确预判某一次请求到底会带什么、不会带什么。等你什么时候能够不打开开发者工具就说清楚“这条 Cookie 现在应该在不在、会不会被发送”这块知识基本就算过关了。
