Flutter同步方案鸿蒙化适配：CRDT冲突治理实践

如果你和我一样，正被“把一套 Flutter 同步方案搬到鸿蒙”这件事搞得焦头烂额，那这篇文章基本是为你准备的。最近我正好完成了一个基于 crdt_sync 的鸿蒙化适配项目，过程中把“同步资产”这几个字从口号拆成了实实在在的类、方法、通道和存储策略，也踩了不少文档里根本不会写的坑。crdt_sync 这个三方库，说白了就是让 Flutter 应用具备离线优先的多端数据同步能力，它内部用 CRDT 算法解决并发冲突，不用服务器做中央仲裁也能让多端数据最终一致。听起来很美好，但一旦要适配鸿蒙，事情就变成了两层：一是 Flutter 层能不能跑通，二是原生通道和系统能力能不能对齐。

这篇文章我会讲清楚三件事：crdt_sync 的同步资产到底包含什么，CRDT 治理在鸿蒙环境里怎么一步步落实，以及整个鸿蒙化适配从依赖分析到桥接实现再到问题排查的完整路径。适合正在做 Flutter 跨端同步、或者刚拿到鸿蒙适配任务、对 CRDT 有一定了解但还没真正上过生产环境的人。

1. 先搞懂 crdt_sync 是什么，以及鸿蒙化适配的本质

1.1 crdt_sync 的定位和它的同步资产

很多人第一次看到 crdt_sync，会以为它只是一个普通的数据库同步库。其实它的定位更接近一个“多端协作基础设施”。它提供的是数据结构级别的同步能力：你定义一份可同步的业务数据，库帮你负责这个数据在多个终端之间的传播、合并和冲突收敛。所谓“同步资产”，我习惯把它拆成四块来看：

• 数据实体：真正需要跨端同步的业务数据，比如文档正文、任务列表、用户资料。
• 操作日志：每次变更产生的带有因果依赖的操作记录，这是 CRDT 能够回放和合并的基础。
• 同步通道配置：网络协议、鉴权信息、同步触发的策略（实时推送还是定时拉取）。
• 冲突规则：针对不同数据结构配置的合并策略，比如计数器用哪种 CRDT、集合用哪种。

在鸿蒙化适配之前，这四块资产都跑在 Flutter 的应用沙箱里，看起来和平台无关。但实际跑起来，问题全出在“看起来无关”的地方：底层的存储引擎、网络链路、后台任务的调度策略、甚至日志文件写到哪个目录，都是平台行为。鸿蒙化适配的第一步，不是写代码，是把这份资产清单逐一盘点清楚，判断哪些能平移、哪些必须替换。

1.2 鸿蒙化适配的本质：平台能力映射，而不是重写

克里特岛的迷宫之所以难走，是因为你手里拿的是另一座岛的地图。鸿蒙化适配的道理也一样：crdt_sync 在 Android 和 iOS 上能跑通，是因为它依赖的那几条原生能力在这两个平台上都有成熟映射，比如数据库、网络栈、后台执行权限。到了鸿蒙上，这些能力要么换了名字，要么换了调用方式，要么干脆需要通过 JSBridge 或者元能力服务间接访问。

所以适配工作的本质，是做一个“能力映射表”：把 crdt_sync 所依赖的每一条原生能力，对应到鸿蒙生态里的实现方案，再分优先级逐个落地。这个过程最忌讳的是上来就改 Dart 代码。一旦你在纯 Dart 层加了平台判断，后续不用猜，代码会烂成一锅粥。正确的做法是保持业务层不动，把平台相关的能力全部隔离在插件通道后面。

1.3 适配前的策略选择：全量替换还是渐进式桥接

鸿蒙化适配有两条路线。一条是把 Android 插件里的原生代码用 ArkTS 重写一遍，再把 crdt_sync 的 Dart 层通过条件导入切到新的实现；另一条是保留主体逻辑，在鸿蒙侧写一个桥接层，把大粒度的原生能力通过 MethodChannel 暴露给 Dart。我在这次项目里选的是第二条路线，原因很实际：改造成本低、风险小，而且可以在不修改 crdt_sync 源码的前提下完成对接。只有那些确实无法在桥接层表达的逻辑，才下沉到 ArkTS 侧去实现。

2. 动手前的底细排查：依赖梳理与能力差距分析

2.1 从纯 Dart 依赖到原生实现的全链路梳理

我在周五下午用一条命令把整个项目的依赖树导了出来，盯着 crdt_sync 的依赖关系看了整整一个小时。这一步值得做细：你不能只盯着顶层库，要顺着依赖链往下挖。crdt_sync 在表面上只暴露了几个数据结构和同步接口，但它背后可能依赖了本地数据库、消息编码库、加密库，这些库在鸿蒙上有没有对应实现，直接决定了你的适配工作量。

