storage 事件怎样同步多个标签页状态

多个标签页同步状态时，最小可用方案是：发送页面把一条 JSON 消息写入 localStorage，其它同源标签页监听 window 的 storage 事件，再根据消息类型更新自己的内存状态。关键边界只有一个：修改存储的那个标签页不会收到这次事件，所以发送页要先更新自己，其它页面再由事件更新。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event

先用 localStorage 做跨标签页通知，再用消息类型和唯一 ID 保证更新可判断、可去重。不要把 storage 事件当成当前页面的回调，也不要用 sessionStorage 期待跨标签页同步。

一、先判断为什么当前标签页没有收到事件

storage 事件由发生变化的存储区域触发，但事件会送到“其它”能访问这个存储区域的窗口。使用 localStorage 时，通常是同源的其它标签页、窗口或 iframe；使用 sessionStorage 时，范围还受同一个顶级浏览上下文限制，不能把它当成标签页之间的广播通道。

因此排查时先问三个问题：

• 两个页面的协议、主机和端口是否完全相同？不同源不会共享这块存储。
• 监听器是否注册在修改发生之前，且监听的是 window 而不是某个业务组件？
• 是不是在同一个标签页里写入又等待事件刷新自己？发送页不会收到自己的 storage 事件。

这个判断能快速解释最常见的“代码没报错但页面不更新”：事件可能已经按规则发送给了另一个页面，只是当前页本来就不在接收范围内。

二、先约定一条可以排查的消息

不要直接把业务对象散落在多个 storage key 中。建议固定一个 key，并在值里带上消息类型、版本、唯一 ID 和负载。这样接收页能忽略不关心的消息，也能在重复写入时做幂等处理。

// 统一消息结构，便于不同标签页按 type 分流
const STORAGE_KEY = "demo:tab-sync";

function makeMessage(type, payload) {
  return {
    type,
    version: 1,
    id: crypto.randomUUID(),
    payload,
    sentAt: Date.now()
  };
}

function publish(message) {
  // localStorage 只能保存字符串，所以统一序列化
  localStorage.setItem(STORAGE_KEY, JSON.stringify(message));
}

// 发送端先更新自己，再通知其它同源标签页
function changeTheme(theme) {
  applyTheme(theme);
  publish(makeMessage("theme-changed", { theme }));
}

这里的 id 不是鉴权字段，而是排查和去重用的消息标识；version 让后续升级消息结构时有机会兼容旧页面。sentAt 只用于日志和过期判断，不能替代真正的状态版本。

三、在其它标签页接收并更新状态

接收端只关心目标 key，并从 event.newValue 解析最新值。不要使用接收页面自己的旧快照作为消息来源，因为事件对象已经提供了这次变化后的值。

const seenMessageIds = new Set();

function onStorageChange(event) {
  // 其它 key 的变化不属于当前同步通道
  if (event.key !== STORAGE_KEY) return;

  // removeItem 会让 newValue 变成 null，交给清理分支处理
  if (event.newValue === null) {
    return;
  }

  let message;
  try {
    // 跨页面数据可能被手工改坏，解析失败不能阻塞后续监听
    message = JSON.parse(event.newValue);
  } catch (error) {
    console.warn("忽略无法解析的标签页消息", error);
    return;
  }

  if (message.version !== 1 || !message.id || seenMessageIds.has(message.id)) {
    return;
  }
  seenMessageIds.add(message.id);

  if (message.type === "theme-changed" && typeof message.payload?.theme === "string") {
    // 同一消息只应用一次，避免重复写入造成界面抖动
    applyTheme(message.payload.theme);
  }
}

window.addEventListener("storage", onStorageChange);

function stopTabSync() {
  // 页面卸载或组件销毁时解除监听，避免重复注册
  window.removeEventListener("storage", onStorageChange);
}

真实项目里可以把 seenMessageIds 换成带上限和过期时间的缓存，避免长期运行的页面无限增长。若消息只需要“当前最终值”，也可以直接用值覆盖，不必把每条变化当成可靠队列。

四、清理消息时要区分 null 和空字符串

调用 localStorage.removeItem(STORAGE_KEY) 时，其它页面收到的 event.newValue 是 null；如果写入的是空字符串，newValue 则是 ""，两者语义不同。可以专门发布一条清理消息，也可以把删除作为“清空缓存”的通知。

function clearTabState() {
  // 先清理当前页，因为当前页不会收到自己的 storage 事件
  resetLocalState();
  localStorage.removeItem(STORAGE_KEY);
}

function onStorageChangeForClear(event) {
  if (event.key !== STORAGE_KEY) return;
  if (event.newValue === null) {
    // 其它标签页删除了同步 key，当前页同步恢复初始状态
    resetLocalState();
  }
}

如果项目需要同时表达“删除登录态”和“主题改成默认值”，更稳妥的做法是写入带 type 的清理消息，再由接收端按业务动作处理；不要仅靠删除 key 推断所有业务含义。

五、出现不同步时按这张清单回滚

1. 先确认来源。在监听器里临时记录 event.key、event.oldValue 和 event.newValue，确认确实有其它页面写入。
2. 再确认同源。协议、主机、端口任意一项不同都不能共享 localStorage；跨源场景应改用服务端推送、postMessage 或其它明确的通信方案。
3. 回退到直接更新。发送页不要等待事件刷新自己，保留 applyTheme 或 resetLocalState 的本地调用。
4. 撤销失控监听。组件重复挂载时先移除旧监听器，避免同一消息触发多次；页面销毁时调用 stopTabSync。
5. 清理脏值。解析失败时只忽略该条消息，不要在监听器里循环写回同一个 key，否则可能形成跨页抖动。

速查：storage 事件适合什么场景

常见问题

为什么 localStorage.setItem 后当前页没有触发回调？

这是规范行为，修改发生的窗口不会收到自己的 storage 事件。当前页应直接执行状态更新，再让其它同源页面接收事件。

删除 localStorage 后还能收到事件吗？

其它符合范围的窗口可以收到事件，此时 newValue 是 null。当前页仍不会收到自己的删除事件。

能不能用 storage 事件传递大对象？

不建议把它当大对象传输或可靠队列。消息应保持小而明确，接收端做好 JSON 解析、版本和幂等处理；复杂数据可以只广播一个版本号，再由各页面重新读取来源。

总结一下：先确认同源和事件接收范围，再固定 key 与消息结构；发送页本地更新，接收页解析 newValue 后按类型处理；最后为删除、脏数据、重复监听和跨源场景准备回退路径，这样 storage 事件才适合承担轻量的标签页状态同步。