Web Storage键名需结构化:统一前缀+模块+版本+用途,避免冲突;强关联状态合并存为单对象;值中嵌入expiresAt实现TTL;运行时校验格式、容量与命名空间。

Web Storage 的键名不是“随便起个名字就行”,而是需要有明确的结构和约束。键名一旦冲突,后写入的数据会直接覆盖前一个,且这种问题往往在上线后才暴露,排查成本高、影响面广。核心原则是:每个键名必须能唯一标识所属模块、版本和用途。
统一前缀 + 模块标识
所有键名都应以项目或应用前缀开头,再拼接具体业务模块,避免裸键(如 theme、user)直接使用。前缀需具备可读性和排他性,不能只用缩写或通用词。
- ✅ 推荐:myapp_v3_cart_items、admin-panel_config
- ❌ 避免:cart(无项目标识)、cp_cfg(缩写歧义)、user_theme(缺版本,跨迭代易撞)
- 建议在入口文件定义常量,如 const STORAGE_PREFIX = "myapp_v3_",后续所有键名通过模板字符串生成
结构化数据统一存单键
多个强关联状态(如用户界面偏好)不应拆成多个键分别存储,而应合并为一个对象,只占一个键名。这样既减少冲突点,也避免并发更新导致状态不一致。
- 例如将主题、语言、通知开关打包为:myapp_v3_ui_state,值为 {"theme":"dark","lang":"zh-CN","notify":true}
- 读取时 JSON.parse(),更新时整对象覆盖,不手动修改子字段
- 不适用于高频独立变更的字段(如实时计数器),这类场景更适合服务端或 IndexedDB
嵌入时间戳或 TTL 字段
localStorage 本身无过期机制,但业务数据常有生命周期。单纯依赖人工清理不可靠,应在值中主动携带时效信息。
- 存入时附加 expiresAt 时间戳(毫秒),例如:{"data":..., "expiresAt": Date.now() + 7 * 24 * 60 * 60 * 1000}
- 读取时先校验 expiresAt 是否已过期,过期则自动清除并返回 null
- 也可用相对 TTL(如 "ttl": 604800),配合创建时间计算是否有效
运行时校验与降级处理
第三方脚本、旧版本残留数据、浏览器私密模式等都可能导致 localStorage 异常。不能假设环境干净,需增强鲁棒性。
- 写入前检查目标键是否存在,且值是否为预期 JSON 格式(避免覆盖非本意数据)
- 捕获 QuotaExceededError,提示用户清理缓存,或临时降级到 sessionStorage
- 关键数据加校验字段,如 "__ns": "myapp_v3",读取时验证该字段再使用,防止被其他系统误写










