1. 为什么我盯上了 text_indexing 这个三方库先交代一下背景。我手头有一个知识管理类的 Flutter 应用核心功能是笔记、书摘和离线文章收集用户量不大但数据量增长很快单个用户的文本内容动辄几十万字。过去搜索功能一直用 SQLite 的LIKE %关键词%硬扛当时觉得数据量小无所谓直到有个用户抱怨我输入一个词要转两秒圈翻了几十页才找到想要的那条笔记。那一刻我意识到全文检索已经不是优化项而是必须项。市面上 Flutter 生态里的全文检索方案不算多text_indexing 是其中一个相对轻量的三方库。它的思路跟我想要的非常接近把文本拆成词条建立倒排索引查询时通过词条快速定位文档并且能返回相关度评分。关键在于它把核心索引结构和打分算法都放在了 Dart 层底层只有少量平台相关的存储调用。这意味着什么意味着鸿蒙化适配的核心工作量不在算法而在把 Dart 层和鸿蒙原生层之间的通道铺好。这几年鸿蒙生态发展很快尤其是 HarmonyOS NEXT 彻底不兼容 APK 之后Flutter 应用要上鸿蒙只能走 OpenHarmony 的 Flutter SDK 这条路。但三方库的适配速度明显跟不上需求很多在 Android/iOS 上很成熟的库到了鸿蒙就抓瞎。text_indexing 这种算法在 Dart、存储走平台的库反而是最适合优先适配的一类——只要解决存储层的平台差异整个检索能力就能在鸿蒙上完整跑起来。这篇文章就把我适配 text_indexing 的完整过程写出来从技术摸底、环境准备、核心适配步骤到实测调优和踩坑记录每一步都尽量说清楚为什么这么做。如果你也在做 Flutter 应用的鸿蒙化或者想在鸿蒙上给应用加一个全文检索能力这篇应该能帮你省不少时间。2. 适配前的技术摸底先搞清楚 text_indexing 到底依赖了什么很多人拿到三方库第一反应就是编译试试报错再说。这个思路在纯 Dart 库上还行但遇到有平台通道的库盲目编译只会让你浪费时间在报错堆里。我建议先花半小时做一次技术摸底搞清楚三件事代码分层、平台依赖点、原生侧需要重写什么。2.1 解剖 text_indexing 的代码结构我 fork 下来之后用了一个取巧的办法先看 pubspec.yaml 的依赖列表再全局搜索dart:io、MethodChannel、path_provider这类关键字把平台相关的调用点全部标出来。text_indexing 的结构大致分三块索引构建层负责把一段文本拆成词条建立倒排索引。这块几乎纯 Dart主要做词频统计、文档编号、词条到文档列表的映射。查询与打分层接收查询词找到候选文档用类似 TF-IDF 或 BM25 的思路给文档打分排序。这块也是纯 Dart。存储层索引数据最终要落盘否则内存一释放索引就没了。text_indexing 默认的实现是往本地文件写索引数据或者把索引状态交给平台侧数据库托管。从适配角度看前三层不需要动真正要处理的是存储层。这也是最容易被编译通过假象迷惑的地方——Dart 层的文件读写 API 在鸿蒙 Flutter SDK 里可能能编译但运行时的沙箱路径、权限模型跟 Android 完全不同跑起来才会暴露问题。2.2 平台依赖点清单我整理了一份依赖清单直接照着检查就行依赖类型具体位置鸿蒙侧影响程度文件读写dart:io的 File/Directory低可编译但路径语义不同本地路径获取path_provider 或自取路径中鸿蒙沙箱路径需要原生侧注入数据库访问sqflite 或 sqlite3高默认走 SQLite 平台库平台通道MethodChannel/EventChannel 定义高必须写鸿蒙侧实现编解码utf8、json 等低纯 Dart 能力直接可用以我用到的版本为例text_indexing 的索引持久化默认依赖 SQLite 的 FTS全文搜索能力。这在 Android/iOS 上是现成的SQLite 编译时通常带了 FTS5 扩展。但鸿蒙系统自带的 SQLite 是否有 FTS5需要实测确认如果没带就得在适配时换个存储方案或者自己把带 FTS5 的 SQLite 编进鸿蒙原生侧。2.3 一个容易被忽略的隐藏依赖分词器text_indexing 的默认分词很简单——按空格和标点切分。英文场景没问题中文场景就是灾难鸿蒙系统会被拆成鸿、蒙、系、统四个单独的字搜系统还行搜鸿蒙就匹配不上。所以中文应用接这个库分词器几乎是必须自己换的。适配时的处理思路是在 Dart 层保留一个分词器接口默认实现用词典最大匹配法正向最长匹配把连续的中文文本切成有意义的词。这个逻辑不依赖平台纯 Dart 就能写适配成本很低但收益极大。实测下来中文检索的准确率至少提升一个档次。注意如果你只需要英文检索或者关键词本身就是用户手动输入的标签可以跳过分词器改造直接用默认行为。3. 鸿蒙 Flutter 开发环境搭建的那些细节环境搭建本身不复杂但版本匹配问题能卡你两天。我踩了一遍坑之后把可复现的步骤和容易出错的地方都整理出来。3.1 工具链组合鸿蒙 Flutter 开发依赖两套工具DevEco Studio 是 IDE 和鸿蒙 SDK 的管理器OpenHarmony 的 Flutter SDK 是让 Flutter 能编译出鸿蒙应用的编译器。我用的是 DevEco Studio 5.x 配合 OpenHarmony 的 flutter_flutter 分支这套组合的新版本支持直接从 Flutter 工程生成ohos/目录。需要注意一个版本匹配问题Flutter SDK 的版本要和鸿蒙 SDK 的 API 版本对齐。比如鸿蒙 SDK 用的是 API 12那 Flutter SDK 最好也用与之配套的分支。版本不匹配的典型症状是编译能过但运行时报符号找不到或者 MethodChannel 注册不上。排查起来非常痛苦因为报错信息往往模棱两可。3.2 具体配置步骤按我的实际操作顺序列一遍安装 DevEco Studio首次启动时让它自动下载配套 HarmonyOS SDK。用命令行配置全局 Flutter 属性flutter config --enable-ohos flutter config --ohos-sdk-dir 你的SDK路径在现有 Flutter 工程目录执行flutter create . --platformsohos生成ohos平台目录。用 DevEco Studio 打开工程的ohos目录等它完成 Gradle 同步。回到命令行执行flutter build ohos或直接flutter run --device-id 设备跑真机。这个顺序里最容易翻车的是第 3 步。老版本 Flutter 项目可能没启用鸿蒙支持直接执行 create 会报错提示unknown platform。我遇到的情况是创建成功后没有生成ohos目录后来才发现是flutter config --enable-ohos那条命令没生效重新执行一遍再flutter doctor确认问题就解决了。3.3 调试策略日志先行鸿蒙侧的调试跟 Android 不一样Android Studio 的 Logcat 那套在 DevEco 里是另一套 hilog 工具。调试 Flutter 应用还有个麻烦Dart 层的print输出和原生侧的 hilog 不在同一个视图里。我建议在适配阶段给鸿蒙侧插件代码里都打上hilog关键 logDart 侧用debugPrint两边打不同的标签这样出了问题能快速定位是 Dart 层还是原生层。提示真机调试比模拟器靠谱得多。开源的模拟器对 Flutter 引擎的图形渲染支持还不稳定跑 text_indexing 这种 IO 密集操作还行一涉及界面刷新就容易花屏卡顿影响你判断问题出在业务逻辑还是渲染层。4. text_indexing 鸿蒙化实施核心适配步骤环境准备好之后真正的适配工作就开始了。我把整个流程拆成四步每一步都有对应的验证方式跑通一步再走下一步不要一口气改完再编译那样出问题你根本不知道是谁的锅。4.1 第一步把存储层从平台 SQLite里解耦出来我前面说过text_indexing 默认依赖 SQLite FTS。鸿蒙系统自带的 SQLite 经实测FTS5 扩展情况并不可靠——API 版本、设备厂商的实现都有差异。与其赌系统库不如在适配时把存储层解耦做成一个StorageBackend抽象支持两种实现纯文件索引索引数据序列化后写入自定义二进制文件类似 sqlite 的 FTS 但由 text_indexing 自己控制格式。原生 SQLite通过鸿蒙侧插件访问 SQLiteFTS 能力由我们自己编译的库保证。像 text_indexing 这种库的常见用法是索引文件可以导出、迁移、合并纯文件索引反而更贴合它的设计。我最终选择的也是纯文件方案——把一个大的倒排索引按词条分片存文件查询时只加载命中的分片。这个方案在鸿蒙上的适配量最小而且不依赖系统 SQLite 的版本。4.2 第二步实现鸿蒙原生插件通道text_indexing 在 Dart 侧通过 MethodChannel 和原生通信鸿蒙侧需要实现对应的插件注册和通道处理。以我适配时用到的接口为例核心方法有这么几个createIndex、addDocument、search、deleteDocument、flushIndex。鸿蒙侧插件类的大体结构如下import { FlutterPlugin } from ohos/flutter_ohos; import { MethodChannel } from ohos/flutter_ohos; import { MethodCall, MethodResult } from ohos/flutter_ohos; export default class TextIndexingPlugin implements FlutterPlugin { onAttach(engine: FlutterEngine) { const channel new MethodChannel(engine, text_indexing/storage); channel.setMethodCallHandler((call: MethodCall, result: MethodResult) { switch (call.method) { case createIndex: this.createIndex(call.arguments(), result); break; case search: this.search(call.arguments(), result); break; // 其余方法同理 } }); } }这里有个关键点onAttach之后插件生命周期要跟 FlutterEngine 同步Flutter 页面销毁时插件要释放资源否则再次打开页面会出现重复注册的报错。text_indexing 的搜索可能跨越多个页面生命周期我在适配时把常用通道对象做成了单例避免重复创建。4.3 第三步处理沙箱路径差异这是整个适配过程中最隐蔽的坑。Android 上你可以直接用context.getFilesDir()拼路径iOS 用NSDocumentDirectory鸿蒙的沙箱路径结构和两者都不同。text_indexing 的 Dart 层会把索引文件路径当作字符串传给原生层如果路径拼接不对文件创建和读取会静默失败——不报错但索引永远是空的。我的处理方案是绝对路径只在原生侧生成Dart 层只传文件名不传全路径。鸿蒙侧通过getContext().filesDir拿到沙箱目录拼接好文件名后把最终路径返给 Dart 层缓存。这样确保两边操作的是同一个文件。4.4 第四步中文分词器的接入前面提过默认分词不适合中文这里展开说。我在 Dart 层实现了一个词典最大匹配分词器思路如下准备一个常用词词典按词长从长到短排序。对输入文本从左到右扫描每次尝试匹配最长的词典词条。匹配不到就按单字切分但记录相邻单字可合并的位置信息方便后续扩展。分词结果统一转成小写去掉空字符串按空格拼接后交给 text_indexing 的索引构建层。这个分词器代码量不大但有一个收益是立竿见影的索引体积大幅缩减。中文按单字索引你好世界会建立 4 个索引项按词索引你好和世界只有 2 个索引项。索引文件小了查询要扫描的数据也少了性能自然上去。5. 实测性能与调优全文检索在鸿蒙上的真实表现适配只是第一步能不能实际用起来取决于性能。我用一台 HarmonyOS NEXT 真机做了两组测试一组是 1 万篇文章的索引构建另一组是随机查询延迟测试数据比较有代表性。5.1 测试环境与数据集设备HarmonyOS NEXT 真机数据集随机生成的 1 万篇中文文本每篇 200-1000 字总计约 800 万字符对比基线同一个数据集上用 SQLiteLIKE %词%查询的耗时测试时要保证数据集有区分度不要全是高频词否则索引构建慢、查询看不出差异。我的做法是混入了一批低频术语模拟真实笔记场景。5.2 索引构建实测操作text_indexing鸿蒙化后SQLite LIKE 全表扫描建索引1万篇约 4.2 秒不适用无索引概念索引文件大小约 48 MB不适用首次查询2-8 毫秒480-900 毫秒热词查询高频词1-3 毫秒300-600 毫秒冷词查询低频词0-1 毫秒600-1200 毫秒可以看到建索引是一次性成本之后所有查询都在毫秒级和 LIKE 全表扫描完全不在一个数量级。冷词查询更快是因为低频词的倒排列表很短命中文档少排序计算也快。注意以上数据是单次冷启动后的表现首次启动加载索引文件会额外增加 100-200ms 的预热时间。对体验要求高的应用建议在启动页或后台线程提前调用一次预搜索触发索引加载。5.3 调优手段事务批量提交最开始我用逐条调用addDocument的方式批量导入 1 万篇文章耗时在 20 秒以上完全不能接受。后来改成事务批量提交每 200 篇文档作为一批批内共享同一个写入事务整体耗时直接降到 4.2 秒。原因是每篇单独提交时索引文件要不断执行打开-写入-关闭的序列化操作磁盘 IO 开销远大于索引构建本身。事务批量提交的代码实现不求复杂核心就一点Dart 层把 200 篇文档累积到一个 List一次性传给原生层或直接走 Dart 层的批处理接口。text_indexing 这类库通常有addDocuments这类批量方法实在没有也可以自己包一层。5.4 调优手段索引分片加载针对索引文件太大导致加载慢这个问题我做了一个分片策略按词条的首字母或哈希值把索引拆成多个分片文件查询时只加载包含命中词条的分片。800 万字符的索引拆成 16 个分片后单个分片平均只有 3 MB冷启动加载速度从 400ms 降到 150ms。分片不是越多越好分片过多会导致查询时要打开多个文件反而增加 IO 次数。我当时用 16 个分片是权衡过的文件大小和打开次数都比较均衡。如果你索引数据量不到 100 MB其实不分片问题也不大分片主要是解决索引文件太大导致加载卡顿的场景。5.5 一个反直觉的经验查询热词不一定比冷词快测试时我发现一个有意思的现象高频词的查询有时候比低频词慢。原因是高频词命中的文档太多打分排序要遍历的候选集大反而拖慢了响应。针对这个现象我做了两类优化截断策略单次查询最多返回 200 条结果评分排序只对前 2000 个候选文档做避免不做任何限制的暴力排序。停用词过滤像的了是这种停用词在索引构建时就过滤掉。这样既缩减了索引体积也避免了查询时被这些高频词拖慢。6. 踩坑记录适配过程中最棘手的三个问题适配过程不可能一帆风顺挑三个我在实际中遇到最费劲的问题把排查链路完整写出来。直接给你答案没意义重要的是这个排查思路。6.1 问题一索引文件创建成功但内容为空一开始我以为 MethodChannel 通了个寂寞Dart 层返回的索引文件大小永远是 0。排查过程在 Dart 层打印Directory.current和文件路径确认路径不是空字符串。在鸿蒙侧createIndex的 method handler 里打 hilog确认方法确实被调到了。发现原生侧返回成功但文件写入用的是相对路径——鸿蒙沙箱的当前工作目录并不是 Flutter 引擎的工作目录相对路径解析到了完全不同的位置。最终解决方案就是前面说的所有路径由原生侧通过filesDir拼接后返回Dart 层不再直接传绝对路径。这个问题的典型特征是不报错但行为不对最容易被忽略。6.2 问题二MethodChannel 异步回调被重复触发text_indexing 的大批量索引操作耗时较长我在鸿蒙侧做了异步处理结果发现 UI 偶尔卡死甚至出现同一批索引任务回调两次的诡异现象。排查过程先怀疑是 Flutter 引擎的 MethodChannel 有 bug查官方 issue 没找到对应项。在鸿蒙侧加日志后发现不是回调被触发两次而是 Dart 侧连续调用了两次同一个addDocuments方法——第一次在页面 A 发起页面 A 销毁时任务没取消页面 B 重建后又发起一次。根因是插件通道对象在页面销毁时没有正常 detach导致任务队列堆积。解决方案是给插件类实现onDetach方法在 FlutterEngine 销毁时取消所有未完成的异步任务。同时Dart 侧给大批量操作加了一个是否正在执行的互斥锁避免重复提交。6.3 问题三索引库自带的 SQLite 编译进鸿蒙后闪退我在测试用原生 SQLite 存储索引这条路时自己编译了一版带 FTS5 的 SQLite编译倒是通过了运行就闪退。排查过程用 hilog 抓崩溃栈发现崩溃发生在 SQLite 的sqlite3_open阶段提示 libc 库冲突。对比鸿蒙 Flutter 引擎自带的 .so 依赖列表发现我编进去的 SQLite 符号和系统库有重叠。尝试用动态链接模式替换但鸿蒙的沙箱机制对动态库的加载路径限制比较严最终还是放弃了原生 SQLite 方案改用纯文件索引。这个经历让我得出一个结论三方库鸿蒙化时优先考虑原生依赖最小化方案。能把逻辑放在 Dart 层就不要编原生库能不依赖系统 API 就不要依赖。文本索引这种场景纯文件索引的适配速度和稳定性远超原生 SQLite 方案印了那句老话少即是多。7. 一点收尾心得这个适配思路还能用到哪里text_indexing 的鸿蒙化适配本质是一套可复制的方法论先摸清三方库的平台依赖点再通过抽象存储层 重写平台通道 处理沙箱差异解决鸿蒙兼容问题最后用实测数据指导性能调优。这套思路不只适配检索类库实际上大部分 Flutter 三方库的鸿蒙化都能套用。我最近也在关注 Flutter 事件通道在鸿蒙上的表现EventChannel 在大数据量场景下的流式传输效率跟 text_indexing 的索引进度回调其实是一个道理。鸿蒙对整个 Flutter 生态来说还属于建设期三方库适配得越充分应用开发者的选择就越多。最后分享一个小经验适配前一定要把原始库在 Android/iOS 上的标准行为录下来比如索引构建耗时、查询结果排序规则、文件格式的二进制内容。鸿蒙化之后拿这个基准去对比能快速发现隐藏的行为差异。我在适配过程中就是靠对比索引文件的字节内容发现了一个排序字段大小端问题这种问题靠肉眼看 UI 根本发现不了。
Flutter鸿蒙化适配：text_indexing全文检索库实践指南
1. 为什么我盯上了 text_indexing 这个三方库先交代一下背景。我手头有一个知识管理类的 Flutter 应用核心功能是笔记、书摘和离线文章收集用户量不大但数据量增长很快单个用户的文本内容动辄几十万字。过去搜索功能一直用 SQLite 的LIKE %关键词%硬扛当时觉得数据量小无所谓直到有个用户抱怨我输入一个词要转两秒圈翻了几十页才找到想要的那条笔记。那一刻我意识到全文检索已经不是优化项而是必须项。市面上 Flutter 生态里的全文检索方案不算多text_indexing 是其中一个相对轻量的三方库。它的思路跟我想要的非常接近把文本拆成词条建立倒排索引查询时通过词条快速定位文档并且能返回相关度评分。关键在于它把核心索引结构和打分算法都放在了 Dart 层底层只有少量平台相关的存储调用。这意味着什么意味着鸿蒙化适配的核心工作量不在算法而在把 Dart 层和鸿蒙原生层之间的通道铺好。这几年鸿蒙生态发展很快尤其是 HarmonyOS NEXT 彻底不兼容 APK 之后Flutter 应用要上鸿蒙只能走 OpenHarmony 的 Flutter SDK 这条路。但三方库的适配速度明显跟不上需求很多在 Android/iOS 上很成熟的库到了鸿蒙就抓瞎。text_indexing 这种算法在 Dart、存储走平台的库反而是最适合优先适配的一类——只要解决存储层的平台差异整个检索能力就能在鸿蒙上完整跑起来。这篇文章就把我适配 text_indexing 的完整过程写出来从技术摸底、环境准备、核心适配步骤到实测调优和踩坑记录每一步都尽量说清楚为什么这么做。如果你也在做 Flutter 应用的鸿蒙化或者想在鸿蒙上给应用加一个全文检索能力这篇应该能帮你省不少时间。2. 适配前的技术摸底先搞清楚 text_indexing 到底依赖了什么很多人拿到三方库第一反应就是编译试试报错再说。这个思路在纯 Dart 库上还行但遇到有平台通道的库盲目编译只会让你浪费时间在报错堆里。我建议先花半小时做一次技术摸底搞清楚三件事代码分层、平台依赖点、原生侧需要重写什么。2.1 解剖 text_indexing 的代码结构我 fork 下来之后用了一个取巧的办法先看 pubspec.yaml 的依赖列表再全局搜索dart:io、MethodChannel、path_provider这类关键字把平台相关的调用点全部标出来。text_indexing 的结构大致分三块索引构建层负责把一段文本拆成词条建立倒排索引。这块几乎纯 Dart主要做词频统计、文档编号、词条到文档列表的映射。查询与打分层接收查询词找到候选文档用类似 TF-IDF 或 BM25 的思路给文档打分排序。这块也是纯 Dart。存储层索引数据最终要落盘否则内存一释放索引就没了。text_indexing 默认的实现是往本地文件写索引数据或者把索引状态交给平台侧数据库托管。从适配角度看前三层不需要动真正要处理的是存储层。这也是最容易被编译通过假象迷惑的地方——Dart 层的文件读写 API 在鸿蒙 Flutter SDK 里可能能编译但运行时的沙箱路径、权限模型跟 Android 完全不同跑起来才会暴露问题。2.2 平台依赖点清单我整理了一份依赖清单直接照着检查就行依赖类型具体位置鸿蒙侧影响程度文件读写dart:io的 File/Directory低可编译但路径语义不同本地路径获取path_provider 或自取路径中鸿蒙沙箱路径需要原生侧注入数据库访问sqflite 或 sqlite3高默认走 SQLite 平台库平台通道MethodChannel/EventChannel 定义高必须写鸿蒙侧实现编解码utf8、json 等低纯 Dart 能力直接可用以我用到的版本为例text_indexing 的索引持久化默认依赖 SQLite 的 FTS全文搜索能力。这在 Android/iOS 上是现成的SQLite 编译时通常带了 FTS5 扩展。但鸿蒙系统自带的 SQLite 是否有 FTS5需要实测确认如果没带就得在适配时换个存储方案或者自己把带 FTS5 的 SQLite 编进鸿蒙原生侧。2.3 一个容易被忽略的隐藏依赖分词器text_indexing 的默认分词很简单——按空格和标点切分。英文场景没问题中文场景就是灾难鸿蒙系统会被拆成鸿、蒙、系、统四个单独的字搜系统还行搜鸿蒙就匹配不上。所以中文应用接这个库分词器几乎是必须自己换的。适配时的处理思路是在 Dart 层保留一个分词器接口默认实现用词典最大匹配法正向最长匹配把连续的中文文本切成有意义的词。这个逻辑不依赖平台纯 Dart 就能写适配成本很低但收益极大。实测下来中文检索的准确率至少提升一个档次。注意如果你只需要英文检索或者关键词本身就是用户手动输入的标签可以跳过分词器改造直接用默认行为。3. 鸿蒙 Flutter 开发环境搭建的那些细节环境搭建本身不复杂但版本匹配问题能卡你两天。我踩了一遍坑之后把可复现的步骤和容易出错的地方都整理出来。3.1 工具链组合鸿蒙 Flutter 开发依赖两套工具DevEco Studio 是 IDE 和鸿蒙 SDK 的管理器OpenHarmony 的 Flutter SDK 是让 Flutter 能编译出鸿蒙应用的编译器。我用的是 DevEco Studio 5.x 配合 OpenHarmony 的 flutter_flutter 分支这套组合的新版本支持直接从 Flutter 工程生成ohos/目录。需要注意一个版本匹配问题Flutter SDK 的版本要和鸿蒙 SDK 的 API 版本对齐。比如鸿蒙 SDK 用的是 API 12那 Flutter SDK 最好也用与之配套的分支。版本不匹配的典型症状是编译能过但运行时报符号找不到或者 MethodChannel 注册不上。排查起来非常痛苦因为报错信息往往模棱两可。3.2 具体配置步骤按我的实际操作顺序列一遍安装 DevEco Studio首次启动时让它自动下载配套 HarmonyOS SDK。用命令行配置全局 Flutter 属性flutter config --enable-ohos flutter config --ohos-sdk-dir 你的SDK路径在现有 Flutter 工程目录执行flutter create . --platformsohos生成ohos平台目录。用 DevEco Studio 打开工程的ohos目录等它完成 Gradle 同步。回到命令行执行flutter build ohos或直接flutter run --device-id 设备跑真机。这个顺序里最容易翻车的是第 3 步。老版本 Flutter 项目可能没启用鸿蒙支持直接执行 create 会报错提示unknown platform。我遇到的情况是创建成功后没有生成ohos目录后来才发现是flutter config --enable-ohos那条命令没生效重新执行一遍再flutter doctor确认问题就解决了。3.3 调试策略日志先行鸿蒙侧的调试跟 Android 不一样Android Studio 的 Logcat 那套在 DevEco 里是另一套 hilog 工具。调试 Flutter 应用还有个麻烦Dart 层的print输出和原生侧的 hilog 不在同一个视图里。我建议在适配阶段给鸿蒙侧插件代码里都打上hilog关键 logDart 侧用debugPrint两边打不同的标签这样出了问题能快速定位是 Dart 层还是原生层。提示真机调试比模拟器靠谱得多。开源的模拟器对 Flutter 引擎的图形渲染支持还不稳定跑 text_indexing 这种 IO 密集操作还行一涉及界面刷新就容易花屏卡顿影响你判断问题出在业务逻辑还是渲染层。4. text_indexing 鸿蒙化实施核心适配步骤环境准备好之后真正的适配工作就开始了。我把整个流程拆成四步每一步都有对应的验证方式跑通一步再走下一步不要一口气改完再编译那样出问题你根本不知道是谁的锅。4.1 第一步把存储层从平台 SQLite里解耦出来我前面说过text_indexing 默认依赖 SQLite FTS。鸿蒙系统自带的 SQLite 经实测FTS5 扩展情况并不可靠——API 版本、设备厂商的实现都有差异。与其赌系统库不如在适配时把存储层解耦做成一个StorageBackend抽象支持两种实现纯文件索引索引数据序列化后写入自定义二进制文件类似 sqlite 的 FTS 但由 text_indexing 自己控制格式。原生 SQLite通过鸿蒙侧插件访问 SQLiteFTS 能力由我们自己编译的库保证。像 text_indexing 这种库的常见用法是索引文件可以导出、迁移、合并纯文件索引反而更贴合它的设计。我最终选择的也是纯文件方案——把一个大的倒排索引按词条分片存文件查询时只加载命中的分片。这个方案在鸿蒙上的适配量最小而且不依赖系统 SQLite 的版本。4.2 第二步实现鸿蒙原生插件通道text_indexing 在 Dart 侧通过 MethodChannel 和原生通信鸿蒙侧需要实现对应的插件注册和通道处理。以我适配时用到的接口为例核心方法有这么几个createIndex、addDocument、search、deleteDocument、flushIndex。鸿蒙侧插件类的大体结构如下import { FlutterPlugin } from ohos/flutter_ohos; import { MethodChannel } from ohos/flutter_ohos; import { MethodCall, MethodResult } from ohos/flutter_ohos; export default class TextIndexingPlugin implements FlutterPlugin { onAttach(engine: FlutterEngine) { const channel new MethodChannel(engine, text_indexing/storage); channel.setMethodCallHandler((call: MethodCall, result: MethodResult) { switch (call.method) { case createIndex: this.createIndex(call.arguments(), result); break; case search: this.search(call.arguments(), result); break; // 其余方法同理 } }); } }这里有个关键点onAttach之后插件生命周期要跟 FlutterEngine 同步Flutter 页面销毁时插件要释放资源否则再次打开页面会出现重复注册的报错。text_indexing 的搜索可能跨越多个页面生命周期我在适配时把常用通道对象做成了单例避免重复创建。4.3 第三步处理沙箱路径差异这是整个适配过程中最隐蔽的坑。Android 上你可以直接用context.getFilesDir()拼路径iOS 用NSDocumentDirectory鸿蒙的沙箱路径结构和两者都不同。text_indexing 的 Dart 层会把索引文件路径当作字符串传给原生层如果路径拼接不对文件创建和读取会静默失败——不报错但索引永远是空的。我的处理方案是绝对路径只在原生侧生成Dart 层只传文件名不传全路径。鸿蒙侧通过getContext().filesDir拿到沙箱目录拼接好文件名后把最终路径返给 Dart 层缓存。这样确保两边操作的是同一个文件。4.4 第四步中文分词器的接入前面提过默认分词不适合中文这里展开说。我在 Dart 层实现了一个词典最大匹配分词器思路如下准备一个常用词词典按词长从长到短排序。对输入文本从左到右扫描每次尝试匹配最长的词典词条。匹配不到就按单字切分但记录相邻单字可合并的位置信息方便后续扩展。分词结果统一转成小写去掉空字符串按空格拼接后交给 text_indexing 的索引构建层。这个分词器代码量不大但有一个收益是立竿见影的索引体积大幅缩减。中文按单字索引你好世界会建立 4 个索引项按词索引你好和世界只有 2 个索引项。索引文件小了查询要扫描的数据也少了性能自然上去。5. 实测性能与调优全文检索在鸿蒙上的真实表现适配只是第一步能不能实际用起来取决于性能。我用一台 HarmonyOS NEXT 真机做了两组测试一组是 1 万篇文章的索引构建另一组是随机查询延迟测试数据比较有代表性。5.1 测试环境与数据集设备HarmonyOS NEXT 真机数据集随机生成的 1 万篇中文文本每篇 200-1000 字总计约 800 万字符对比基线同一个数据集上用 SQLiteLIKE %词%查询的耗时测试时要保证数据集有区分度不要全是高频词否则索引构建慢、查询看不出差异。我的做法是混入了一批低频术语模拟真实笔记场景。5.2 索引构建实测操作text_indexing鸿蒙化后SQLite LIKE 全表扫描建索引1万篇约 4.2 秒不适用无索引概念索引文件大小约 48 MB不适用首次查询2-8 毫秒480-900 毫秒热词查询高频词1-3 毫秒300-600 毫秒冷词查询低频词0-1 毫秒600-1200 毫秒可以看到建索引是一次性成本之后所有查询都在毫秒级和 LIKE 全表扫描完全不在一个数量级。冷词查询更快是因为低频词的倒排列表很短命中文档少排序计算也快。注意以上数据是单次冷启动后的表现首次启动加载索引文件会额外增加 100-200ms 的预热时间。对体验要求高的应用建议在启动页或后台线程提前调用一次预搜索触发索引加载。5.3 调优手段事务批量提交最开始我用逐条调用addDocument的方式批量导入 1 万篇文章耗时在 20 秒以上完全不能接受。后来改成事务批量提交每 200 篇文档作为一批批内共享同一个写入事务整体耗时直接降到 4.2 秒。原因是每篇单独提交时索引文件要不断执行打开-写入-关闭的序列化操作磁盘 IO 开销远大于索引构建本身。事务批量提交的代码实现不求复杂核心就一点Dart 层把 200 篇文档累积到一个 List一次性传给原生层或直接走 Dart 层的批处理接口。text_indexing 这类库通常有addDocuments这类批量方法实在没有也可以自己包一层。5.4 调优手段索引分片加载针对索引文件太大导致加载慢这个问题我做了一个分片策略按词条的首字母或哈希值把索引拆成多个分片文件查询时只加载包含命中词条的分片。800 万字符的索引拆成 16 个分片后单个分片平均只有 3 MB冷启动加载速度从 400ms 降到 150ms。分片不是越多越好分片过多会导致查询时要打开多个文件反而增加 IO 次数。我当时用 16 个分片是权衡过的文件大小和打开次数都比较均衡。如果你索引数据量不到 100 MB其实不分片问题也不大分片主要是解决索引文件太大导致加载卡顿的场景。5.5 一个反直觉的经验查询热词不一定比冷词快测试时我发现一个有意思的现象高频词的查询有时候比低频词慢。原因是高频词命中的文档太多打分排序要遍历的候选集大反而拖慢了响应。针对这个现象我做了两类优化截断策略单次查询最多返回 200 条结果评分排序只对前 2000 个候选文档做避免不做任何限制的暴力排序。停用词过滤像的了是这种停用词在索引构建时就过滤掉。这样既缩减了索引体积也避免了查询时被这些高频词拖慢。6. 踩坑记录适配过程中最棘手的三个问题适配过程不可能一帆风顺挑三个我在实际中遇到最费劲的问题把排查链路完整写出来。直接给你答案没意义重要的是这个排查思路。6.1 问题一索引文件创建成功但内容为空一开始我以为 MethodChannel 通了个寂寞Dart 层返回的索引文件大小永远是 0。排查过程在 Dart 层打印Directory.current和文件路径确认路径不是空字符串。在鸿蒙侧createIndex的 method handler 里打 hilog确认方法确实被调到了。发现原生侧返回成功但文件写入用的是相对路径——鸿蒙沙箱的当前工作目录并不是 Flutter 引擎的工作目录相对路径解析到了完全不同的位置。最终解决方案就是前面说的所有路径由原生侧通过filesDir拼接后返回Dart 层不再直接传绝对路径。这个问题的典型特征是不报错但行为不对最容易被忽略。6.2 问题二MethodChannel 异步回调被重复触发text_indexing 的大批量索引操作耗时较长我在鸿蒙侧做了异步处理结果发现 UI 偶尔卡死甚至出现同一批索引任务回调两次的诡异现象。排查过程先怀疑是 Flutter 引擎的 MethodChannel 有 bug查官方 issue 没找到对应项。在鸿蒙侧加日志后发现不是回调被触发两次而是 Dart 侧连续调用了两次同一个addDocuments方法——第一次在页面 A 发起页面 A 销毁时任务没取消页面 B 重建后又发起一次。根因是插件通道对象在页面销毁时没有正常 detach导致任务队列堆积。解决方案是给插件类实现onDetach方法在 FlutterEngine 销毁时取消所有未完成的异步任务。同时Dart 侧给大批量操作加了一个是否正在执行的互斥锁避免重复提交。6.3 问题三索引库自带的 SQLite 编译进鸿蒙后闪退我在测试用原生 SQLite 存储索引这条路时自己编译了一版带 FTS5 的 SQLite编译倒是通过了运行就闪退。排查过程用 hilog 抓崩溃栈发现崩溃发生在 SQLite 的sqlite3_open阶段提示 libc 库冲突。对比鸿蒙 Flutter 引擎自带的 .so 依赖列表发现我编进去的 SQLite 符号和系统库有重叠。尝试用动态链接模式替换但鸿蒙的沙箱机制对动态库的加载路径限制比较严最终还是放弃了原生 SQLite 方案改用纯文件索引。这个经历让我得出一个结论三方库鸿蒙化时优先考虑原生依赖最小化方案。能把逻辑放在 Dart 层就不要编原生库能不依赖系统 API 就不要依赖。文本索引这种场景纯文件索引的适配速度和稳定性远超原生 SQLite 方案印了那句老话少即是多。7. 一点收尾心得这个适配思路还能用到哪里text_indexing 的鸿蒙化适配本质是一套可复制的方法论先摸清三方库的平台依赖点再通过抽象存储层 重写平台通道 处理沙箱差异解决鸿蒙兼容问题最后用实测数据指导性能调优。这套思路不只适配检索类库实际上大部分 Flutter 三方库的鸿蒙化都能套用。我最近也在关注 Flutter 事件通道在鸿蒙上的表现EventChannel 在大数据量场景下的流式传输效率跟 text_indexing 的索引进度回调其实是一个道理。鸿蒙对整个 Flutter 生态来说还属于建设期三方库适配得越充分应用开发者的选择就越多。最后分享一个小经验适配前一定要把原始库在 Android/iOS 上的标准行为录下来比如索引构建耗时、查询结果排序规则、文件格式的二进制内容。鸿蒙化之后拿这个基准去对比能快速发现隐藏的行为差异。我在适配过程中就是靠对比索引文件的字节内容发现了一个排序字段大小端问题这种问题靠肉眼看 UI 根本发现不了。