我的做法是建一个三层表格来梳理：第一层是纯 Dart 实现的包，标注“可复用”；第二层是带原生代码的 Flutter 插件，标注“需要验证”；第三层是 crdt_sync 自身涉及平台通道的调用点，标注“必须桥接”。然后把每个“必须桥接”的调用点，逐一提取出它需要的平台能力，比如“持久化存储”“获取系统时间”“网络请求”“生成唯一 ID”。这套梳理做完之后，哪些地方要动手就一目了然了。

2.2 鸿蒙侧基础能力盘点

在确认 crdt_sync 需要哪些平台能力之后，紧接着要做的是清单对照。鸿蒙的应用开发框架提供的能力和 Android 并不完全一致，但它们之间存在明显的对应关系。比如文件读写路径，Android 拿的是应用私有目录，鸿蒙侧也有类似的沙箱目录；数据库这块，SQLite 在鸿蒙上仍然可用，但需要引入对应依赖；网络请求和 WebSocket 都能跑，不过鉴权方式和全局网络配置是另一套语法。

真正需要谨慎的，是那些和“后台行为”相关的能力。crdt_sync 一般不会主动在后台拉数据，但一旦你配置了周期同步或者监听来自服务端的推送，就涉及后台任务的调度。鸿蒙对后台任务的限制比 Android 更严格，这一点在盘点阶段必须确认清楚，否则适配完了，一到真机上电发一条同步请求就被系统掐断，那种体验非常像熬夜写了两天代码之后被产品经理一句话打回原形。

2.3 输出一份“能力差距矩阵”

能力差距矩阵是给整个适配团队看的东西，也是自己判断工作量的核心工具。我按这样的格式做了表格：

这个表格看起来不复杂，但真正有价值的地方在于它逼着你把“风险等级”和后面每一步实施动作关联起来。风险等级高的部分，就要预留出独立验证的时间；风险等级低的，可以在联调阶段顺带覆盖。我见过不少适配项目失败，就是因为一开始闷头写代码，结果网络通道这个中风险项在最后一周变成阻塞项。

3. 从通道到桥接层：核心适配实施指南

3.1 改造 Dart 层封装：把平台差异藏进接口后面

进入实现阶段，我给自己定了一条铁律：不动 crdt_sync 对外的主要 API。所有适配工作都必须发生在平台桥接层。操作上，我用 Dart 的条件导入机制，把原本直接依赖 MethodChannel 的调用点替换成一个自定义的桥接类，叫它 CrdtSyncBridge。这个桥接类对上层暴露五个方法：initialize、syncOnce、watchChanges、applyLocalChanges、destroy。上层业务完全不知道这套实现是跑在 Android 还是鸿蒙上，它只需要调用这五个方法，就能完成一次完整同步生命周期。

有人可能会问，MethodChannel 本身在不同平台上的 Dart 侧代码不是一样的吗？为什么还要在 Dart 层包一层？原因很简单：crdt_sync 的每一个原生调用点，参数格式和返回值结构并不统一，有些地方还需要把 Dart 的 Map 转成标准化的同步消息体。如果不做这层收口，你要在 crdt_sync 内部几十个方法调用点里逐个加兼容分支，那个场面光想想就会头皮发麻。收了这一层之后，鸿蒙和 Android 的差异被隔离在不到两百行 Dart 代码里，后续维护成本大幅下降。

这里给出一段示意性代码，Dart 侧的桥接类核心结构如下：

