前言

鸿蒙最酷的能力之一，是"分布式"：你的手机、平板、手表像一台设备。备忘录在手机写了，平板上立刻能看到——数据跨设备同步。

这篇文章我不讲怎么调 API（那要写不少），而是把分布式数据同步的原理讲清楚：它是怎么知道"哪些设备可信"“数据怎么传过去”"冲突怎么解"的。懂原理，你用起 API 才不会懵。

先理解"分布式软总线"

跨设备通信的底层是软总线（Soft Bus）。你可以把它理解为"把所有 nearby 设备连成一张虚拟局域网"。

• 设备发现：通过蓝牙/WiFi 发现同账号下的 nearby 设备。
• 设备认证：只有登录同一华为账号、且互信的设备才能通信（安全前提）。
• 数据传输：基于软总线的点对点通道，比你自建 socket 省心。

所以分布式的前提永远两条：同一华为账号 + 设备间已授权互信。不满足，代码写得再对也连不上。

分布式数据库（distributedKVStore）

跨设备同步数据，官方推荐用 distributedKVStore（分布式键值库）。原理：

代码实现

import { distributedKVStore } from '@kit.ArkData'

const kvManager = distributedKVStore.createKVManager({
  context: getContext(),
  bundleName: 'com.example.myapp'
})
const kvStore = kvManager.getKVStore({
  storeId: 'mySyncStore',
  syncDeviceList: [distributedKVStore.DeviceLevel.DEVICELEVEL_CLOUD] // 或 LOCAL
}, (err, store) => {
  // 拿到 store
})

• KVStore 是键值库，和本地 Preferences 类似，但多了"同步"能力。
• 写入后，系统自动把变更推给已信任的其它设备。

数据怎么"自动"同步过去

写入分布式 KV 后，框架做了这些事（你不用管）：

1. 拦截这次写入，记录变更。
2. 通过软总线找到可信设备列表。

3. 把变更增量推送到各设备。
4. 对方设备应用变更，本地 KV 更新。
5. 触发本地监听回调，UI 刷新。

核心代码

// 写入，自动同步到其它设备
kvStore.put('note_1', '今天买了咖啡').then(() => {
  console.info('已写入，将同步到其它设备')
})

// 监听其它设备的变更，刷新 UI
kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
  this.refreshUI()
})

冲突怎么解

两台设备同时改了同一个 key，谁赢？分布式 KV 默认策略是时间戳后者覆盖前者（last write wins）。如果你的业务需要更细的合并（比如"合并两条备忘录"），得自己在应用层处理。

常见误区（小白必踩）

误区	说明
不同账号/不互信连不上	分布式前提永远是"同一华为账号 + 设备互信"，不满足代码再对也连不上。
冲突策略不清楚	多设备同时改同 key，默认"后者覆盖"，要合并得自己写应用层逻辑。
不监听 dataChange	写入后不监听变更，UI 不会自动刷新，还以为没同步成功。

下面这段代码可以直接复制到 DevEco Studio 里运行。建议你边读边敲，改一改文末「动手改一改」里的参数，亲眼看看效果。

完整可运行示例：分布式数据同步

把数据放到分布式存储，跨设备可读写。

完整示例

// 分布式 KV 存储：多设备共享同一份数据
import { distributedKVStore } from '@kit.ArkData'

async function syncDemo() {
  const kvManager = distributedKVStore.createKVManager({
    context: getContext(),
    bundleName: 'com.example.app'
  })
  const kv = await kvManager.getKVStore('store', {
    securityLevel: distributedKVStore.SecurityLevel.S1,
    kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION
  })
  await kv.put('todo', '买牛奶')         // 本机写入
  const v = await kv.get('todo')         // 其他可信设备也能读到
  console.info('跨设备读到: ' + v)
}

你会看到什么：在手机 A 写入 todo，登录同一账号的可信设备 B 能读到同样的值——这就是分布式数据管理的「数据跟着账号走」。

动手改一改：

• 用 kv.on('dataChange') 监听远端变更，做实时同步 UI。
• 把 SecurityLevel 调高，体验更高安全等级。
• 用 delete 删除后，观察其他设备同步失效。

写在最后

分布式同步的本质：同一账号 + 互信设备 + 软总线传输 + KV 自动增量同步。框架把发现、认证、传输、冲突兜底都包了，你只要 put 和监听 dataChange。

理解了这个流程，你再看官方 API 就不会怕。下一步想实战，就从 distributedKVStore 的 put + dataChange 两个方法入手，跑一个"手机写、平板看"的最小 demo。