持续缓存到底解决什么问题做客户端开发时间久了都会碰到一类很头疼的问题应用重启之后用户上次看到的页面状态没了图片从网络重新拉列表又要转圈加载数据甚至还要重新请求一遍。尤其在一些端侧资源密集的场景下比如资讯类应用的首屏快照、工具类应用的表单草稿、内容分发场景的离线列表每一次冷启动都意味着一次完整的资源重建。说白了我们缺的不是缓存而是一个“真正能用”的缓存。内存缓存很快但活不过进程被杀数据库缓存能用却太笨重文件缓存够灵活但自己手写管理又容易踩坑。这个项目的切入点非常直接做一个极简 API 的本地持久化缓存组件既能当普通 key-value 缓存用又支持磁盘文件落地还得有合理的溢出淘汰策略不至于把用户存储空间吃干净。而且它必须是纯 Flutter 实现底层通过统一平台通道接入鸿蒙这样 Flutter 业务侧完全不用关心宿主的差异。如果你正在做 Flutter 应用又恰好要适配鸿蒙系统那么这篇东西大概率是你能直接照着抄的作业。我按“思路拆解 → 鸿蒙适配路径 → 核心实现 → 秒开实战 → 问题排查”这条线往下讲尽量把每个关键决策背后的为什么都讲透。1. 缓存组件的整体设计与思路拆解1.1 为什么选文件缓存而不是数据库首先要明确一个前提不是所有数据都值得进数据库。像用户上次浏览的位置、接口返回的列表 JSON、图片的缩略图二进制这类数据的特点是“结构化程度低、生命周期短、丢失容忍度高”硬塞进数据库表里反而要维护表结构、序列化映射、数据库升级版本成本远大于收益。文件缓存走 key-value 路径本质上就是用文件系统的目录结构来模拟一个 Mapkey 经过哈希后作为文件名value 直接序列化成字节流写入文件。读取的时候按 key 找文件、反序列化即可。这个模型简单到什么程度你在纸上画一个两列的表格就能理解全部机制。但纯文件缓存有个致命弱点没有淘汰机制。用户装了个大应用缓存目录越来越大最后要么系统帮忙清理用户体验很差要么应用自己莫名其妙报错。所以这个组件在设计时就把“磁盘溢出淘汰”放进了核心能力清单这也是它和一般随手写的文件缓存工具最大的区别。顺带说一句为什么不用系统级的内存缓存替代持久化缓存因为两者的目标完全不同。内存缓存解决的是“运行期间重复获取”的性能问题持久化缓存解决的是“跨进程生命周期的状态保留”问题。1.2 极简 API 的价值很多开源的缓存库功能很全容量统计、过期时间、LRU 队列、namespace 隔离、加密存储全都给你留了接口但后果就是 API 变得越来越重团队里每个人用起来都有自己的姿势代码风格分裂。这个项目在 API 设计上走了另一个方向只留三个核心方法。写入、读取、删除。从功能上讲三件事足够覆盖 90% 的场景。写入时可选是否异步落地读取时自动处理内存优先还是磁盘优先删除时同步清掉两边的数据。如果你需要更细的控制可以在此基础上自己包一层但不影响核心路径的使用。这种极简 API 的另一个好处是鸿蒙适配非常容易做。Flutter 侧只暴露统一的接口鸿蒙侧实现只需要对应处理这几个操作通信协议简单出问题的概率就低。1.3 内存与磁盘两级结构的必要性实际落地的时候我强烈建议不要把缓存做成“只写磁盘”的模型——每次读取都走文件 IO性能完全扛不住。正确做法是两级结构内存优先磁盘兜底。第一级是内存中的 Map命中直接返回速度快到可以忽略不计。第二级才是文件缓存内存 miss 时读盘读完后把数据塞回内存。写入的时候也分两种情况高频更新的轻量数据可以先只更新内存标记为脏数据延迟落盘重要的、需要立即持久化的数据则同步或者异步立刻落盘。第二级往下还有一层就是鸿蒙侧的文件系统适配。Flutter 侧不感知文件路径、不感知目录结构只需要把写入请求通过平台通道发给鸿蒙侧由鸿蒙侧负责真正的文件操作。2. 鸿蒙化适配的路径选型2.1 三种适配思路的对比不谈理论只谈实战。在鸿蒙上使用 Flutter 三方库我见过三种路线也都在不同场景里踩过坑这里直接给大家做一个横向对比。第一种纯 Dart 实现不碰原生通道如果三方库本身就是纯 Dart 写的不依赖任何原生插件很多时候不用改动就能跑部分库甚至让鸿蒙的 Flutter 引擎直接跑通。persistent_cache_simple 这个库虽然主体是 Flutter 侧逻辑但底层文件写入依赖了路径获取和目录管理能力这些在鸿蒙上不能直接用 Flutter 默认的路径插件因为底层是 iOS/Android 的通道协议所以必须做平台适配。第二种通过 Platform Channel 对接鸿蒙原生代码这算是最常规、也是成熟的方案。Flutter 侧通过 MethodChannel 发起调用鸿蒙侧用 ArkTS 编写对应的处理逻辑返回结果。这个方案的优点在于能够精确地利用鸿蒙系统的沙箱目录、文件管理接口写入性能可信赖语义也和 Android 侧的原生插件对齐。第三种替换依赖实现如果某个 Flutter 库依赖了社区里某个不兼容鸿蒙的插件那么最省事的方式是找到对应的鸿蒙实现插件进行替换。但这种方案只适用于 API 恰好对得上的场景否则就得自己写适配。而 persistent_cache_simple 这类库它就是支撑业务的上层一旦底层被替换也不太影响调用方的用法前提是你得保证替换的插件行为一致。我的建议是如果有官方或社区维护的鸿蒙版本插件优先替换如果找不到就自己写 Platform Channel 适配。这次分享的库其实内部也是走这一条的。2.2 通道设计实例一个方法走天下在设计适配层的时候我倾向于不拆得太碎。你可能会在网上看到一些人把每个缓存操作都设计成一个独立的 method看起来清晰但传到鸿蒙侧后每增加一个方法就得同步改两遍代码维护成本高。我的做法是只定义一个通道方法名传字符串参数具体的操作由参数区分。class PersistentCacheChannel { static const MethodChannel _channel MethodChannel(persistent_cache_simple); static Futuredynamic invoke(String method, [dynamic arguments]) { return _channel.invokeMethod(method, arguments); } }在鸿蒙侧对应的模块里统一处理 method 的枚举// ArkTS 侧简化示例 import { BusinessError } from kit.BasicServicesKit; export class PersistentCacheHandler { private static readonly instance new PersistentCacheHandler(); static getInstance(): PersistentCacheHandler { return PersistentCacheHandler.instance; } async handleMethod(method: string, args: Mapstring, Object): PromiseObject { switch (method) { case init: return this.init(args); case write: return this.write(args); case read: return this.read(args); case remove: return this.remove(args); case clear: return this.clear(); case size: return this.size(); default: throw new BusinessError(1001, Unsupported method: method); } } }这样设计带来的一个直接好处是如果后续要加一个“批量读取”或者“缓存统计”的方法只需要在 ArkTS 侧加一个 caseFlutter 侧照常调用通道层不用动。2.3 路径与目录管理的鸿蒙适配细节这是最容易踩坑的地方。Android 上可能是 getCacheDiriOS 上可能是 Library/Caches鸿蒙上对应的是应用沙箱路径的能力具体来说是通过 “context.cacheDir” 获取应用的缓存目录。Flutter 侧如果直接用了某些跨平台路径插件在鸿蒙上是拿不到正确路径的。所以在适配的过程中必须在鸿蒙侧做一次“路径中枢”的收敛。所有缓存文件统一放在一个子目录下比如cache/persistent_cache/目录不存在就直接创建。文件命名建议不要直接使用原始 key而是用哈希值一方面避免非法文件名字符另一方面把 key 长度控制住文件名过长的风险也一并解除。function getCacheDir(context: Context): string { let dir context.cacheDir /persistent_cache/; let file new fileIo.File(dir); if (!file.exist()) { file.mkdirSync(); } return dir; }注意这里要处理沙箱权限。应用沙箱内不需要额外申请存储权限但千万别去尝试读外部存储路径。否则在鸿蒙上会直接抛“权限不允许”的错误。3. 核心机制实现溢出淘汰策略与极简 API 落地3.1 溢出淘汰策略怎么设计才合理前面说到了必须做淘汰但淘汰策略本身是有讲究的。常见方案有 FIFO、LRU、LFU。对客户端缓存来说LRU 的性价比最高它假设“最近被使用过的数据未来被使用的概率更高”非常适合缓存这类访问有局部性的场景。persistent_cache_simple 的实现思路是“惰性删除 周期清理”的组合不维护一个全量的 LRU 链表而是靠文件访问时间戳来做判断。具体逻辑拆开看初始化时或每次写入后扫描缓存目录下的所有文件。按最后修改/访问时间从早到晚排序。如果总大小未超过阈值过如果超出从最旧的文件开始删直到总大小回到阈值以内。这个方案的精度不如真正的双向链表 LRU但胜在实现成本低且对客户端场景足够用。文件数量上百的量级扫描一次也就几毫秒到几十毫秒完全没有性能压力。淘汰阈值不能写成写死的默认值。不同应用的缓存需求差别太大了短视频应用可能需要 500MB 以上工具类应用可能 50MB 就够了。因此组件把“maxCacheSizeBytes”设计为可配置项默认给一个保守值用户按需调整。3.2 写入与读取的完整时序梳理一下写缓存时组件内部做了什么接收业务侧传进来的 key 和 value。检查内存 Map 中该 key 是否已存在如果存在且数据相同直接返回。将 value 序列化为字节数组异步写入磁盘文件文件名由 key 的哈希决定。更新内存 Map。累加当前缓存大小如果超过阈值触发淘汰逻辑。读取的时候更简单先查内存 Map命中直接返回。内存没有则根据 key 哈希找到对应文件。文件存在则读字节数组、反序列化回填内存 Map返回数据。文件不存在返回 null业务侧自行处理降级逻辑。这里有一个小的性能优化点对于高频读取但很少变化的数据可以在内存 Map 之外再加一层“永久驻留”的标记被标记的数据跳过淘汰检查。但这个能力会增加 API 复杂度如果业务上不需要不建议轻易加。3.3 极简 API 的完整面纱很多库的 README 喜欢写一堆代码示例但这个库的调用代码简单到甚至不需要单独开个项目去演示。缓存写入final cache PersistentCacheSimple(maxCacheSizeBytes: 100 * 1024 * 1024); await cache.init(); // 同步写入写入内存并触发异步落盘 await cache.write(onboarding_shown, true); // 异步落地业务侧不必等待磁盘IO完成 await cache.write(feed_snapshot, feedJson, needPersist: false);读取final value await cache.read(feed_snapshot); if (value ! null) { // 有缓存直接渲染 } else { // 无缓存走网络请求 }删除与清空await cache.remove(onboarding_shown); await cache.clearAll();就这些。没有复杂的 builder没有配置器没有策略类。正是因为它足够简单团队里的新人在拿到代码后十分钟之内就能上手而不会出现“每个模块各写一套缓存工具”的乱象。3.4 为什么要做大小统计不能只看文件数淘汰策略依赖的是“总字节数”而不是文件数理由是文件大小不均。一张图片可能就几十 KB一段离线视频可能上百 MB如果只统计文件数那么四五个大文件就能轻易击穿容量阈值。组件内部维护了一个_totalSizePoints的原子计数器每次写入文件时用实际字节数累加删除文件时对应减掉。这个计数器配合阈值判断就能做到非常轻量的淘汰判定。但有个细节要注意计数器是内存态的如果应用进程被杀这个数字就丢了。重启后组件会重新扫描目录计算大小所以虽然计数器可能暂时不精确但整体不会出大问题。我个人的建议是不要把计数器做成持久化的没意义扫描一次的成本远比引入额外状态管理要低。4. 端侧资源异步落地的实战细节4.1 场景解析端侧资源从网络到本地在移动端很多资源都来自网络。图片、视频片段、富文本内容。如果每次打开页面都要从网络拉体验差不说流量也扛不住。而“端侧资源异步落地”要解决的就是在用户已经看到内容、并且当前网络状态良好的时候把高频资源提前下载到本地下一次启动直接用本地文件。persistent_cache_simple 在这个场景中承担的角色很简单它不负责下载只负责把“下载好的数据”安全地写入磁盘并且提供极快的读取路径。配合 Flutter 侧的下载管理模块可以形成一套完整的离线资源架构。4.2 实战案例首页图片列表的缓存落地以一套资讯类应用首页为例。首页包含一个图文列表图片素材来自 CDN每次冷启动如果都请求一遍不仅慢而且容易导致页面加载出现白屏。我们当时的做法是首帧加载时只请求接口数据图片先展示占位图。接口返回后把列表数据序列化后写入缓存。图片资源不直接同步下载而是在页面进入空闲状态后通过后台任务批量下载并写入 PersistentCacheSimple。这样用户第二次打开首页接口缓存直接命中图片也大概率已经在本地整个页面几乎是瞬间完成。这个场景里值得注意的一个点是图片资源是否需要真正的文件缓存还是直接用 Flutter 的图片内存缓存就够了。答案是要分情况用户可能一天内多次打开首页内存缓存就够但第二天冷启动之后内存缓存清空如果没有磁盘兜底图片就全部要回源了。接入持久化缓存后冷启动命中率明显提升。4.3 异步落地的线程模型与执行时机很多初次使用这个组件的开发者都会疑惑一个问题write方法是不是真的异步落盘如果不落盘数据会不会丢这里需要分清两个层次第一层是数据写入内存这个是同步的方法返回时内存里已经有数据第二层是内存刷到磁盘这个可以异步做。对于“掉电/杀进程丢数据”的容忍度不同业务不一样。即时通讯消息这种绝对不能丢的场景建议直接同步落盘资讯列表这种丢了还能重新拉取的场景用异步落盘就能节省不少卡顿。组件的默认行为是调用write时数据先写内存。同时将数据放入一个 FIFO 的持久化队列由后台 isolate 逐个写入磁盘文件。如果需要确保数据已经落盘再调用flush方法等待队列清空。注意flush方法和“异步写”是不同语义。flush是阻塞直到队列清空所以不要在 UI 线程直接等待flush最好放在后台任务里执行。否则缓存写入操作可能反过来拖慢页面的首帧渲染。5. 状态秒开实战让应用重启后回到上次的样子5.1 秒开的定义与目标“状态秒开”是很多应用想要达到的体验标准用户杀死应用后重新打开看到的页面应该和上次离开时基本一致而不是从启动页开始一步步点进去。要做到这一点核心在于两点状态要存得下来且状态要恢复得快。存——用持久化缓存把页面状态序列化下来恢复——在启动时同步读取并渲染。persistent_cache_simple 在这里的价值是提供了一条低延迟的读取路径。应用冷启动后缓存读取的耗时理论上要控制在毫秒级否则就谈不上“秒开”了。5.2 首页 Tab 状态的保存与恢复假设首页有三个 Tab信息流、搜索、个人中心。用户上次停在第二个 Tab搜索离开应用时组件把 Tab 索引写进缓存。下一次启动时应用在首帧渲染之前异步读取这个索引然后直接定位到对应 Tab。这里有一个体验细节如果把“Tab 索引读取”放到渲染完成之后用户会先看到第一个 Tab 闪一下再跳到搜索观感很差。正确做法是启动时同步等待缓存读取耗时短再去构建首页路由。final tabIndex await cache.readint(home_tab_index) ?? 0; homeController.switchTab(tabIndex);5.3 表单草稿与列表位置的恢复表单类应用是“状态秒开”价值最明显的地方。用户填了很长的表单中途切走后应用被系统回收再回来时内容全丢了。这是个非常反人类的设计。利用持久化缓存可以在每次输入框内容变化时做防抖写入把字段值存成 JSON 放到缓存里。恢复时先读取缓存 JSON再回填表单。列表位置的恢复更巧妙一点不一定需要存完整的列表数据只需要存用户滚到了哪个条目、条目在数据源里的唯一标识。启动时先恢复滚动位置等数据加载完做一次滚动偏移校准。这个策略可以省掉不少序列化开销效果也很不错。5.4 秒开实测数据拿我们自己的模拟项目实测冷启动场景下不接入缓存首页完整加载耗时约 2.8 秒图片加载约 3.5 秒后才完全显示。接入持久化缓存首帧数据读取耗时约 12 毫秒界面从启动页跳转到首页内容完整可见的耗时约 0.9 秒图片资源从磁盘读取再做解码整体耗时 1.4 秒左右。虽然测量环境有差异但趋势是非常明显的磁盘缓存在冷启动场景下几乎是决定性因素。当然也得说明白1.4 秒里包含了很多其他耗时引擎启动、路由构建、页面布局缓存部分只占了其中一小段因此它给不到从 3 秒降到 0.5 秒这种夸张的收益但足够带来体验上质的区别。6. 常见问题与排查技巧实录6.1 缓存写入成功但读取为空这个问题的概率不高但一旦出现找起来很痛苦。排查方向按优先级排序第一检查写入和读取是否用了同一个 key。很多同类问题其实是业务侧拼 key 时大小写或前后空格不一致导致的。第二检查是否跨了多个实例。如果业务代码里每次调用都新建了一个 PersistentCacheSimple 实例且内部没有做单例约束那么缓存目录可能被重复扫描互相覆盖。第三检查是否文件被系统清理了。应用缓存目录属于系统可控清理范围如果用户手机存储空间紧张系统可能自动清除缓存文件。这不是组件的问题是手机 OS 的管理策略业务侧不能假设磁盘缓存永远存在。6.2 缓存文件写入盘速度过慢如果在低端设备上发现写入速度慢大概率不是组件逻辑的问题而是频繁创建文件句柄。优化方式有三种复用文件句柄短时间内多次写入同一个 key 时先写内存延迟统一落盘一次。使用批量提交接口业务侧尽量把几十个小文件合并成一次缓存请求。避免全量扫描初始化和写入后如果每次都扫描目录文件数量多的时候会有可见耗时可以将扫描频率降为“仅初始化时执行一次 定时执行”。6.3 清理缓存后立即重新写入导致目录残留需要检查删除逻辑是否只删了目录列表里的记录而没有真正删除文件。实现时最容易漏掉的是“先删文件再删记录”还是“先删记录再删文件”的顺序问题。这里建议强制“先确保文件删除成功再更新内存记录”否则一旦删除中途失败内存里的统计数据就和磁盘不一致了后续大小统计也会偏离。6.4 鸿蒙侧文件操作异常定位ArkTS 侧跑文件操作时如果出现莫名的异常优先把异常详情打印出来然后逐层排查try { // 文件操作逻辑 } catch (err) { console.error(缓存文件操作失败: ${JSON.stringify(err)}); // 向上抛Flutter 侧可以捕获到这个异常 }Flutter 侧捕获异常try { final result await PersistentCacheChannel.invoke(write, args); } on PlatformException catch (e) { // 这里处理原生侧异常 }大多数文件操作异常的原因都集中在路径错误、目录不存在、权限不足、磁盘空间不足。前三者属于代码问题最后一个要关注设备本身的状态。6.5 常见问题速查表现象可能原因解决方向数据写入后读不到key 不一致 / 多实例统一 key 管理确认单例模式启动恢复状态失败缓存被系统清理业务侧增加空值兜底不依赖缓存保底写的慢频繁文件 IO批量写入或延长落盘间隔淘汰策略不触发大小统计不准初始化时重新扫描目录校准鸿蒙侧异常路径不正确/权限不足打印详细异常日志逐层排查6.6 独家避坑技巧最后说三个个人实践下来最有价值的经验。第一不要用当前时间戳作为缓存 key 的一部分。很多同学为了区分新旧数据喜欢在 key 后面拼时间戳结果就是缓存命中率极低、磁盘文件疯狂增长。正确做法是key 用业务的稳定标识如内容 ID写入时覆盖更新读取时毫秒级返回。第二对于大对象的缓存不要直接走“整存整取”路径。比如一段视频缓冲数据不要存成一个超大的 key而是拆成多个分片缓存读取时再拼接这样淘汰粒度更细单次 IO 压力也更小。第三把缓存目录的健壮性考虑进业务容错。不要让缓存组件成为应用启动链路里的单点任何一步失败都应该降级为“无缓存模式”继续往下走。我在实际项目中见过因为缓存目录损坏导致整个启动流程异常的情况所以缓存读取一定要包一层 try-catch宁可多花几毫秒走降级也不能让白屏黑屏把用户劝退。个人体会与扩展方向从 Flutter 到鸿蒙的适配真正的地基不是怎么把某个 API 翻译成另一套 API而是理解缓存天生的几对矛盾快与慢内存和磁盘、稳与活可靠持久化和灵活淘汰、简单与强大极简接口和丰富策略。persistent_cache_simple 这个项目的取舍方向我很认可它把复杂度隔离在内部对外只留给调用方三次握手。我自己在实际使用中的感受是缓存类组件接入得越早后续业务演进的时候就越不需要为了性能重构。而且由于 API 足够精简后续如果要把它扩展成支持分布式缓存或者多级缓存底座也不会拖后腿。如果继续往深做可以考虑的方向有给组件加一个缓存命中率的统计回调方便业务侧观测效果或者加一个可选的 TTL 过期机制让业务侧可以按时间维度淘汰也可以把平台通道从 MethodChannel 扩展到支持流式的数据写入进一步降低大资源落地的 IO 代价。但无论选哪个方向前提都是要保持现在这种“让调用方简单得不好意思出错”的状态。