abstract class CrdtSyncBridge { Future<void> initialize(Map<String, dynamic> config); Future<Map<String, dynamic>> syncOnce(); Stream<Map<String, dynamic>> watchChanges(); Future<void> applyLocalChanges(Map<String, dynamic> changes); Future<void> destroy(); } class CrdtSyncBridgeHarmony extends CrdtSyncBridge { static const MethodChannel _channel = MethodChannel('crdt_sync/bridge'); final EventChannel _eventChannel = EventChannel('crdt_sync/events'); @override Future<void> initialize(Map<String, dynamic> config) async { await _channel.invokeMethod('initialize', config); } @override Future<Map<String, dynamic>> syncOnce() async { final result = await _channel.invokeMethod('syncOnce'); return Map<String, dynamic>.from(result as Map); } // watchChanges 使用 EventChannel 实现 }

3.2 ArkTS 侧实现：注册通道、处理调用、返回标准化结果

Dart 侧封好了，真正磨人的地方在鸿蒙原生侧。以我使用的鸿蒙 Flutter 适配方案为例，ArkTS 侧注册一个自定义插件，核心步骤是拿到 MethodChannel 的实例、实现 setMethodCallHandler、在 handler 里分发方法名并返回标准化结果。

ArkTS 侧的关键代码框架大致如下，不同版本框架的注册方式略有差异，但整体思路一致：

import { MethodChannel, MethodCall, Plugin } from '@ohos/flutter_ohos'; export class CrdtSyncPlugin extends Plugin { private channel: MethodChannel; constructor(context: Context) { super(context); this.channel = new MethodChannel(this, 'crdt_sync/bridge'); this.channel.setMethodCallHandler(this.handleMethodCall.bind(this)); } private async handleMethodCall(call: MethodCall): Promise<Object> { switch (call.method) { case 'initialize': { const config = call.arguments as Map<string, Object>; return await this.initializeSync(config); } case 'syncOnce': { return await this.syncOnce(); } default: return Promise.reject(new Error(`Unknown method: ${call.method}`)); } } }

这段代码看起来简单，但有几个细节必须注意。

第一，MethodChannel 的 name 要和 Dart 侧完全一致，连大小写都不能差，否则调用直接抛 MissingPluginException。

第二，handleMethodCall 的返回类型必须是 Promise，否则同步方法当场卡死。

第三，所有参数在 ArkTS 侧拿到的类型不一定是 Dart 里的原始类型，尤其是 Map 的嵌套结构，经常是序列化之后的对象，取值时要先做一次类型收敛，否则后续逻辑全是运行时异常。

3.3 数据序列化方案：别在最容易出问题的地方偷懒

序列化是整个桥接层里埋雷最多的环节，没有之一。crdt_sync 在 Dart 侧用的是标准对象结构，但通过 MethodChannel 传过去之后，ArkTS 侧拿到的是泛化的 Object。如果你是传递 Map<String, dynamic>，这个时候要特别注意数值类型的精度问题。Dart 的 int 是 64 位，ArkTS 里的 Number 在极端情况下会有精度丢失的风险。同步操作里的 lamport 时钟一旦丢精度，整个 CRDT 排序直接错乱，这个后果相当严重。

我的方案是：所有跨通道传递的整数统一在 Dart 侧转化为字符串，ArkTS 侧解析字符串后转换为对应的整型。虽然多了一步解析，麻烦一点，但换来的是确定性。对同步数据来说，确定性比性能更重要。还有一点值得提醒：不要擅自把数据压缩成自定义的二进制格式。crdt_sync 内部的同步消息是有格式约定的，你在桥接层做转换，等于给自己造了一个难以排查的兼容层。数据格式尽量保持原样传递，只在边界做类型修正和精度处理。

4. 同步能力的鸿蒙化落地：从初始化到冲突治理

4.1 初始化流程：建立同步上下文

crdt_sync 的初始化不是一行调用那么简单。它在内部要做三件事：恢复本地存储中的历史状态，建立同步通道的配置，以及初始化工作区。鸿蒙化之后，这三件事都会和系统能力纠缠在一起。

第一件恢复历史状态，要读取上次同步落盘的数据。这部分我直接复用了鸿蒙侧的文件接口，路径需要重新适配到当前应用沙箱目录，千万不能硬编码 Android 时代的路径。第二件建立同步通道，涉及到网络权限和线程模型，建议初始化时保持和 Android 一致的回调语义，不要刻意提前建链。第三件初始化工作区，在 ArkTS 侧维护一份同步引擎实例，注入到后续所有同步请求中。

初始化失败的情况需要认真处理。我把初始化拆成了两步：第一步加载本地存储，失败不阻塞应用启动；第二步建立同步通道，失败则进入降级模式，只保留本地写入能力。这样适配之后，即使网络环境极差，用户的本地编辑也不会丢。

注意：鸿蒙侧初始化时，优先检查应用是否已获得网络访问权限。因为权限确认是异步过程，直接调用同步方法会偶发失败，别问我怎么知道的，血泪教训。

4.2 同步触发机制：从周期性到事件驱动的平衡

crdt_sync 支持多种同步触发方式：手动调用 syncOnce、监听远端推送、以及周期性自动同步。在鸿蒙平台上，我建议把周期同步的间隔调得比 Android 长一些，并且一定要结合系统后台任务的窗口期。否则你会发现，逻辑上每 30 秒触发一次同步，但在鸿蒙上实际可能一小时只能执行几次，因为系统把后台任务压缩了。

我的平衡策略是三层触发：第一层，应用在前台使用且有数据变更时，立即执行一次增量同步；第二层，应用进入后台前，做一次尽力而为的全量快照同步；第三层，低频的周期同步作为兜底。这样用户感知到的“实时协作”没有损失，系统后台的压力也控制在合理范围内。

4.3 CRDT 冲突治理：同一份数据在两端被同时改了怎么办

里聊 CRDT，不把它原理讲透很难往下走。CRDT 的核心价值是让每个终端独立处理变更，然后在同步时合并，最终收敛到一致状态，且不需要中心服务器仲裁。crdt_sync 在内部实现了多种 CRDT 结构，对应到不同的业务场景：

• 计数器类数据，比如点赞数、库存数，用 G-Counter 或 PN-Counter，合并规则是取最大值或累加增量。
• 集合类数据，比如在线用户列表、标签列表，用 OR-Set，通过给每个元素附加唯一标识来解决重复添加和删除冲突。
• 文档类数据，比如富文本正文，用基于序列的 CRDT，插入操作会携带位置引用，合并后不会丢字也不会乱序。

我在适配过程中并没有修改任何 CRDT 算法本身，这些算法是纯 Dart 实现的，跨平台不涉及系统调用。真正需要治理的是属性映射。比如 OR-Set 里每个元素的唯一标识，在 Dart 侧可能是 64 位整数，到了 ArkTS 侧如果走了一遍 Number 转换，精度就丢了。我采取的办法是让标识长度限制在 32 位可安全表达的范围，或者干脆用字符串作为标识。分层看，CRDT 算法像是大脑，桥接层像是神经，治理的核心就是确保神经信号不衰减，某个位都不能错。

4.4 同步状态的监控与治理

同步资产治理不只是管数据本身，还要管同步过程和状态。crdt_sync 会维护一份同步状态，包括待发送操作数、已确认操作数、本地未推送的变更数、连接状态。在鸿蒙化落地时，我把它映射成了四类指标：

• 延迟指标：从本地变更到远端确认的耗时。
• 吞吐指标：单次同步里处理的变更操作数。
• 积压指标：本地待同步但未成功的操作数，这是最值得盯的数字。
• 失败指标：同步失败的类型分布，网络失败、序列化失败、权限失败要分开统计。

其中积压指标最容易被忽略。很多人只看“同步成功了没”，一旦同步成功就认为数据没丢。但 crdt_sync 的同步是分批进行的，如果增量同步过程中反复失败，待发送队列会越长越大，直到触发恢复逻辑。所以我在鸿蒙侧加了本地监控面板，把积压操作数实时显示出来，超过阈值就报警。这个面板耗时不大，但对及时发现问题起了很大作用。

5. 适配过程中我踩过的那些坑

5.1 精度丢失导致 CRDT 状态错乱

这是我踩得最疼的一个坑。某次联调，发现两台设备上的同一份文档，在同步几次之后出现了顺序错乱。排查了很久，最终定位到是一个 ID 生成器返回了超过 2 的 53 次方的整数，Dart 侧没问题，传到 ArkTS 侧经过一次浮点转换，末尾几位直接变了。由于 CRDT 的排序严重依赖操作 ID 的全局唯一性和单调性，一个 ID 变化，整个合并顺序全部被打乱。

修复方案就是前面提到的，所有跨通道传递的整数统一转字符串。这个改动看起来简单，但需要顺着桥接接口把所有参数都过一遍，不能漏。

5.2 事件通道的消息乱序

crdt_sync 有一个 watchChanges 方法，用来监听远端的变更事件。我在鸿蒙上第一次跑通时，发现收到的事件顺序偶发和发送顺序不一致。查下来原因是 EventChannel 的事件在 ArkTS 侧发出时，经过异步闭包后顺序无法保证。这个问题的解决方案是在事件体里加上自增序号，在 Dart 侧消费时做一次排序缓冲。CRDT 本身具备乱序合并能力，所以对最终一致性没有影响，但为了保证事件流的可预期性，排序缓冲还是很有必要。

5.3 后台同步被系统强制性停掉

鸿蒙系统的后台任务约束让周期同步变成了一件不太容易的事。本来我以为和 Android 一样，注册一个后台任务就能跑，结果真机上跑了一天，发现同步日志里凌晨两点到早上七点的记录完全是空的。调试后发现，系统对没有亮屏、没有充电、且用户没有主动打开应用的长时间后台任务做了收敛。这不是错误，是系统设计如此。

我没有选择关闭这个限制，而是把同步策略改成“重建式同步”：应用每次从后台切回前台时，先读取本地状态，再主动向远端拉取增量，以本地积压数据为准进行合并。这样即使后台完全不做同步，也不会丢数据，最多是用户打开应用时有一次短暂的同步等待。

5.4 常见问题速查表

写在最后的一点体会

把 crdt_sync 鸿蒙化的整个过程中，我最深的体会是：做适配和做新功能完全是两种心态。做新功能时你写的是从无到有，做适配时你写的是“为什么两边表现不一样”，每一个坑的背后都是一次平台差异的深刻理解。如果你也在做类似的事，建议从一开始就维护好那份能力差距矩阵，并且在桥接层所有跨通道传递的值上都套一层“严格类型”的保险。别指望一次就能跑通，留足排坑的时间，比赶进度更有价值。那台用于回归测试的鸿蒙工程机，后来成了整个团队排查问题场景下使用频率最高的设备，这大概就是适配工程的宿命。