用途:在已存在令牌与存储方案的前提下,让认证状态在多个浏览器标签页、页面刷新和令牌过期之间保持一致,不涉及登录注册等 CRUD 认证搭建。
主要能力与核心模式:
- 跨标签同步:使用 storage 事件(仅在其它标签页触发,不在设置值的当前页触发);触发登出需写入后立即移除标识,否则后续登出不会再次触发。更推荐 BroadcastChannel,它不产生存储副作用,且不会触达发送方自身,组件卸载时应关闭通道避免幽灵监听。
- 令牌静默刷新:多标签同时过期会并发刷新,导致令牌轮换冲突;用 localStorage 实现分布式互斥锁(含过期时间与 tabId,写入后延迟重读检测冲突),未获取锁的标签等待赢家广播后重读令牌。刷新策略分为基于定时器的主动刷新(到期前约 60 秒)、401 拦截的被动刷新(对未知过期时间的第三方令牌),建议两者结合;401 重试需用单一 refreshPromise 去重,请求失败后只重试一次。
- httpOnly Cookie 令牌:JS 无法读取令牌时,用可读的轻量标志(如 localStorage 或短时会话 cookie)表示认证状态,过期检测完全依赖 401,跨标签用 BroadcastChannel 同步登出、storage 事件同步标志变化。
- 页面刷新水合:刷新会丢失内存状态,可从存储读取前用 jwt-decode 校验签名/过期时间,同步初始化并设置 authReady 标志门控渲染以避免未认证 UI 闪烁。
- 登出传播清单:清理内存令牌与刷新定时器、localStorage 与 sessionStorage、广播 LOGOUT 并兼容 storage 事件监听、请求服务端清除 httpOnly cookie、取消在途请求后跳转登录。
使用方式:作为技能在实现认证同步时调用,产出 authSync.ts(BroadcastChannel、存储监听、刷新锁)、useAuth.ts 或框架等价物(消费同步事件的钩子/状态)、tokenRefresh.ts(带锁、主动定时器与 401 拦截的刷新逻辑),每个文件需注释说明所解决的问题与非常规之处,并标注竞态位置、事件在当前页与其它页的触发差异、浏览器兼容注意事项(BroadcastChannel 支持现代浏览器但不支持 IE)。资料未提供安装命令、具体依赖版本、框架适配细节与收费信息。