Cherry Studio 中的 localStorage 版本化与数据最小化实践client-localstorage-schema 规则详解【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 的渲染进程大量依赖 localStorage 做跨窗口 UI 状态持久化与旧版本数据迁移稍有不慎就会出现键名冲突、旧 schema 崩溃或敏感字段落盘。本文基于仓库内置的 client-localstorage-schema.md 规则Vercel React 最佳实践技能集中的client-客户端数据获取类规则影响级别 MEDIUM展开讲解为 localStorage 键加版本前缀 只存最小字段两个核心做法并结合 Cherry Studio 渲染进程的 CacheService 持久层与 legacyV1BrowserData.ts 迁移清理模块看这些规范在真实工程里如何落地。读完后你将掌握localStorage 异常捕获的必要性、键版本化与 v1→v2 迁移的标准写法、字段裁剪策略以及多窗口应用中如何避免整包落盘的存储膨胀问题。一、规则定位为什么 localStorage 需要 schema 治理该规则在 SKILL.md 中被归入第 4 类Client-Side Data Fetching客户端数据获取优先级 MEDIUM-HIGH规则名client-localstorage-schema一句话描述为Version and minimize localStorage data为 localStorage 数据加版本并做最小化。规则给出的三大收益是通过版本化实现 schema 演进键名携带版本号后旧版本数据可以识别、迁移或安全忽略而不会和新版本数据互相污染减小存储体积只序列化 UI 真正需要的字段而不是把整个接口对象 dump 进本地防止敏感数据落盘token、PII个人身份信息、内部开关字段不会被顺手写进 localStorage造成隐私与安全暴露面。规则标注的影响面说明为 prevents schema conflicts, reduces storage size防止 schema 冲突、减少存储占用这与浏览器端两个现实问题对应一是 localStorage 是按 origin 共享的扁平键值空间不同功能模块、不同版本应用写的键很容易撞名二是 localStorage 的容量与可用性都不是永远可用的——规则明确要求所有 getItem/setItem 调用都必须包在 try-catch 中因为在隐身/隐私模式Safari、Firefox、配额超限quota exceeded或存储被禁用时这些调用会直接抛异常。二、反例无版本、全量存储、无错误处理规则先给出了典型错误写法// No version, stores everything, no error handling localStorage.setItem(userConfig, JSON.stringify(fullUserObject)) const data localStorage.getItem(userConfig)这行代码踩了三个坑键没有版本前缀。userConfig是一个裸键一旦某天把配置结构从{ darkMode, lang }改成{ theme, language }旧数据读回来就是错误形状代码要么静默拿到 undefined 字段要么在运行时抛错把整个服务端对象存下来。fullUserObject里可能有 20 多个字段其中大部分 UI 根本用不到白白放大 localStorage 占用还可能把不该持久化的字段令牌、内部标记一起存了没有任何异常处理。setItem一旦因隐私模式或配额超限抛QuotaExceededError整个调用栈会被打断。三、正例版本前缀 类型约束 全链路 try-catch规则给出的正确实现分为三层写入、读取、迁移。3.1 带版本前缀的读写封装const VERSION v2 function saveConfig(config: { theme: string; language: string }) { try { localStorage.setItem(userConfig:${VERSION}, JSON.stringify(config)) } catch { // Throws in incognito/private browsing, quota exceeded, or disabled } } function loadConfig() { try { const data localStorage.getItem(userConfig:${VERSION}) return data ? JSON.parse(data) : null } catch { return null } }要点拆解版本是编译期常量VERSION v2拼接进键名得到userConfig:v2。升级 schema 时只需递增常量并配套迁移函数新键与旧键物理隔离写入函数的参数类型直接约束了存储形状——saveConfig只接受{ theme: string; language: string }从类型层面杜绝了把fullUserObject塞回来的可能这是最小化在 TypeScript 里的落地方式写失败静默降级catch 内注释直接说明了三种触发场景隐私浏览、配额超限、存储被禁用读失败返回 null 而不是抛出。JSON.parse本身也可能因为数据损坏而抛错所以 parse 必须包含在同一个 try 块内。3.2 v1 → v2 迁移函数// Migration from v1 to v2 function migrate() { try { const v1 localStorage.getItem(userConfig:v1) if (v1) { const old JSON.parse(v1) saveConfig({ theme: old.darkMode ? dark : light, language: old.lang }) localStorage.removeItem(userConfig:v1) } } catch {} }迁移的完整模式是四步读旧版本键 → 字段映射注意这里字段名也变了darkMode: boolean映射为theme: dark | lightlang映射为language→ 用新版saveConfig写出 →removeItem删除旧键。整个过程再套一层 try-catch因为旧值可能已经损坏parse 抛错迁移失败不能阻断应用启动。这个读旧键、映射、写新键、删旧键的模式正是版本化存储的核心价值schema 变更从破坏性事件变成了可编排的一次性任务。3.3 字段最小化服务端响应只存 UI 需要的部分规则第三个示例进一步强调服务端响应也要裁剪后再存// User object has 20 fields, only store what UI needs function cachePrefs(user: FullUser) { try { localStorage.setItem(prefs:v1, JSON.stringify({ theme: user.preferences.theme, notifications: user.preferences.notifications })) } catch {} }即使FullUser有 20 多个字段落盘的也只需要一个显式构造的投影对象{ theme, notifications }。显式构造而不是解构拷贝还有一个好处将来接口新增字段不会自动进入 localStorage存储形状保持稳定、可预期。四、Cherry Studio 的落地类型化 persist 缓存层Cherry Studio 的渲染进程Electron 应用面对的问题比单页网站更复杂多个窗口主窗口、迁移窗口、迷你应用窗口共享同一个 origin 的 localStorage且应用经历了 v1Redux persist Dexie到 v2DataApi 分层缓存的大版本重构。规则里的三个要点——schema 约束、版本/键治理、异常兜底——在 CacheService.ts 的 persist 层中都有对应工程实现。4.1 用单一持久键 白名单 schema 替代散键规则建议每个逻辑实体一个带版本的键。Cherry Studio 的 persist 层选择了另一种同样合规的组织方式整个持久化状态只占用一个localStorage 键const STORAGE_PERSIST_KEY cs_cache_persist所有 UI 持久状态标签页、侧栏宽度、用量统计页筛选条件、截图标注样式等都收敛进这一个键对应的 JSON 对象中。真正防冲突的不是键名版本前缀而是编译期 schema 白名单cacheSchemas.ts 中定义了RendererPersistCacheSchema每个键都必须形如namespace.sub.key_name正则约束^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)例如ui.sidebar.width、settings.usage.chart_type、ui.tab.active_tab_id并且每个键都声明了精确的值类型与默认值DefaultRendererPersistCache。setPersist/getPersist是泛型方法键不在 schema 里就编译不过——这相当于把规则中只存最小字段的要求从运行时约束提升成了编译期约束想存一个新字段必须先改 schema、声明类型和默认值。4.2 加载与保存schema 过滤、大小告警、防抖写盘loadPersistCache()的读取逻辑与规则中读失败返回空值的兜底策略完全一致还多了一步 schema 过滤const data JSON.parse(stored) // Only load keys that exist in schema, overriding defaults const schemaKeys Object.keys(DefaultRendererPersistCache) as RendererPersistCacheKey[] for (const key of schemaKeys) { if (key in data) { this.persistCache.set(key, data[key]) } }这段代码正是版本化思想在 blob 存储下的等价物旧版本或已废弃的键读回来后会被静默丢弃不在 schema 中即忽略而缺失的键回落到DefaultRendererPersistCache的默认值随后savePersistCache()用defaults 有效键重写 localStorage完成一次隐式的数据清理。整个 try 块失败时的处理也是规则要求的形态——删除损坏数据、回退默认值、记录日志} catch (error) { logger.error(Failed to load persist cache:, error as Error) localStorage.removeItem(STORAGE_PERSIST_KEY) // Fallback to defaults only logger.debug(Fallback to default persist cache values) }写入侧则体现了最小化 容量意识savePersistCache()会把整个 persist 状态序列化为一个 JSON 字符串超过 2MB 时打 warn 日志提醒可能影响性能、可能丢数据schedulePersistSave()以 350ms 防抖合并高频写入PERSIST_SAVE_DEBOUNCE_MS 350并在beforeunload时若persistDirty为真则强制落盘一次——这是对规则try-catch 包住 setItem之外Electron 多窗口场景下的补充工程手段。此外 persist 层通过 IPCbroadcastSync向其他窗口广播变更其他窗口只更新内存副本、不重复写 localStorage避免了多窗口并发写同一键的竞态。从源码结构看Cherry Studio 选择一个版本无关的固定键 schema 白名单 默认值表而非每个键加 :vN 后缀本质上是把规则里的版本治理从键名维度转移到了 schema 维度schema 就是当前版本的声明schema 之外的数据天然被视为旧版本产物并被清理。对开发者而言两种方案解决的是同一问题——旧数据不能污染新逻辑。4.3 真实迁移案例legacyV1BrowserData.ts规则示例中的migrate()是一个函数而在 Cherry Studio 里v1 → v2 迁移是一整个模块legacyV1BrowserData.ts 负责识别、计量和清除旧版 v1 应用留在浏览器存储里的数据其结构与规则的四步迁移模式高度同构const LEGACY_DATABASE_NAME CherryStudio const LEGACY_PERSISTED_STATE_KEY persist:cherry-studio const LEGACY_CLEANUP_RETRY_MARKER_KEY cherry-studio:legacy-v1-cleanup-pending export const LEGACY_LOCAL_STORAGE_KEYS [ LEGACY_PERSISTED_STATE_KEY, onboarding-completed, memory_currentUserId, privacy-popup-accepted, language, openai_alert_closed, migration:theme_mode, ai302_token, tokenLanyunToken, mcprouter_token, tokenflux_token ] as const几个值得注意的实现细节先探测旧版本标记再动手。hasLegacyV1Marker()检查 v1 的持久化状态键或清理重试标记是否存在同样包在 try-catch 里失败时记日志并返回 false确认这台机器上真的来过 v1 数据才进入清理流程白名单精确枚举待清理键而不是Object.keys(localStorage)全量删除——全量删除会误伤同 origin 下其他来源写入的数据白名单才是安全的清理边界删除逐键捕获。clearLegacyV1BrowserData()中每个removeItem独立 try-catch单个键失败只计failedItems最后聚合出cleared / partial / failed / not_found状态供设置页展示重试标记键cherry-studio:legacy-v1-cleanup-pending在清理开始时写入、成功cleared/not_found后由finalizeLegacyV1Cleanup删除等价于给一次性迁移任务加了 checkpoint——这正是规则迁移模式删旧键步骤的工程强化版。另外v2 迁移窗口里的 LocalStorageExporter.ts 展示了另一面迁移导出时同样只遍历白名单MIGRATION_LOCAL_STORAGE_KEYS当前为[onboarding-completed]定义于 types.ts逐个getItem→ 尝试JSON.parse失败保留原始字符串→ 通过 IPC 追加写入导出文件。读旧数据、类型探测、宽容降级与规则正例中的读取封装是同一套防御性读法。五、规则要点速查与适用前提把规则与 Cherry Studio 的实现对照可以提炼出如下速查表要点规则要求Cherry Studio 对应实现键版本化userConfig:${VERSION}前缀单一持久键cs_cache_persist schema 白名单 充当版本声明schema 外键加载即丢弃字段最小化只存 UI 需要的投影字段RendererPersistCacheSchema逐键声明类型与默认值编译期禁止未声明字段迁移读旧键 → 映射 → 写新键 → 删旧键legacyV1BrowserData.ts 白名单探测/计量/清理 重试标记 checkpoint异常兜底所有 get/set 包 try-catch隐私模式、配额超限、禁用读写/清理全链路 try-catch 日志 默认值回退容量意识减小存储体积persist 状态超 2MB 告警、350ms 防抖写盘、getStats()估算字节数适用前提需要说明本规则面向浏览器端 Web StoragelocalStorage/sessionStorage。Electron 的渲染进程同样适用——Cherry Studio 的 persist 缓存、迁移导出与旧数据清理都运行在渲染进程的 Web Storage 上而主进程的持久化走的是独立通道cacheSchemas.ts 中MainPersistCacheSchema的注释明确说明主进程 persist 存于自己的 JSON 文件、不与渲染进程同步不受 localStorage 配额与隐身模式限制也不适用本规则。最后回到规则的一句话总结Add version prefix to keys and store only needed fields。无论是 Cherry Studio 用固定键 类型化 schema实现的隐式版本化还是规则示例里键名 :vN的显式版本化本质都是同一件事——让旧数据可识别、可迁移、可安全删除让新数据形状固定、体积最小、不碰敏感字段并保证任何存储调用失败都不会击穿应用。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考