直接说结论：如果你们团队正在做 Flutter 跨端应用，又被离线同步、多端冲突合并折磨得头疼，那sql_crdt这个库值得花点时间认真研究。它把 CRDT 那一套理论上很复杂的一致性模型，直接封装成了 SQLite 里能跑、Dart 里能调的东西。而放到鸿蒙生态里，这事儿的复杂度会再上一个台阶——不是 CRDT 本身难，而是 Flutter 在鸿蒙上的原生依赖适配、插件通道、数据库落盘这些环节，处处都有坑。这篇文章就是把我实际踩过的、验证过的鸿蒙化适配路径完整记录下来，从方案选型到核心原理，再到一步步代码落地和排错实录，全给你捋清楚。
网上关于 CRDT 的理论文章其实不少，但大多停留在"讲了概念但不知道怎么写代码"的层面。sql_crdt属于那种直接给你可运行方案的库，它既能帮你在本地用 SQLite 可靠落盘，又能通过同步协议让多个设备最终收敛到一致状态。这篇文章适合正在做 Flutter 三端（Android/iOS/鸿蒙）应用、需要处理离线数据的开发者，也适合那些刚接触同步冲突、想从原理层面搞懂 CRDT 为什么能解决这些问题的朋友。
1. 方案选型：离线同步到底难在哪，为什么最后选中了 sql_crdt
1.1 离线同步的典型痛点
先还原一下业务场景。假设你在做一个数据采集类的应用，用户在野外、地铁、电梯里网络不稳定，录入的数据要先存在本地，等有网了再上传。这时候最朴素的做法是"本地存一份 + 时间戳同步"，但时间戳方案在真正多设备、多用户协作的场景下会崩得很彻底——A 设备 10:00 改了字段 X，B 设备 10:01 也改了字段 X，两边都认为自己是"最新的"，同一时间戳甚至同毫秒级别的修改到底听谁的？后端拿不到足够的信息来决定保留哪一份，数据就直接错乱了。
更麻烦的是删除与修改的竞争：一条记录在 A 设备被删除了，在 B 设备又被修改了，后台合并的时候究竟是恢复还是保留修改？普通方案根本处理不了这种语义层级的问题。这也是为什么我在评估了多个方案之后，坚定的把 CRDT（Conflict-free Replicated Data Types，无冲突复制数据类型）作为基线方案的原因。
你可能听说过 OT（Operational Transformation，操作转换），就是 Google Docs 用的那套，但 OT 的复杂度在于必须依赖中心化服务端做操作转换，离线场景下多个副本同时编辑时协调成本很高。而 CRDT 的核心思想非常简单直接：每个副本记录所有的更新操作（或者合并后的状态），这些操作在数学上满足交换律、结合律、幂等律，所以不管以什么顺序到达，最终都能合并出同一个结果。不需要中心服务器裁决，天生就是为离线优先（offline-first）设计的。
选了 CRDT 这个大方向之后，还得再选具体实现。我对比过几个方案：
| 方案 | 存储模型 | 适用场景 | 鸿蒙适配难度 |
|---|---|---|---|
| Yjs | 二进制编码的 CRDT，基于内存 + 可选持久化 | Web 编辑器协作 | 需要自建存储，无原生 Flutter 实现 |
| Automerge | JSON-like 文档 CRDT，Rust 核心 | 文档级离线同步 | 需要跨语言 FFI，鸿蒙端工具链复杂 |
| sql_crdt | SQLite 落盘 + 日志式 CRDT | Flutter 全平台离线同步 | 核心纯 Dart + 原生 SQLite 依赖，适配路径清晰 |
sql_crdt的优势在于是为 Flutter 和 SQLite 量身定做的。它的作者在实现了crdt这个纯 Dart 的 CRDT 库后，又做了一个 SQLite 持久化层，让整个状态不只是停留在内存里，而是能安全落盘。对于 Flutter 这种跨端框架来说，这意味着绝大部分逻辑可以复用，只有数据库这一层需要针对不同平台做适配。鸿蒙适配的难点也被缩小到了一个点：让 Flutter 在鸿蒙上能正常打开 SQLite 数据库。
1.2 为什么 SQLite 是落盘的最佳选择
移动端的本地存储选择，说来说去就那几个：SharedPreferences 只能存轻量 KV，不适合结构化文档；Hive 虽然纯 Dart 但底层是文件追加写，并发和事务支持弱；而 SQLite 是 Android/iOS 系统级标配，生态成熟，支持完整的事务、索引、SQL 查询。sql_crdt的作者选择 SQLite 做存储层，还有一个很现实的考量：SQLite 本身是 C 库，几乎可以在任何平台上编译，不管是 Android 的 SQLite、iOS 的 SQLite，还是后来鸿蒙 OpenHarmony 里集成的 SQLite，只要 Flutter 能把这个原生依赖打通，数据层就能跑起来。
另一个细节是，用 SQLite 做 CRDT 存储，天然就获得了 ACID 特性。CRDT 的合并算法虽然理论上是幂等的，但在实际落盘过程中，如果中途断电、进程被杀，数据库文件可能处于中间状态。SQLite 的事务机制能保证要么写入完整的日志记录，要么不写，这让整个系统的健壮性提升了一个量级。
2. 核心原理解剖：sql_crdt 的 PPDT 结构、不可变日志与同步协议
2.1 先把 CRDT 的类型搞清楚
在深入sql_crdt的实现之前，需要先明确它属于哪一类 CRDT。CRDT 大致分两种：
- 基于状态的 CRDT（State-based）：整个副本是一个可合并的状态，同步时把完整状态（或者定期合并后的状态）发给对方，对方做 merge 操作。实现简单、带宽消耗大。
- 基于操作的 CRDT（Operation-based）：广播的是单个操作（比如"把字段 A 的值设为 X"），每个副本重放这些操作，关键是要保证操作能可靠地传输和幂等地应用。
sql_crdt采用的是操作日志 + 定期快照的组合方案：每个文档的修改都会生成一条不可变的日志记录（record），这条记录包含操作内容、作者 ID、逻辑时间戳。本地应用时直接把操作应用到当前状态；同步时传输日志，对方重放日志就能达到一致。为了避免日志无限增长，它会在日志条数超过阈值时生成一个快照（snapshot），快照是某个时间点的完整状态，后续重放只需要从这个快照开始。
这个"日志式"设计比纯状态合并有一个显著优势：能保留完整的历史修改记录。你需要排查"这个字段到底是谁改的、什么时候改的"这种审计问题时，查日志就行。而且日志天然是 append-only 的，写 SQLite 时可以走顺序 IO，性能很好。
2.2 PPDT：一种高效的 JSON 文档 DAG 表示
sql_crdt没有停留在简单的 KV 型 CRDT 上，它实现了一种更复杂的数据结构，叫做PPDT（Prefix Partitioned Document Tree，前缀分区文档树）。这个名字听起来很吓人，但理解起来并不难。
想象你要同步的不是一个简单的计数器，而是一棵 JSON 树。比如一个清单应用有items数组，数组里每个元素又有title、checked字段。普通的 CRDT Map 模型很难优雅地处理数组元素的新增、删除、移动这些操作。PPDT 的想法是给每个数组索引分配一个稳定的标识符，索引前缀对应树上的路径。每次修改数组，不是对比索引位置（那会受插入删除影响），而是对比节点的稳定 ID。这样，两个副本各自在数组中间插入了不同元素，合并时就能通过前缀分区规则，自然地把两个元素都保留下来，而不会互相覆盖。
这个机制解决的是 CRDT 领域最难的问题之一——集合语义下的冲突合并。如果用朴素的"列表同步"，你根本没法分辨"A 删了第2项、B 在第2项插了一个新项"这种操作，到底最后应该保留几个元素。PPDT 通过给每项一个全局唯一标识，让每个操作都有明确的锚点，合并就变成了对标识符集合的操作，确定性很强。
2.3 不可变日志与 LWW 逻辑时钟
sql_crdt的每条日志记录包含以下核心字段（这是我看源码后的总结）：
| 字段 | 作用 | 备注 |
|---|---|---|
log_id | 日志唯一 ID | 由"作者 ID + 时间戳 + 序号"拼接而成 |
author_id | 作者标识 | 每次安装生成的随机 UUID |
timestamp | 逻辑时钟 | 基于毫秒时间戳 + 单调递增序号防冲突 |
op_type | 操作类型 | add/remove/set/move 等 |
path | 操作路径 | 对应 PPDT 树中的路径 |
value | 操作值 | 新增或修改的 JSON 值 |
这里最关键的机制是LWW（Last-Write-Wins，后写赢）策略。当两个副本对同一个路径产生了不同值时，sql_crdt会比较逻辑时间戳和作者 ID，取"时间戳更晚"或"作者 ID 更大"的操作作为最终值。这个策略不是 CRDT 里最复杂的，但它是生产环境里最容易解释、最容易调试的策略。它保证了一个强收敛性：不管各副本以什么顺序、什么时间收到这些日志，最终都会因为确定性比较而得到同一份数据。
有人可能担心 LWW 策略"后写赢"会不会丢失数据——比如两个用户在离线时分别对同一段文字做了完全不同的修改，合并后只留下其中一个。这在纯粹文本协作的场景确实有局限，但对绝大多数表单类、事务类、数据采集类业务是够用的。如果业务需要真正的"合并两个意图"，那应该走字段级 CRDT，比如把每个独立字段拆成一个 CRDT 寄存器，sql_crdt的 PPDT 结构其实已经支持到 path 级别了，所以你可以把"整个对象"拆成"多个字段路径分别处理"，用结构化设计来规避 LWW 的语义丢失问题。
2.4 同步协议的拉取与推送流程
sql_crdt的同步协议非常清爽，官方文档里用了一个叫Synced的类做了封装，核心在于两件事：知道对方缺什么日志，把我有的给对方；知道对方有什么而我缺的，从对方拉取。
具体实现是：
- 两端都把自己已同步到的日志水位（
last_log_id）告诉对方。 - 本地扫描数据库，找到所有大于该水位的最新日志，封装成
SyncMessage。 SyncMessage通过你自己的网络层发送给对端。- 对端收到后，把消息里的日志逐条应用到本地数据库，更新水位。
这个协议虽然简单，但要注意一个问题：网络层必须可靠投递。因为它是基于"增量日志"的设计，如果一条日志丢了，后续同步会陷入不一致。所以我在落地时，给消息加了一层至少一次（at-least-once）的确认机制，应用层记录了每条日志的 ack 状态，超时重发。好消息是 CRDT 的幂等性让重复投递不会有副作用，你不需要复杂的去重逻辑。
3. 鸿蒙化适配实操：环境准备、依赖分析与逐步落地
3.1 底层认知：鸿蒙上的 Flutter 运行机制
聊适配前，先得搞明白鸿蒙上的 Flutter 是怎么跑起来的。OpenHarmony 社区维护了一个flutter_flutter的分支，这个分支把 Flutter Engine 编译成了鸿蒙系统的动态库，Dart 代码经过 AOT 编译后运行在鸿蒙的运行时上。这意味着你的 Dart 层代码几乎不用改，但任何涉及原生能力（文件、数据库、网络、传感器）的插件，都需要找到鸿蒙版本的原生实现。
在鸿蒙生态里，插件机制和 Android 类似：Dart 侧通过MethodChannel或者FFI调用到原生侧，原生侧用 ArkTS、C++ 来实现。但鸿蒙插件和 Android 插件不能直接复用，因为鸿蒙的系统 API、封装方式完全不同。好在 OpenHarmony 的生态已经积累了一批常用插件的鸿蒙适配版，比如sqflite_harmony、shared_preferences_harmony、device_info_harmony之类。
3.2 检查依赖树：分清纯 Dart 与原生依赖
鸿蒙化适配的第一步，不是急着改代码，而是先跑一遍flutter pub deps，把整个依赖树拉出来，分清哪些是纯 Dart 包、哪些带了原生代码。以sql_crdt为例，它的直接依赖是crdt和sqflite：
crdt：纯 Dart 实现，实现了 CRDT 的核心数据结构（LWW Map、PPDT 等）。这个包没有任何原生代码，在鸿蒙上可以直接用，不需要改动。sqflite：Flutter 官方的 SQLite 插件，在 Android/iOS 上有原生实现，但鸿蒙上需要用sqflite_harmony来替换。
所以整个鸿蒙化适配的核心，就是把sqflite这个依赖在鸿蒙工程里替换成鸿蒙能用的 SQLite 插件。听起来简单，但实际操作中会有不少坑，因为sql_crdt在代码里直接import 'package:sqflite/sqflite.dart'并调用其 API，替换意味着要么全局改 import，要么用 Dart 的条件导入机制去适配。
3.3 第一步：创建鸿蒙 Flutter 工程并接入洪蒙 SDK
具体流程我建议这么走。首先用flutter create --platforms=ohos .在项目根目录生成鸿蒙平台的壳工程（需要你已经安装了适配 OpenHarmony 的 Flutter SDK 分支，以及 DevEco Studio）。然后确保鸿蒙 SDK 路径、签名配置正确，让一个最简单的 Flutter 页面能跑在鸿蒙设备或模拟器上。这一步如果跑不通，后面适配无从谈起。
提示：如果你还没有安装鸿蒙的 Flutter 分支，建议先去 OpenHarmony 官方仓库按文档完整配置一遍。这里容易踩坑的是环境变量
OHOS_SDK_HOME没设置对，导致构建时找不到 SDK。实测用 DevEco Studio 自带的 SDK 路径最稳妥。
3.4 第二步：替换 sqflite 依赖与桥接层设计
既然sql_crdt内部是import 'package:sqflite/sqflite.dart'，最直接的方案是全局替换为sqflite_harmony的导入。但这么做的缺点是：如果将来还要跑回 Android/iOS，就得来回改。
我采用的方案是做一层数据库工厂抽象。具体来说：
- 在项目里建一个
db_factory.dart，内部根据Platform.isOhos判断返回哪种数据库实现。 - Android/iOS 走
sqflite插件；鸿蒙走sqflite_harmony插件。 - 通过依赖注入的方式，把数据库实例传给
sql_crdt的Synced或者Database类。
sql_crdt的接口设计得还算干净，它接收一个数据库实例，然后自己建表、做 CRDT 逻辑。所以只要你能给出一个在鸿蒙上能成功打开、能执行 SQL 的数据库对象，核心逻辑就能跑起来。
import 'package:sqflite/sqflite.dart' as sqflite; import 'package:sqflite_harmony/sqflite_harmony.dart' as sqflite_harmony; import 'package:platform/platform.dart'; Future<Database> openDatabaseWrapper(String path) async { if (Platform.isOhos) { return sqflite_harmony.openDatabase(path); } return sqflite.openDatabase(path); }注意：
sqflite_harmony的 API 设计目标是兼容sqflite的，但毕竟不是官方同步维护，某些方法名、参数类型可能不完全一致。实测下来基本操作（openDatabase、execute、query、insert）都能兼容，但事务相关的高级方法（如withTransaction）出现过一次签名不一致的情况，需要手动适配。
3.5 第三步：处理数据库路径与初始化问题
sql_crdt默认的存储路径在getDatabasesPath()下，但鸿蒙上这个路径返回的目录结构跟 Android 的不一样。你需要在测试时先打日志，确认路径是否可写、是否存在。
鸿蒙沙箱目录在应用私有目录下，一般长这样：/data/app/el2/100/base/com.example.yourapp/haps/entry/files/。如果getDatabasesPath()返回的是只读目录，你需要在工厂里显式拼一个可写的路径。
final dir = await getDatabasesPath(); // 确认是否为可写目录 final dbPath = '$dir/sql_crdt_demo.db';我在实测中还发现，如果应用有多个入口（比如元服务、API 版、entry 模块），它们的沙箱目录是隔离的，数据库文件不会共享。如果你的应用有多个模块需要访问同一份数据，你得自己解决文件共享问题，或者统一把数据库放到外部存储目录（需要申请权限）。
3.6 第四步：验证插件通道是否真正打通
所有代码改完之后，最关键的一步是跑通一次完整的数据库读写流程。我会写一个冒烟测试：打开数据库、建一张表、插入一条数据、再读出来、删掉。如果这条链路在鸿蒙上走通，那sql_crdt的底层依赖就稳了。
这个环节最容易遇到的问题不是 API 不兼容，而是原生插件在鸿蒙上没有注册。Flutter 的插件发现在鸿蒙上跟 Android 不太一样，鸿蒙侧需要手动在模块配置里声明依赖并完成注册。如果没有注册，Dart 侧调用MethodChannel时会直接抛MissingPluginException。
排查方式很简单：跑起来后看控制台日志，如果出现MissingPluginException，去检查鸿蒙工程的oh-package.json5和模块的依赖配置，确认已经正确引入了sqflite_harmony。
3.7 核心代码改造点清单
把上述所有步骤整理成一张可执行的清单，方便你在自己的项目里对照操作：
- 环境准备：安装 OpenHarmony Flutter SDK 分支，配置 DevEco Studio，跑通基础 Flutter 鸿蒙应用。
- 依赖替换：在
pubspec.yaml中引入sqflite_harmony，并用数据库工厂模式隔离平台差异。 - 数据库路径处理：打印
getDatabasesPath()确认沙箱路径可写，必要时手动指定路径。 - 插件注册检查：确保鸿蒙工程配置里已注册
sqflite_harmony，避免运行时报MissingPluginException。 - 数据读写冒烟测试：用最基础的增删改查验证数据库通道可用。
sql_crdt集成：创建Synced实例，进行 document 级别的 CRDT 操作。- 双端同步验证：一个模拟器 + 一台真机（或两个模拟器）离线操作后手动触发同步，比对数据一致性。
4. 同步场景的完整落地：从数据模型设计到双端一致验证
4.1 数据模型的 CRDT 化设计
把sql_crdt接入项目后，第一件事是重新审视你的数据模型。CRDT 并不是兼容所有数据结构的银弹，比如一个强相关的图结构（好友关系、树形审批流）用 CRDT 表达会非常别扭，而扁平的表单、任务清单、配置项则非常适合。
以我实际的"设备巡检"业务为例，一条巡检记录大致长这样：
{ "id": "inspection_001", "deviceId": "device_alpha", "inspector": "张三", "items": [ {"key": "温度", "value": 36.5, "unit": "℃"}, {"key": "压力", "value": 101.3, "unit": "kPa"} ], "remark": "一切正常", "status": "completed" }用sql_crdt建模时，我会建议把记录拆成：
inspection_001/profile：一个 LWW 寄存器，保存inspector、status等标量信息。inspection_001/items：一个 PPDT Map，保存巡检项列表，每项有独立 ID。inspection_001/remark：一个单独的 LWW 寄存器。
这个设计的好处是：字段之间的同步粒度互不干扰。如果用户在 A 设备只改了remark，在 B 设备只改了status，合并后两个修改都能保留。如果你把它们硬塞进一个大的 LWW 寄存器里，那就只能"后写赢"，一次修改会覆盖掉另一边的所有内容。
4.2 创建文档、本地修改与持久化
在sql_crdt中，文档 Document 是核心入口。创建一个文档并写入初始值：
import 'package:sql_crdt/sql_crdt.dart'; final db = await openDatabaseWrapper('/path/to/your.db'); final synced = Synced(db); await synced.createDocument(docId: 'inspection_001'); final doc = synced.getDocument('inspection_001'); // 对文档做修改 await doc.set('profile/status', 'completed'); await doc.set('profile/inspector', '张三'); await doc.set('items/item001/key', '温度'); await doc.set('items/item001/value', 36.5); await doc.set('remark', '一切正常');每次调用set都会在本地生成一条日志记录并写入 SQLite。这一步是同步的，写完本地事务才返回，所以数据是不会丢的。你可以模拟断网环境反复调用这些方法，本地数据会正确落盘。
4.3 两个设备的同步合并测试
同步的核心是调用sync()产生待发送的消息，以及接收对端消息后合并。典型流程：
// 设备 A 生成需要同步给 B 的消息 final syncMessage = await synced.sync(docIds: ['inspection_001']); // 通过网络发送 syncMessage（示例用了自定义 sender 函数） await sender(syncMessage.toJson()); // 设备 B 收到消息后合并 final syncedB = Synced(dbB); await syncedB.receiveRemote(syncMessage);设备 B 收到消息后，SQLite 里会应用所有 A 的日志。此时如果 B 本地也有一份修改，sql_crdt内部的逻辑时钟比较会解决冲突。我在测试时特意做了两个场景：
- 无冲突同步：A 只改
remark，B 只改status，合并后两边都有两个修改。 - 同字段冲突：A 和 B 都改了
status，A 是completed，B 是pending，合并后两边都收敛到同一个值（逻辑时间戳更新的那个）。
第二个场景尤其在验证时需要额外小心：你需要在合并前记录两边的日志水位，合并后逐条检查最终值，确保两边完全一致。我写了一段断言逻辑，对每个文档、每个字段路径做最终的比对，确保没有分叉。
4.4 快照机制与存储优化
日志无限增长是所有日志型 CRDT 的通病。sql_crdt会在日志数量超过阈值后自动生成快照。快照是一个 JSON 序列化的完整文档状态。启用快照后，同步不再需要传输整个日志历史，只需要"从快照之后新产生的日志"。
实操中我把快照阈值设成了 100 条日志，这样同步消息体积能控制在几 KB 到几十 KB 以内。对于大规模文档，这个优化是决定性能的关键。
5. 真实踩坑记录与性能实测：不藏私的问题汇总
5.1 鸿蒙端高频报错的定位与解决
| 问题 | 表现 | 原因 | 解决方案 |
|---|---|---|---|
MissingPluginException | 打开数据库即报错 | sqflite_harmony 插件未注册 | 检查 oh-package.json5 与模块依赖 |
getDatabasesPath不可写 | 创建库文件失败 | 沙箱路径不正确 | 手动拼接可写沙箱路径 |
事务withTransaction崩溃 | 高级事务方法未实现 | sqflite_harmony API 未完全对齐 | 改写为多个原子操作 |
| 中文乱码 | JSON 中文写入异常 | 字符编码转换问题 | 统一 UTF-8，并检查 SQLite 的 encoding pragma |
| 同步数据量过大 | 频繁同步导致卡顿 | 日志条数太多 | 调小快照阈值，定期清理旧日志 |
5.2 同步时数据不一致的真实现场
有一次测试，两个设备合并后出现了少数据的情况：A 设备有 5 条巡检项，B 设备有 5 条巡检项，合并后却只有 8 条而不是 10 条。排查发现，我在两个设备上使用了相同的 item ID去创建数据。因为 PPDT 是"按 ID 去重"的，相同 ID 的项会被认为是同一条数据的不同版本，于是合并时直接合并成了同一条记录。
这个问题的本质是ID 分配策略错误。CRDT 要求每个实体必须有全局唯一的 ID，不能只在单端生成。正确做法是使用 UUID 或"设备 ID + 自增序号"的组合来生成 item ID。调整之后，再测合并，10 条数据就完完整整地保留了。
提示：这是 CRDT 实战中最容易翻车的点。很多人以为 CRDT 天然解决所有冲突，但实际上它解决的是"同 ID 实体下的值冲突"，而不是"不同 ID 实体的归属冲突"。ID 生成策略必须从系统设计上保证全球唯一。
5.3 性能数据：离线同步的实测基准
我在一台鸿蒙开发板上跑过压力测试，数据如下供参考：
| 数据量 | 操作类型 | 耗时表现 |
|---|---|---|
| 1000 条日志 | 写入 | 约 80ms，SQLite 事务批处理 |
| 1000 条日志 | 合并/重放 | 约 350ms，IO 为主 |
| 5000 条日志 | 快照生成 | 约 1.2s，内存占用可控 |
| 5000 条日志 | 全量同步消息序列化 | 约 2.1MB，需压缩后传输 |
对于中小型业务，sql_crdt的性能完全够用。但如果你的文档特别大、写入特别频繁，建议减小快照阈值，例如设成 50 条，这样单次同步的消息体积能显著下降。
5.4 原生依赖包的核心源码解读
再补充一点底层知识。sql_crdt的 SQLite 表结构非常简洁，核心是一张名为records的表：
CREATE TABLE records ( log_id TEXT PRIMARY KEY, doc_id TEXT NOT NULL, author_id TEXT NOT NULL, timestamp INTEGER NOT NULL, op_type INTEGER NOT NULL, path TEXT NOT NULL, value BLOB ); CREATE INDEX idx_doc_id ON records(doc_id);这个表设计得非常直白：所有 CRDT 日志都塞在一张表里，同一个文档的日志通过doc_id索引快速查询。合并日志时，只需要执行"插入新记录 + 更新本地状态"两个步骤。因为log_id有主键约束，重复投递同一日志会被自动忽略，这天然保证了幂等性。
理解这张表的设计，对你排查问题也特别有帮助。比如你想看某个文档的历史记录，直接 SQL 查询：
SELECT * FROM records WHERE doc_id = 'inspection_001' ORDER BY timestamp;动手跑一次，比看十篇理论知识都管用。
6. 鸿蒙化适配的经验沉淀与最终建议
我自己的体会是，鸿蒙化适配的核心工作量和难点并不在 CRDT 本身，而在平台差异处理。CRDT 理论再复杂，sql_crdt已经封装得很好了，你花半天时间看看文档就能上手。但鸿蒙那一侧的插件替换、路径处理、注册配置，才是真正消耗时间的地方。
我把这套流程跑通之后，最大的感受是：千万别低估初始化验证的重要性。先跑通一个最基础的数据库读写，再往上叠 CRDT 逻辑，排查问题会轻松很多。另一个特别想强调的是ID 生成策略，CRDT 应用里所有实体的 ID 必须全局唯一，这个设计做不好，后面同步一定出幺蛾子。
最后再分享一个小技巧：在鸿蒙端调试时，数据库路径和日志文件路径经常变化，我建议在应用启动时打印所有关键路径到控制台，同时把一份调试日志写到应用沙箱里。这样哪怕应用崩溃了，重启后你还能拿到之前的日志来复盘。这个习惯在我适配整个鸿蒙分支的过程中，帮我省了至少一半的排查时间。
