Web storage 事件为什么只通知其他文档

我第一次用 storage 事件做多标签页状态同步时，最容易误判的一点是：在当前页面执行 localStorage.setItem()，当前页面自己的监听器不会收到事件。这个行为不是监听器失效，而是 Web Storage 的事件语义本来就把“修改者”和“其他观察者”分开了。

一句话结论：storage 事件只通知共享同一存储区的其他文档，不通知发起修改的文档。localStorage 通常可以把变化传给同源的其他标签页；sessionStorage 的范围则收缩到同一顶层浏览上下文里的同源 iframe。

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

同页不触发，关键在于谁修改了存储区

一个文档既可以写入存储，也可以监听存储变化，但事件接收对象不是写入动作所在的那个 Window。对 localStorage 来说，当前标签页写入后，其他同源文档才有机会收到 StorageEvent。

因此下面这段代码的监听器不会因为本页的 setItem() 自己打印日志：

window.addEventListener('storage', (event) => {
  // 这里只处理其他文档发来的存储变化。
  console.log(event.key, event.oldValue, event.newValue);
});

// 当前文档负责写入，但不会收到自己这次写入产生的 storage 事件。
window.localStorage.setItem('theme', 'dark');

这条规则让“写入后立即更新当前界面”和“通知其他页面”成为两个明确动作。当前页面应直接更新自己的状态；其他页面则通过事件补上同步。

localStorage 适合做同源标签页同步

localStorage 按 origin 共享。把同一个站点打开到两个标签页时，一个标签页修改键值，另一个标签页可以监听变化。监听器不应假设所有变化都是同一种更新，最好先判断 key，再把字符串值解析成业务状态。

window.addEventListener('storage', (event) => {
  // 只接收登录主题这一类业务键，避免误处理其他模块的写入。
  if (event.key !== 'theme') return;

  // newValue 为 null 通常表示该键被删除，界面应回到默认主题。
  const nextTheme = event.newValue ?? 'light';
  document.documentElement.dataset.theme = nextTheme;
});

function changeTheme(theme) {
  // 先更新当前文档，再让其他同源文档通过 storage 事件跟随。
  document.documentElement.dataset.theme = theme;
  window.localStorage.setItem('theme', theme);
}

这里的 event.url 可以帮助记录发生写入的文档地址，storageArea 表示对应的存储对象。它们适合做诊断信息，但不要把事件当作可靠消息队列：事件只适合传递“状态发生了变化”的提示，页面仍应从 localStorage 重新读取完整状态。

localStorage 和 sessionStorage 的共享范围不同

两者都属于 Web Storage，但共享边界不一样。localStorage 的存储区按 origin 组织，同源的其他标签页可以看到同一份数据；sessionStorage 还受顶层浏览上下文限制，同源 iframe 可以共享所在标签页的会话存储，但另一个标签页不在同一顶层上下文中。

这也决定了事件能传到哪里：监听器必须位于共享该存储区的其他文档中。只打开另一个标签页测试 sessionStorage，通常不会得到和 localStorage 一样的结果。

StorageEvent 的字段和删除边界

处理事件时最有用的字段通常是 key、oldValue、newValue、url 和 storageArea。调用 setItem() 时，newValue 是写入后的字符串；调用 removeItem() 时，newValue 会是 null。调用 clear() 时，key 也会是 null，不能把它当成普通键名处理。

window.addEventListener('storage', (event) => {
  // clear() 没有单独的键名，先区分“清空全部”和“更新单键”。
  if (event.key === null) {
    resetCachedPreferences();
    return;
  }

  // 删除键值时 newValue 为 null，交给统一的缺省值逻辑处理。
  applyPreference(event.key, event.newValue);
});

如果当前页面也需要响应自己的修改，不要等待 storage 事件。把更新界面的函数抽出来，在写入前后显式调用；跨文档同步则保留事件监听器。这样同页行为和跨页行为都由清晰的入口负责。

把它用在合适的同步场景

这个事件适合主题切换、偏好设置、轻量的跨标签页状态提醒等场景。它不适合传递必须逐条消费的指令，也不适合替代需要确认、重试和顺序保证的通信机制。若页面之间需要更明确的消息语义，可以根据场景考虑其他浏览器通信 API。

排查“为什么没收到事件”时，按这三个问题看最快：

• 写入和监听是否来自两个不同的文档，而不是同一页面自写自收？
• 两边是否具有相同 origin，使用的是否是同一种存储区？
• 如果用的是 sessionStorage，监听文档是否仍在同一顶层浏览上下文？

相关问题

storage 事件能在同一个页面里通知另一个组件吗？不能把它当作同页组件事件。当前文档的写入不会触发当前文档的 storage 监听器，同页组件应使用自己的状态管理或显式函数调用。

为什么 localStorage 监听到了，但 sessionStorage 没有？最常见原因是测试页面位于不同标签页。sessionStorage 的事件范围受同一顶层浏览上下文限制，另一个标签页不属于同一个上下文。

收到 storage 事件后应该直接使用 newValue 吗？可以把它作为轻量提示，但更稳妥的做法是按键重新读取当前存储状态，并处理值被删除或全部清空的情况。

记住这条边界即可：写入者负责更新自己，其他共享存储区的文档负责接收 storage 事件；能否收到，先看存储区的共享范围，再看监听器是不是位于“另一个文档”。