cal.diy 前端性能优化实战用内存 Map 缓存 localStorage / sessionStorage / Cookie 的同步读取Vercel js-cache-storage 规则【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy浏览器存储 API 读取是 React / Next.js 应用中极易被忽略的隐藏性能瓶颈。本文将讲解 cal.diy 仓库所采纳的 js-cache-storage 规则为什么localStorage、sessionStorage、document.cookie的每次读取都是“昂贵 I/O”以及如何用模块级Map把同步存储读取降为内存读取并正确处理跨标签页与服务端写 Cookie 时的缓存失效。读完你可以在 cal.diy 及任何 Next.js/React 项目中把这一条可落地的优化写进工具函数、事件处理器与组件逻辑。为什么缓存浏览器存储读取同步 API 背后的真实开销很多开发者把localStorage.getItem()当成普通内存变量读取但它的成本远高于直觉同步阻塞Web Storage 与document.cookie的读写是同步 API会直接阻塞主线程期间任何渲染、事件、布局都无法推进。底层序列化与磁盘 I/O每次读取都需要从存储区取出字符串并解析。浏览器通常还要维持存储区的跨标签页一致性一次简单的getItem背后可能包含磁盘读取与进程间同步。调用次数与成本线性放大若在热门函数、渲染路径或事件回调里反复读取同一 key成本随调用次数线性累积。这也是 SKILL.md 将其归入第 7 类JavaScript Performance前缀js-并标注影响等级为LOW-MEDIUM、核心收益为reduces expensive I/O降低昂贵的 I/O的原因——它不如消除请求瀑布waterfall或压缩包体那样显性但在高频路径上叠加起来同样可观。反例每次调用都触碰真实存储规则给出的“错误示范”非常直白function getTheme() { return localStorage.getItem(theme) ?? light } // Called 10 times 10 storage reads这段代码的问题是函数体没有任何记忆getTheme()被调用 10 次就会发生10 次真实的同步存储读取。如果它被多个组件、多个事件回调、热更新逻辑共享调用存储读取次数会进一步膨胀。正例用模块级 Map 做“读穿 写穿”缓存规则推荐的方案是使用模块作用域的Mapstring, string | null作为一次性缓存层const storageCache new Mapstring, string | null() function getLocalStorage(key: string) { if (!storageCache.has(key)) { storageCache.set(key, localStorage.getItem(key)) } return storageCache.get(key) } function setLocalStorage(key: string, value: string) { localStorage.setItem(key, value) storageCache.set(key, value) // keep cache in sync }实现要点在于两条读写路径的对称性读穿read-throughgetLocalStorage首次访问某 key 时读一次真实存储并把结果写入Map之后同一 key 的全部读取都命中内存。同 key 读取 N 次存储只被访问 1 次。写穿write-throughsetLocalStorage在写入真实存储的同时更新缓存保证缓存不出现陈旧值。这是最容易遗漏的一步——只缓存读取而不在写入时同步缓存与存储会很快产生不一致。为什么用 Map 而不是 React Hook要“到处都能用”规则特别强调缓存应建立在普通模块级数据结构上而不是 React Hook 或组件状态Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.原因很实际Hook 只能在组件顶层调用无法在纯工具函数、定时器、全局事件监听器、非 React 渲染流程中复用组件状态的生命周期随挂载/卸载而销毁缓存会频繁冷启动起不到跨调用共享的效果模块级Map是进程内的单例任何模块、任何调用方共享同一份缓存同时与框架解耦。因此这条规则的最佳落点是模块级工具函数层而非某个组件内部。Cookie 读取同样需要缓存document.cookie更特殊它是一整条字符串读取时浏览器会把它序列化拼接给你而你每次都要split解析。规则给出的做法是把解析结果整体缓存为Recordstring, string首次解析后所有getCookie都只查内存对象let cookieCache: Recordstring, string | null null function getCookie(name: string) { if (!cookieCache) { cookieCache Object.fromEntries( document.cookie.split(; ).map(c c.split()) ) } return cookieCache[name] }它比逐条缓存更聪明Cookie 的读取天然是“整串读再切分”所以把整个解析结果缓存起来而非按 name 缓存一次解析服务所有后续查询。需要注意的是split(; )假定浏览器返回格式以分号加空格分隔边界值处理见下文“注意事项”。缓存失效跨标签页与外部写入必须处理任何缓存都伴随一个核心问题谁来宣告缓存失效规则给出了两条必须响应的事件window.addEventListener(storage, (e) { if (e.key) storageCache.delete(e.key) }) document.addEventListener(visibilitychange, () { if (document.visibilityState visible) { storageCache.clear() } })失效场景与应对逻辑失效来源触发事件处理策略另一标签页/同源另一窗口修改同一存储window的storage事件携带key精确delete对应 key保留其余缓存页面切回前台期间可能有外部改动如服务端通过 HTTP 响应头设置 Cookie、其他标签页写入后返回document的visibilitychange且状态变为visible直接clear()全部缓存宁可重建不可陈旧关键认知storage事件只在“其他文档”修改存储时触发当前页面自己的setItem不会触发它——这正是写穿路径必须手动同步缓存的原因。而visibilitychange是兜底切回前台后重新从真实存储建立快照能覆盖所有“你不在场时发生的外部变更”。对 Cookie 缓存而言服务端写入的 Cookie 没有等价事件可听visibilitychange后重建或将cookieCache置回null就是最稳妥的兜底失效策略。如果你的应用逻辑中还有直接通过document.cookie ...绕过工具函数写入的地方记得也要同步重置cookieCache null否则会读到陈旧值。仓库实践印证cal.diy 中的存储读取与内存缓存该规则在 cal.diy本项目中不是空谈仓库里有多个贴近的实现可供对照学习。1. 安全包装packages/lib/webstorage.tswebstorage.ts 对localStorage/sessionStorage做了try/catch 安全包装。它解决的是规则文档未展开的边界问题——localStorage在受限环境下Chrome 隐身模式下的第三方上下文、存储配额超限、被禁用的 iframe直接访问会抛异常因此所有getItem/setItem/removeItem都被包进 try/catch异常时优雅降级读返回null、写静默忽略。这提醒我们做存储缓存层时底层读取函数本身应当是永不抛错的否则缓存函数第一次触碰存储就会把异常传染到整个调用链。2. 模块级内存缓存apps/web/lib/clock.tsclock.ts 是规则正例的仓库级变体它用模块级timeOptions对象在内存中保存 24 小时制与邀请人时区的当前值const timeOptions: TimeOptions { is24hClock: false, inviteeTimeZone: , }; const initClock () { // ... timeOptions.is24hClock !!getIs24hClockFromLocalStorage(); timeOptions.inviteeTimeZone localStorage.getItem(timeOption.preferredTimeZone) || CURRENT_TIMEZONE; };后续所有对外读函数is24h()/timeZone()都直接返回内存中的timeOptions字段见 clock.ts而写入侧set24hClock/setTimeZone也严格遵循“先写存储、再同步内存”的双写模式。这样时区/时钟偏好这种会被多处 UI 高频查询的状态只有初始化时才真正触碰localStorage。可见这条规则在工程上的完整形态就是“模块级内存状态 初始化读一次存储 每次写同步双写”不一定非要用泛化的 Map 封装。3. 组件侧读写apps/web/modules/auth/hooks/useLastUsed.tsxuseLastUsed.tsx 展示了“登录方式记忆”这类 UI 状态如何与存储同步useEffect中把last_cal_login从localStorage读入组件状态并在状态变化时setItem/removeItem回写。把它与本规则对照可以看出组件状态只是缓存的一层跨组件共享或非组件路径读取时仍需要回归到模块级 Map/内存缓存的方案。4. 订阅式存储封装apps/web/modules/bookings/hooks/useBookingsView.ts更进一步useBookingsView.ts 把“视图模式”等偏好封装成了独立的 localStorage store读取时先查内存并通过useSyncExternalStore让多个组件订阅同一份值localStorageStore.subscribe/getSnapshot写入时localStorageStore.notify()通知全部订阅者。这是“Map 缓存 React 响应式”的进阶版——同一份存储值只需真实读取一次其余全靠内存分发。注意事项与边界条件结合规则文档与仓库实践落地时还要留意以下边界Cache 值语义区分缓存 Map 的值类型是string | null其中null表示“真实存储中不存在该 key”。若不做区分一旦把“未缓存”与“缓存了 null”混淆has()判断就会失效导致每次都穿透到存储。多 key 批量失效如果同页面有多个功能共享一个缓存 Map写穿时务必保证每个写入口都经过封装函数避免直连localStorage.setItem绕过缓存。不适用场景对于一次性读取、写入频率极低的密钥、超长字符串或需要实时一致性的安全敏感数据缓存收益有限或带来陈旧风险应谨慎评估。规则针对的是同一值被高频反复读取的模式。SSR 前提本规则运行在客户端涉及window/document/localStorage。在 Next.js 服务端渲染路径直接引用这些 API 会报错——cal.diy 中工具函数普遍以“存在性判断”保护服务端调用例如 cookie.ts 的getCookie首先检查typeof document undefined即返回null。做缓存封装时同样要保证模块导入期不触碰浏览器 API只在函数被实际调用时才访问。Cookie 解析健壮性示例用; 与切分属于简写真实世界 Cookie 值可能包含。若需生产级解析应在缓存层之下先做正确解析处理首项、trim、只按第一个切分等再对解析结果做整体缓存。小结本条规则的一页速查症状同一localStorage/sessionStorage/document.cookiekey 在渲染或事件路径被反复同步读取。解法模块级Mapstring, string | nullCookie 则缓存整份Recordstring, string解析结果做读穿缓存所有写入路径同步更新缓存写穿。用普通数据结构而非 Hook让工具函数、事件处理器与组件共享同一缓存。必做失效处理监听storage事件按 key 删除、visibilitychange回到前台时全量清空服务端 Cookie 类外部写入依赖后者兜底。仓库对照js-cache-storage.md 规则原文、webstorage.ts受限环境安全包装、clock.ts模块级内存缓存实战、useBookingsView.ts订阅式 store 进阶。把“读一次、缓存多次、写入同步、切回前台重建”这四件事做对就能在 React 与 Next.js 应用中稳定消除这类隐蔽的重复 I/O让每一个高频读取的函数都变成纯内存操作。【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考