localStorage操作必须用setItem()/getItem()，存对象需JSON序列化，注意5MB限制、无痕模式兼容性、storage事件仅跨tab触发、无自动过期机制需手动实现TTL。

localStorage.setItem() 和 getItem() 是最常用的操作入口

存取字符串数据必须用 setItem() 和 getItem()，不能直接赋值或读取属性。比如 localStorage.myKey = "value" 虽然看似生效，但实际无法触发 StorageEvent，且在某些浏览器隐私模式下会静默失败。

实操建议：

• 始终用 JSON.stringify() 存对象，用 JSON.parse() 读取，否则得到的是 [object Object]
• 写入前检查是否支持：用 typeof localStorage !== 'undefined'，避免 Safari 无痕模式报 SecurityError
• 注意大小限制：多数浏览器约 5MB，超限会抛 QuotaExceededError

const user = { id: 123, name: 'Alice' };
try {
  localStorage.setItem('user', JSON.stringify(user));
  const saved = JSON.parse(localStorage.getItem('user'));
  console.log(saved.name); // 'Alice'
} catch (e) {
  if (e.name === 'QuotaExceededError') {
    console.error('localStorage 已满');
  }
}

删除缓存要用 removeItem() 或 clear()，别用 delete

delete localStorage.key 完全无效，也不会报错 —— 这是常见误操作。真正生效的只有 removeItem()（删单个）和 clear()（清空全部）。

使用场景差异：

• removeItem('token')：退出登录时删凭证，保留用户偏好等其他键
• clear()：调试时快速重置，生产环境慎用，可能误删关键配置
• 没有批量删除 API，如需删多个键，得先 Object.keys(localStorage) 遍历过滤

监听 localStorage 变化只能靠 window.addEventListener('storage')

storage 事件**只在其他同源 tab 或 iframe 中修改 localStorage 时触发**，当前页面调用 setItem() 不会触发自身监听器 —— 这点极易误解。

关键限制：

• 事件对象 event.key、event.newValue、event.oldValue 仅提供变更信息，不包含完整 state
• 无法监听到 clear() 后的具体哪些键被删了，event.key 为 null
• 私有窗口/无痕模式下事件可能不触发，别依赖它做核心状态同步

window.addEventListener('storage', (e) => {
  if (e.key === 'auth_token') {
    if (!e.newValue) {
      console.log('token 已被其他页面清除');
      // 触发登出逻辑
    }
  }
});

localStorage 没有过期机制，得自己加时间戳字段

原生 localStorage 不支持 TTL（time-to-live），所谓“自动过期”必须手动实现。常见做法是在存值时附带 expires 时间戳，读取时比对。

容易踩的坑：

• 用 Date.now() 存毫秒数，别用 new Date().toString() —— 字符串解析慢且易错
• 读取时发现过期，应立刻 removeItem()，否则下次读还是旧值
• 服务端下发的 token 等敏感数据，别只靠前端时间判断过期，必须配合后端校验

function setWithExpiry(key, value, ttlMs) {
  const item = {
    value,
    expiry: Date.now() + ttlMs
  };
  localStorage.setItem(key, JSON.stringify(item));
}

function getWithExpiry(key) {
  const itemStr = localStorage.getItem(key);
  if (!itemStr) return null;
  const item = JSON.parse(itemStr);
  if (Date.now() > item.expiry) {
    localStorage.removeItem(key);
    return null;
  }
  return item.value;
}