1. 项目背景为什么会盯上游戏存档这个需求1.1 一句话讲清这个应用在做什么做这个项目的原因很庸俗我的游戏存档又丢了。确切地说不止一次新设备换机、游戏大版本更新、清理存储空间误删目录每次都让人想砸设备。自己损失一次就长记性了后来身边一起玩游戏的朋友也陆续碰上类似的事我就开始盘算与其到处找恢复工具不如自己写一个专门管存档的小应用。于是就有了这个游戏存档管理器。核心功能链条不复杂扫描设备上游戏产生的存档文件按游戏归类展示然后提供一键备份、一键还原的能力。后面又陆续加了定时备份、压缩存储、版本记录这些增强功能。说白了这就是一个带管理界面的文件备份工具只不过聚焦在游戏存档这一个垂直场景上。对普通玩家来说它解决的是存档到底去哪了、我怎么把它找回来这个刚需。这个教程会按我实际开发的顺序来写项目怎么从零搭建、核心功能怎么实现、鸿蒙平台上有哪些特殊适配、中间踩了哪些坑。适合已经会 Flutter 基础语法、想做一个跨平台工具应用的开发者也适合想从 Flutter 切入鸿蒙开发的人参考。如果你是纯粹的新手建议先把 Dart 语法和 Flutter 的 Widget 体系过一遍再回来读这篇会省很多力气。1.2 方案对比为什么最终选了 Flutter决定动手之后第一个要回答的问题就是用哪套技术栈。当时摆在面前的主要有三条路。第一条路是用鸿蒙自己的 ArkTS 加 ArkUI 写原生应用。这条路能力最完整能直接调用所有系统底层接口性能也是最好的。但问题很现实我只能得到一个鸿蒙版本。我的需求除了鸿蒙设备还想同时覆盖 Android 设备甚至以后可能上桌面端原生方案意味着每个端都要重新写一遍界面和业务逻辑个人开发者根本维护不过来。第二条路是 uni-app 这类偏前端的跨端方案。上手快生态也成熟但真要处理文件系统操作、压缩、数据库这些贴近系统的活儿往往要绕到原生插件上面去很多细节不可控出了问题排查起来也费劲。第三条路就是 Flutter。Dart 语言对文件 IO、流处理这些操作很顺手Flutter 自带的渲染引擎保证了界面流畅度插件生态里有路径管理、压缩包、SQLite 等现成方案。更重要的是Flutter 社区对 OpenHarmony 的适配已经形成了一个相对稳定的分支一套代码可以同时产出鸿蒙和 Android 的构建产物。对个人开发者来说这是性价比最高的路线。实际开发下来的感受也证实了当初的判断。存档管理这种工具类应用核心难点根本不在界面而在文件操作的可靠性、平台权限的差异处理。Flutter 把文件系统相关的 API 封装得很顺手跨平台开发成本比我预想的低很多。如果你的项目也是这种业务逻辑重、平台差异多的工具类应用Flutter 值得认真考虑。2. 开发环境搭建Flutter 跑在鸿蒙上的前提条件2.1 工具链清单与版本匹配先泼一盆冷水这不是一个普通 Flutter 项目。标准版的 Flutter SDK 默认不会输出鸿蒙安装包要在鸿蒙设备上跑 Flutter 应用必须使用带 OpenHarmony 适配能力的 Flutter SDK 分支再配合鸿蒙官方的 IDEDevEco Studio和命令行工具来完成构建、签名和安装。我自己实际跑通的工具链组合是这样的组件版本要求说明Flutter SDK3.x 的 ohos 适配分支必须拉取适配分支不能用官方主线版本代替DevEco Studio5.x 及以上鸿蒙应用的官方 IDE负责工程构建和签名HarmonyOS SDKAPI 12 及以上SDK 版本要和 Flutter 分支要求匹配JDK17 或更高鸿蒙构建链路对 JDK 版本有硬性要求hdc 命令行工具随 DevEco Studio 附带类似安卓生态里 adb 的角色用于连接设备和安装包版本匹配是这个环节最容易翻车的点。Flutter 适配分支的更新节奏通常落后于官方主线如果你随便拉一个最新版 Flutter很可能在构建鸿蒙工程时遇到编译错误。我第一次配置环境就踩了这个坑Flutter 分支版本比较新但 DevEco Studio 内置的构建插件还没跟上导致一连串莫名其妙的原生编译报错。后来把 Flutter SDK 固定到适配分支文档里明确推荐的版本号问题立刻少了九成。2.2 创建工程并接上鸿蒙平台整个环境准备流程拆成四步照着做就行。第一步拉取适配分支的 Flutter SDK。从官方仓库拉下来或者直接下载对应的发行包把bin目录加进系统 PATH然后执行flutter --version确认当前分支号是对的。这里要留意适配分支的版本号命名和官方主线不一样不用觉得奇怪。第二步安装并打开 DevEco Studio。首次启动会引导你安装 HarmonyOS SDK这里勾选你需要的 API 版本即可但要记得和 Flutter 分支文档里要求的一致否则后面编译会不匹配。第三步用 flutter create 创建项目同时声明两个目标平台flutter create --platforms ohos,android --org com.example save_manager这一步会把鸿蒙平台的工程骨架一起生成出来。创建完成后工程根目录里会多出一个ohos目录里面就是鸿蒙侧的 HAP 工程结构。第四步在 DevEco Studio 里打开项目。注意一个细节不要直接打开 Flutter 的根目录要先打开ohos目录内部的鸿蒙工程让 IDE 识别到鸿蒙侧的源码。然后再回到 Flutter 侧执行flutter pub get拉取依赖包。还有一个很容易忽略的点flutter create生成的鸿蒙目录默认可能没有正确关联 Flutter 插件。如果你后面用flutter run启动时报没有找到可用的设备先在 DevEco Studio 里同步一次鸿蒙工程的构建配置让 IDE 把 Flutter SDK 的路径正确写进工程文件里再回到命令行跑就好了。2.3 环境配置阶段我踩过的三个坑第一个坑是签名。鸿蒙应用不管是调试包还是发布包都需要签名才能装到设备上。默认的调试签名在 DevEco Studio 里会自动生成但如果你直接用命令行构建 HAP很容易因为缺少签名信息而失败。我的处理方式是先在 DevEco Studio 里面手动完成一次签名配置再把签名文件的路径和别名记下来后续命令行构建时指定同一套证书。第二个坑是首次构建特别慢。第一次构建要下载大量原生依赖还要编译 Flutter 引擎相关的产物整个流程走下来十几分钟甚至更久都正常。别以为是卡死耐心等就行。我中间有两次因为等不及直接中断了构建结果重新构建时反而多花了不少时间因为上次缓存的中间产物没有完整落盘等于白等。第三个坑是真机和模拟器的差异。鸿蒙模拟器启动速度偏慢而且对文件系统的模拟和真机差异不小。扫描目录这种离不了文件系统的功能在模拟器上跑出来的结果经常会骗人——路径能访问、权限也正常但你换到真机再跑就发现全变了。这个项目我干脆放弃模拟器从一开始就用真机调试还特意拿了一台游戏应用装得比较多的设备当测试机这样扫描时才有真实的目录结构和数据量可以验证。3. 需求梳理与整体架构设计3.1 四个功能模块的划分逻辑动手写代码之前先把功能拆成四个模块每个模块只干一件事。存档扫描模块负责找出设备上所有游戏存档。它的输入是一个可以扫描的根目录列表输出是归类好的游戏条目每个条目下面挂着这个游戏对应的存档文件。这个模块是整个项目的地基它不准后面所有功能都白搭。备份管理模块负责把选中的存档复制或者压缩到备份区同时维护一份备份记录。还原操作也归这个模块管而且必须包含还原前的安全检查比如校验备份包完整性和备份当前状态。定时备份模块负责在后台定期触发备份任务。这是后期加的功能因为人总会犯懒手动备份坚持不了几周就断了。定时模块的设计要特别注意平台限制后面我会单独讲这儿的问题。统计展示模块负责把备份数据可视化比如每个游戏占用多大空间、最近一次备份是什么时候、成功备份了多少次。这些信息看着简单但正好戳中用户的焦虑点让他看到自己有没有被好好保护。四个模块之间的依赖关系是单向的扫描模块给备份模块提供数据备份模块把记录写进数据库统计模块从数据库读数据展示。这样做的好处是改起来边界清晰——后面就算要换存档识别规则也只动扫描模块其他模块根本不用碰。我在项目后期给扫描模块加过一次规则确实只改了一个文件这个架构带来的收益是实打实的。3.2 存档记录的数据模型设计存档的本质是文件加文件元数据所以我直接用 SQLite 做持久化而不是简单地堆 JSON 文件。原因有三个查询方便能按游戏、按时间排序数据量可控几百条记录存一个文件也不会慢后面要扩展字段时不需要改文件解析逻辑加一列就行。我设计了两张核心表。第一张表记录游戏维度的信息CREATE TABLE games ( id INTEGER PRIMARY KEY AUTOINCREMENT, game_name TEXT NOT NULL, package_name TEXT, save_dir TEXT NOT NULL, added_at INTEGER NOT NULL DEFAULT 0, last_backup_at INTEGER DEFAULT 0 );第二张表记录每次备份的快照信息CREATE TABLE backups ( id INTEGER PRIMARY KEY AUTOINCREMENT, game_id INTEGER NOT NULL, backup_time INTEGER NOT NULL, backup_path TEXT NOT NULL, file_count INTEGER DEFAULT 0, total_size INTEGER DEFAULT 0, checksum TEXT, remark TEXT );设计时我特意留了checksum字段存的是压缩包的 SHA-256 散列值。这是项目做了两三周之后才补上的因为有一次还原出来的存档明显少了文件排查了好几轮才确定是压缩过程出问题个别文件没有被写进包里。加了哈希校验之后每次还原前先比对散列数据完整性就有保障了。3.3 工程目录结构规划目录结构也花了一点心思主要按照数据流的方向来组织lib/ ├── main.dart # 入口初始化数据库和定时任务 ├── models/ │ ├── game_entry.dart # 游戏条目模型 │ └── backup_entry.dart # 备份记录模型 ├── services/ │ ├── database_service.dart # SQLite 封装 │ ├── scan_service.dart # 存档扫描 │ ├── backup_service.dart # 备份还原 │ └── scheduler_service.dart # 定时任务 ├── pages/ │ ├── home_page.dart # 首页游戏列表 │ ├── game_detail_page.dart # 详情页备份列表 │ └── settings_page.dart # 设置页定时策略 └── utils/ └── file_utils.dart # 路径和大小格式化等工具这个结构不复杂但对一个人维护的项目来说足够了。我见过不少个人项目把模型、服务、页面全堆在一个文件里前期写起来很爽到后期改一个数据结构就要全局搜索挨个修改非常痛苦。一开始就按模块拆干净后面加功能会轻松很多。4. 核心功能实现从扫描到还原的完整链路4.1 存档目录扫描第一步是把文件找出来存档扫描是整个应用的地基扫描不准确后面一切功能都无从谈起。我的实现思路是维护一个已知存档路径的列表再允许用户手动添加路径扫描时把两类来源合并处理。一个典型的扫描流程是这样写的FutureListGameEntry scanSaveFiles() async { final roots await _getScanDirectories(); final results GameEntry[]; for (final root in roots) { final dir Directory(root); if (!await dir.exists()) continue; await for (final entity in dir.list(followLinks: false)) { if (entity is Directory) { final entry await _inspectGameDir(entity); if (entry ! null) results.add(entry); } } } return results; }这里真正的核心逻辑在_inspectGameDir里。怎么判断一个目录到底是不是游戏存档目录我的办法是综合三个特征来打分目录名里是否包含常见游戏名关键词、目录下是否存在特定后缀的存档文件、目录的最近修改时间是否对应玩家的活跃时段。三个特征里命中任意两个才判定为存档目录这样可以最大程度避免把缓存目录或者系统目录误认成游戏存档。扫描代码看起来简单但有一个重要的性能坑如果直接递归遍历整个存储目录会把无关的系统目录也扫一遍既慢又耗电。我给扫描过程加了两层限制一是主动跳过系统目录和隐藏目录二是遍历深度限制在四层以内。实测下来因为绝大多数游戏存档的路径深度都不会超过这个范围扫描时间从最初的半分钟缩短到了几秒钟。4.2 备份与还原数据安全永远是第一位备份模块的核心就是把指定目录安全地复制到备份区同时生成一条备份记录。我实际跑通的备份流程是这样的FutureBackupEntry createBackup(GameEntry game) async { final stamp DateTime.now().millisecondsSinceEpoch; final destDir await _backupRootFor(game); final destPath ${destDir.path}/${game.name}_$stamp.zip; await _compressDir(game.saveDir, destPath); final checksum await _sha256(destPath); final entry BackupEntry( gameId: game.id, backupTime: DateTime.now(), backupPath: destPath, checksum: checksum, ); await _database.insertBackup(entry); return entry; }备份做压缩而不是直接文件复制这是我的刻意选择。存档文件往往小而多直接复制会产生大量文件碎片后面管理和迁移都很费劲。压缩成单个 zip 文件之后一条备份就是一个文件删除、迁移、上传都非常干净。而且压缩包天然携带文件目录结构统计模块直接从包内信息就能拿到规格不需要额外维护一份清单。当然压缩也有代价每次备份会有一段 CPU 密集的打包过程不过存档文件的总量级通常也就几十兆这个时间成本完全在用户可以接受的范围内。还原流程比备份更看重安全。还原的本质是用备份文件覆盖当前存档目录这一步如果做错了很可能连备份里唯一一份数据也没了。所以我强制加了一个三步安全阀第一步校验备份包 SHA-256确定包是完整可解的第二步把当前存档目录整体复制到临时恢复区相当于给当前状态也留个后路第三步才用备份包的内容覆盖原目录。万一还原之后游戏读档异常用户还能退回还原前的状态。这三步听起来繁琐但实际执行时间都在毫秒到秒级用户体感就是点一下等一会儿完事。安全性上多出来的保障对我来说非常值得。4.3 压缩与完整性校验的实现细节压缩这块我用了 Dart 的 archive 包。它支持把目录里的文件逐个读进内存再打包也可以从流直接写进磁盘。对于存档这种文件数量多但单个文件不大的场景内存压力不大但要注意处理文件名里的中文和特殊字符否则解压后可能出现乱码或者路径错乱。Archive encodeDirContent(Directory dir) { final archive Archive(); for (final file in dir.listSync(recursive: true).whereTypeFile()) { final relativePath file.path.replaceFirst(dir.path, ).replaceFirst(/, ); archive.addFile( ArchiveFile.bytes(relativePath, file.readAsBytesSync()), ); } return archive; }哈希校验我直接用 crypto 包读文件流逐块更新摘要避免一次性把整个文件读进内存。大存档动辄几百 MB一次性读取很容易把内存吃满导致应用被杀掉这个坑我确实踩过后来改成流式读取就再也没出过问题。校验结果的记录和比对逻辑也要做好不然哈希算出来却没人用等于白做。4.4 定时备份的实现与平台限制定时备份这个功能一开始我以为很简单实际做的时候才发现跨平台后台任务是个深水区。鸿蒙和 Android 对后台任务的唤醒频率都有系统级限制最短间隔不是你说了算的而且用户在系统设置里还可能手动关掉应用的后台权限。我在 Flutter 层使用 workmanager 插件统一注册任务void initScheduler() { Workmanager().initialize(callbackDispatcher); Workmanager().registerPeriodicTask( backup-periodic, periodicBackup, frequency: Duration(hours: 12), constraints: Constraints( networkType: NetworkType.not_required, requiresBatteryNotLow: true, ), ); }这里特别提醒一句workmanager 这类插件在鸿蒙端的支持程度还在推进实际优化时可能要结合鸿蒙自身的任务调度能力来写。我的策略是定时任务只作为兜底手段应用每次打开时会另外检查上次备份时间如果超过设定间隔就主动提醒用户手动备份。两条链路互相配合才能真正覆盖忘记手动备份的情况。5. 鸿蒙平台的适配细节5.1 存储权限与沙箱机制鸿蒙应用和早期安卓应用最大的区别是它默认跑在严格的应用沙箱里。应用只能访问自己的数据目录想去读公共存储区或者其他应用的存档目录就必须申请权限并经过用户授权。这个项目的权限设计我分了两种情况来处理。如果游戏是鸿蒙原生应用存档默认在自己的沙箱目录里其他应用根本访问不到只能通过系统提供的文件选择器或者分享能力间接拿到文件。如果游戏走的是兼容安卓的形态存档路径通常落在公共存储区域这时就需要在运行时申请存储权限。权限申请我用的是 Flutter 侧的 permission_handler 插件在鸿蒙端它会映射到系统权限请求。需要注意一个平台差异鸿蒙上权限请求的回调可能不是立即触发弹窗关闭之后最好主动查一次权限状态否则界面显示和真实权限会不同步出现明明授权了但按钮还是灰的这种奇怪问题。5.2 通过平台通道调用原生能力Flutter 的标准库毕竟封装不了鸿蒙的所有系统能力所以我把一些特有的操作通过 MethodChannel 放到了原生侧。这里举一个实际用到的例子读取鸿蒙专属目录列表获取特定应用的外部沙箱路径。原生侧注册一个通道class SaveNativeHandler : MethodChannel.MethodCallHandler { override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) { if (call.method getKnownSaves) { val package call.argumentString(package) val path resolveSavePath(package) // 通过鸿蒙系统接口获取路径 if (path ! null) { result.success(path) } else { result.error(404, save path not found, null) } } else { result.notImplemented() } } }Dart 侧封装成统一调用static const _channel MethodChannel(save_manager/native); static FutureString? getKnownSavePath(String package) async { try { return await _channel.invokeMethod(getKnownSaves, {package: package}); } on PlatformException catch (e) { return null; } }平台通道的使用原则是能不用尽量不用但涉及系统目录、文件选择器这类能力时不要硬扛。跨平台框架的价值在于业务逻辑跨平台平台差异最终还是要靠原生代码兜底。我在设计时把所有平台通道调用都收敛在一个SavePlatform类里这样 Dart 侧代码就不会散落一堆if (Platform.isAndroid)之类的分支维护起来清爽很多。6. 常见问题与排查经验实录6.1 目录权限与沙箱访问失败这是整个项目里出现频率最高的一类问题具体表现为扫描时某个游戏目录明明存在但代码访问时抛权限异常或者Directory.exists()直接返回 false。我的排查顺序是这样的。第一步确认是不是权限问题到系统设置里看看应用有没有拿到存储权限没有就先手动授权再试一次别急着怀疑代码。第二步确认路径写法鸿蒙的文件系统对路径大小写、末尾斜杠处理比较严格最好统一用系统路径 API 返回的绝对路径不要自己手拼字符串。最后再确认是不是沙箱隔离导致的如果目标目录属于其他应用的私有区域那无论怎么申请权限都拿不到这种场景只能引导用户用系统文件选择器手动选择。我把这套排查流程整理成了表格直接贴在项目 README 里再遇到问题查表比回忆快得多现象可能原因处理方式目录 exists 返回 false路径拼写错误或末尾斜杠异常使用系统 API 返回的标准路径读取时权限异常运行时权限未授予在设置页引导用户重新授权扫描结果为空目标目录属于其他应用沙箱改用系统文件选择器手动选择列表刷新慢大量文件未做分页处理扫描放 isolate列表流式加载6.2 压缩包损坏与还原失败压缩包损坏是备份工具最致命的故障现象是还原时解压抛异常或者解压出来的文件数量和备份前对不上。我实际排查下来原因基本集中在这三个地方。第一个原因是压缩过程中读文件超时。某些云同步目录下的文件存在占位符读取时机不对会拿到空文件或者半截文件。解决办法是在进入压缩流程之前先过滤掉这类没有真实落盘的文件类型。第二个原因是文件名编码问题中文或者特殊字符在跨平台迁移时容易乱码导致解压失败。解决办法是压缩时统一用相对路径解析时做一层路径合法化处理。第三个原因就是前面反复提过的哈希校验缺失这个补上之后所有备份包在创建时就有了指纹任何损坏都能在还原之前被识别出来。解决完这些问题后我还给还原操作加了一道自检解压完成后立即统计文件数量和备份记录里的file_count字段比对不一致就提示用户备份可能异常不要强行写入。宁可让用户选择重新备份也不能让他拿到一个不完整的数据。6.3 扫描目录时的性能问题前面提到过最初我把备份目录直接放在应用私有目录扫描时递归遍历整个目录树结果就是每次打开首页都要卡三四秒。后来主要做了两个优化。第一步把复杂的扫描逻辑丢进compute函数让它在一个独立 isolate 里跑这样主线程和 UI 完全不受影响界面不会出现白屏或者掉帧。第二步对游戏列表做内存缓存只有用户主动下拉刷新时才重新扫描平时直接读缓存数据。这两个方案合起来首页打开速度从原来的三秒多降到了毫秒级体感上是完全不同的应用。如果你也要做类似的目录遍历功能建议一开始就把耗时操作放到后台 isolate别图省事直接在主线程里跑等到卡顿出现再改成本就高了。7. 打包、安装与上线前检查7.1 HAP 包的构建和签名开发功能全部完成后要产出可安装的发布包。鸿蒙侧的构建操作通常是在 DevEco Studio 里完成的。我的流程是先在 DevEco Studio 里配置好发布签名然后执行构建生成.hap文件最后通过 hdc 命令安装到真机hdc install -r save_manager.hap如果你习惯命令行构建命令大致是这样flutter build hap --release构建之前要特别检查几项Flutter SDK 分支与鸿蒙 SDK 的版本匹配、所有平台通道的原生代码没有编译警告、应用的minSdkVersion与目标真机的系统版本匹配。这几项只要有一项不对构建阶段就会被卡住。尤其是 SDK 版本不匹配的报错信息通常很隐晦我花过不少时间才定位到根因。7.2 真机验证的检查清单发布之前我习惯在真机上完整过一遍检查清单重点不是界面而是数据链路能不能闭环。装上应用之后我会手动跑一遍扫描-备份-还原-验证存档可读的全流程特别关注还原后游戏端能不能正常读到数据。这个环节暴露过不少问题比如有一次还原出来的目录权限不对文件虽然在但游戏读取时直接被系统拒绝。然后测试一次低电量状态下触发备份确认应用不会因为系统杀进程而中断备份流程。最后是连续备份两三个版本再从旧版本还原确认备份记录没有被覆盖、没有串版本。这些检查看着基础却能规避绝大多数发布后的功能性问题。存档管理器这种工具类应用用户对数据安全的要求是零容错的一次还原失败就足以让用户卸载掉它。发布前多花半小时跑一遍链路比发布后收到差评再修复划算太多了。8. 一点开发后的体会项目做到目前这个程度功能已经趋于完整我也在真机上连续使用了几周。回顾整个开发过程最深的体会是工具类跨平台应用的技术门槛并没有很多人想的那么高真正的门槛在数据链路的可靠性设计上。备份、还原、校验这三步每一步都要反复问自己如果中间断掉了怎么办只有把这些问题在设计阶段就想清楚写代码的时候才有条理才不会后面返工。另一个很现实的建议是用 Flutter 做鸿蒙开发不要一开始就追求把所有平台差异化功能都封装成插件。先用平台通道把最核心的一两个能力接起来跑通整个业务闭环之后再根据实际需求逐步扩展。这种最小闭环的开发方式能让你更快看到应用的真实形态也更容易控制项目复杂度。如果你也想做一个类似的跨平台工具应用我的建议是最先跑通手动备份和手动还原这两个闭环不要急着加定时任务和界面美化。工具类应用的护城河从来不在界面多华丽而在数据链路足够可靠这一点在我自己这个项目里体现得淋漓尽致。等到核心链路稳定了再去打磨视觉和体验你会发现一切都顺很多。