[!info] related notes

• 所属 MOC: 前端基础 MOC
• 上位总览: 浏览器客户端存储
• 对比: Cookie vs LocalStorage
• 调试: DevTools Storage 调试

Web Storage API

一句话定义

Web Storage API 只包含两种同步键值存储：

• localStorage
• sessionStorage

它们都：

• 以 string key/value 为核心；
• 不会自动随 HTTP 请求发送；
• 使用同步 API；
• 受 origin / browsing context 边界影响。

Cookie、IndexedDB、Cache Storage 都不是 Web Storage API。

localStorage

localStorage 的目标是：

在同 origin 下跨 reload / navigation 保留简单键值数据。

典型用途：

• theme；
• UI preference；
• 少量 feature flag；
• 非敏感、低频配置。

示例：

localStorage.setItem('theme', 'dark')
const theme = localStorage.getItem('theme')
localStorage.removeItem('theme')

值最终是字符串。

对象需要显式序列化：

localStorage.setItem('prefs', JSON.stringify({ compact: true }))
const prefs = JSON.parse(localStorage.getItem('prefs') ?? '{}')

sessionStorage

sessionStorage 的 API 形状与 localStorage 类似，但生命周期和隔离范围不同。

它更接近：

当前 top-level browsing context / tab session 的键值存储。

常见用途：

• 当前 tab 的临时表单状态；
• 当前 tab 的流程状态；
• 不希望长期持久化的 UI 数据。

它不会因为 SPA 内部 route change 自动清空。

两者真正的差异

维度	localStorage	sessionStorage
API	同步 key/value	同步 key/value
数据格式	string	string
reload 后	保留	保留
普通 navigation	保留	同 tab session 内保留
tab/session 结束	通常继续存在	通常结束
自动随 HTTP 发送	否	否

不要把差异简化成“一个永久、一个页面刷新就没了”。

同步 API 的成本

Web Storage 是同步 API。

所以高频大量读写可能阻塞主线程。

如果开始存：

• 大量记录；
• 复杂对象；
• 离线数据集；
• 需要索引查询的数据；

更应该考虑 浏览器客户端存储 中的 IndexedDB，而不是继续扩大 localStorage。

安全边界

页面 JavaScript 能直接读取 Web Storage。

因此如果页面发生 XSS，攻击代码通常也可以读取这些值。

所以不要把：

• password；
• 高价值长期 credential；
• 不希望页面 JS 读取的 secret；

仅因为“方便”就放进 localStorage/sessionStorage。

Credential 方案要结合 HttpOnly Cookie、Token 生命周期和整体认证架构判断。

Storage Event

同 origin 的其他 browsing context 修改 localStorage 时，页面可以通过 storage event 获知变化。

它适合做简单跨 tab 同步信号，但不是完整事务系统。

不要依赖它实现复杂强一致状态。

Web Storage 与 Browser Storage 的关系

Browser Client Storage
├─ Cookie
├─ Web Storage
│  ├─ localStorage
│  └─ sessionStorage
├─ IndexedDB
└─ Cache Storage

所以：

Web Storage 是浏览器客户端存储体系中的一个子集。

学习检查

1. Web Storage API 到底包含哪些对象？
2. localStorage 与 sessionStorage 的核心差异是什么？
3. 为什么 sessionStorage 不会在普通 SPA route change 后自动消失？
4. 为什么 Web Storage 不适合大量高频数据？
5. Cookie 与 Web Storage 最重要的网络行为差异是什么？
6. XSS 为什么会直接影响 Web Storage 中 credential 的安全性？
7. 给主题设置、当前 tab 表单草稿、大量离线任务三种数据分别选择存储方式。