localStorage.setItem()仅支持字符串，存对象需JSON.stringify()序列化，取值须判null并try-catch容错解析；键名应统一前缀，敏感数据慎存，大文本需评估容量。

localStorage.setItem() 是实现浏览器端数据持久化的最直接方式，但它不是“存进去就完事”，关键在于写得安全、读得可靠、用得合理。数据能跨页面、跨重启保留，但前提是操作规范，否则容易丢失、报错或读出 null。

只接受字符串：对象和数组必须 JSON 转换

localStorage 本质只支持字符串键值对。直接传入对象、数组、布尔或数字，会被自动 toString()，结果往往是 [object Object] 或 true 这类不可逆的字符串，后续无法还原。

• 存储前用 JSON.stringify() 序列化：

  const user = { name: '张三', score: 95 };  
  localStorage.setItem('userInfo', JSON.stringify(user));

• 读取后用 JSON.parse() 解析：

  const saved = localStorage.getItem('userInfo');  
  const userObj = saved ? JSON.parse(saved) : null;

• 注意：如果 key 不存在，getItem() 返回 null，直接 JSON.parse(null) 会报错，务必先判断

加 try-catch 防止意外中断

两种典型错误会打断执行：一是超出容量（通常 5–10 MB），抛出 QuotaExceededError；二是用户禁用本地存储或处于无痕模式，可能触发 DOMException。

• 写入时建议包裹异常处理：

  try {  
    localStorage.setItem('theme', 'dark');  
  } catch (e) {  
    console.warn('本地存储失败:', e.name);  
    // 可降级到内存缓存或提示用户  
  }

• 读取虽少报错，但返回 null 是常态，别假设一定有值

遵循同源策略，注意作用域边界

localStorage 数据绑定在协议 + 域名 + 端口上。比如 https://a.com 存的数据，http://a.com、https://sub.a.com 或 https://a.com:8080 都无法访问。

page-agent 浏览器控制（CDP）

使用 page-agent CLI（CDP）控制浏览器；CLI只能通过 GitHub Release 的 .tgz 安装，npm 官方包暂未发布。

下载

• 同一站点多个页面（如 /home、/profile）可共享数据，适合保存主题、语言、搜索历史等全局状态
• 开发时注意本地预览地址（如 file://）不支持 localStorage
• 测试跨子域需求时，需改用其他方案（如 postMessage + iframe 配合 cookie）

明确“持久”的真实含义：不等于永久

它不会因关页、关机、重装系统而丢失，但以下情况数据会清空：

• 用户主动清除浏览数据（勾选“Cookie 及网站数据”）
• 使用无痕/隐私窗口，关闭即销毁
• 浏览器设置中禁用第三方 Cookie 或本地存储
• 代码调用 localStorage.clear() 或 removeItem()

因此，敏感信息（如 token、密码）不应单独依赖 localStorage；重要业务数据应配合服务端备份。