localstorage是同步的，所有操作会立即阻塞javascript主线程直至读写完成；localforage等异步存储则通过promise避免阻塞，适合大数据量场景。

localStorage 是同步的，所有操作会立即阻塞 JavaScript 主线程，直到读写完成；而异步存储（如 localForage、IndexedDB）不阻塞主线程，通过 Promise 或回调通知操作结果。

localStorage 的同步特性

调用 setItem 或 getItem 时，代码会停在这一行，等浏览器完成硬盘写入或读取后才继续执行。这意味着：

• 无需处理 Promise 或回调，写法直观，适合小量、简单数据（如用户偏好、开关状态）
• 大量数据（比如存一个几 MB 的 JSON 字符串）可能造成界面卡顿、动画掉帧
• 无法在 Web Worker 中直接使用，因为它是绑定在 window 上的同步 API
• 即使底层硬盘 I/O 本身是异步的，浏览器为简化 API 设计，强制封装成同步语义

异步存储的典型代表

localForage 和 IndexedDB 是主流的异步替代方案，它们把存储操作交给后台线程或数据库引擎处理：

ClawUsage Windows Hardlock

通过聊天（Telegram / 飞书）执行本地 `clawusage` 监控命令。当用户输入 `/clawusage ...`，或提出“查看 Codex 用量”、“开启/关闭自动…”等请求时触发使用。

下载

• localForage 自动降级：优先用 IndexedDB，不支持时回退到 WebSQL，最后 fallback 到 localStorage（但所有方法统一返回 Promise）
• IndexedDB 原生支持结构化数据（对象、二进制），读写都必须用事务，天然异步
• 操作不会卡住 UI，适合缓存列表页数据、离线日志、图片 blob 等中大型内容
• 需要显式处理错误和完成逻辑，例如用 await localforage.setItem(key, value) 或 .then()

什么时候该选同步，什么时候该选异步？

关键看数据规模和用户体验要求：

• 存 token、主题色、折叠状态等轻量键值对 → localStorage 足够，简单可靠
• 存用户上传的多张图片、历史搜索记录数组、未发送的聊天消息队列 → 异步方案更稳妥
• 需要在页面加载初期就依赖本地数据渲染 → 同步读取可减少等待，但要注意避免大体积读取拖慢首屏
• 涉及频繁读写或并发操作（如多个 tab 同时更新）→ 异步方案通常有更完善的冲突处理或事务机制

微信小程序与浏览器的差异提醒

小程序的 wx.setStorageSync 类似于浏览器的 localStorage，是同步的；而 wx.setStorage 是异步的。这种命名明确区分了行为，避免了浏览器中仅靠 API 名称难以判断同步性的困惑。开发跨端应用时，需注意不同平台对“同步/异步”的默认约定并不一致。