Web Storage键名冲突是同源环境下必然风险，需通过统一前缀+语义化命名、封装命名空间存储类、结构合并单键管理及工程化约束四层机制系统性防护。
Web Storage 键名冲突不是小概率事件，而是同源环境下必然存在的风险。只要多个脚本（包括你自己不同模块、第三方 SDK、微前端子应用）共用同一个 localStorage，就可能因键名重复导致数据覆盖、逻辑错乱甚至安全问题。预防的核心不是“尽量不重名”，而是建立可落地、可约束、可验证的隔离机制。
统一前缀 + 语义化命名
这是最基础也最关键的防线。所有键名必须带前缀，且前缀需体现项目、版本和模块三层信息：
- ✅ 推荐格式：
${project}_${version}_${module}_${key}，例如crm_v2_user_theme、smart_admin_app1_token - 避免仅用通用词（如
theme、config）或缩写（如usr_tok），它们不可读、难追溯、易撞车 - 前缀应在项目级常量文件中定义（如
local-storage-key-const.ts），所有业务代码只引用常量，禁止硬编码字符串 - 微前端场景下，前缀必须包含子应用唯一标识（如
app1或payment-fe），不能只靠“app_”这种模糊前缀
封装命名空间存储类
不直接调用 localStorage.setItem()，而是通过封装类自动注入前缀与类型处理：
- 实例化时传入模块名：
const cartStorage = new NamespacedStorage('cart')，后续set('items', [...])实际存为myapp_v3_cart_items - 内置 JSON 自动序列化/反序列化，避免手动
JSON.stringify()漏写或报错 -
clear()方法只清除本命名空间下的键（通过key.startsWith(prefix)筛选），不误删其他模块数据 - 支持运行时校验：读取时检查是否存在
__ns字段，匹配预期命名空间再使用，防止被非本系统数据污染
结构合并 + 单键管理
对强关联的小型状态集，优先合并为单个对象存储，而非分散多个键：
- 例如用户界面偏好：
localStorage.setItem('user_ui_state', JSON.stringify({ theme: 'dark', lang: 'zh-CN', sidebarCollapsed: false })) - 优势在于避免并发更新导致状态撕裂（比如一个脚本改了
theme，另一个同时改了lang，中间状态不一致） - 适合低频整体更新的配置类数据；高频独立更新字段（如计数器、实时心跳）仍建议单键存储
- 注意控制单个值大小，避免接近浏览器 5–10MB 限制
工程化约束与运行时防护
靠人自觉不可靠，必须嵌入开发与发布流程：
- ESLint 规则：禁止出现
localStorage.setItem('xxx')字面量调用，只允许通过常量或封装类访问 - CI 扫描：构建阶段检查所有子应用是否导入并使用统一键名常量模块
- 开发环境控制台警告：检测到未加前缀的 localStorage 操作，立即输出提示并堆栈
- 异常降级：捕获
QuotaExceededError后提示用户清理缓存，或 fallback 到sessionStorage存临时状态
