我是兰瓶Coding，一枚刚踏入鸿蒙领域的转型小白，原是移动开发中级，如下是我学习笔记《零基础学鸿蒙》，若对你所有帮助，还请不吝啬的给个大大的赞~

前言

先说心里话——第一次在鸿蒙里把两台设备“拉一根网线般”连起来后，我真的愣了半分钟：把文件放到一个“分布式目录”，另一台设备就能像本地一样读到。这不就是把“局域网共享 + 同步盘 + 权限分级 + 冲突处理”给打包进了系统？是的，OpenHarmony/HarmonyOS 的 hmdfs（HarmonyOS Distributed File System）干的就是这件事：在分布式软总线上构建一个全局一致的访问视图，让开发者用同一套 @kit.CoreFileKit 的 fs 接口干跨设备的活儿，少思考设备，多思考数据。(华为开发者官网)

本文按你给的提纲来：文件虚拟化 → 多端访问一致性 → 性能优化。技术点我会围绕 Distributed File / DFS API 展开，所有代码都用 ArkTS；文末再给一套从“发现设备 → 连接 DFS → 跨设备拷贝 → 断开”的最小实战闭环。走起～😎

一、文件虚拟化：把“很多设备”伪装成“一个文件系统”

1）架构一眼懂：软总线 + distributedfile_daemon + hmdfs

DFS 的底层是分布式软总线，distributedfile_daemon 负责设备上线监听和链路建立，结合数据/设备安全分级选择不同的流转策略；hmdfs 在内核侧实现网络文件系统，承担缓存、文件访问、元数据与冲突管理。对上层应用来说，文件接口长得跟本地一模一样（@ohos.file.fs），只是系统帮你把“本地 or 远端”的路径路由掉了。(华为开发者官网)

要点：

• 全局一致视图：把远端设备的分布式目录“合成”到本地视图里。
• 不主动拷贝：DFS 提供互访，不自动把远端数据落地；需要本地副本时请自己拷。
• symlink 不支持：避免跨设备符号链接带来的复杂一致性问题。(华为开发者官网)

2）“分布式路径”到底在哪儿？

对同一应用来说，跨设备访问的约定路径是：/data/storage/el2/distributedfiles/（每个设备都有自己的这份“分布式目录”）。只要两端设备组网、同账号登录、应用都安装，把文件放进分布式目录，另一台设备就能读。开发者完全可以用 fs 的常规 APIs 来读写。(华为开发者官网)

3）API 入口认准谁？

核心就是 @kit.CoreFileKit 的 fs 模块。从 API 12 开始，fs 加了几位“专管 DFS 的新同学”：

• fs.connectDfs(networkId) / fs.disconnectDfs(networkId)：挂载/卸载某个远端公共目录或会话；
• fs.createReadStream() / fs.createWriteStream()：跨设备也可用的流式 I/O；
• fs.DfsListeners.onStatus(...)：监听 DFS 状态（API 文档标注为 12+）。
  其它常用的 open/read/write/copy/move 也都能在分布式路径上用。(华为开发者官网)

小贴士：官方文档会标“12+”之类的版本角标，注意你工程选择的 API Level；如果你用的是 12 以下版本，对应 DFS 能力会受限。(华为开发者官网)

二、多端访问一致性：别追“强一致”，DFS 的真实承诺是 Close-to-Open

DFS 强调的是 Close-to-Open 一致性：一端把文件写完并关闭后，另一端再打开读，能看到最新内容。这不是行级实时一致（比如写的同时另一端就读到变更）——DFS 在网络波动、缓存回刷上有自己的节奏，冲突也有系统级的命名策略处理。(华为开发者官网)

1）一致性模型的开发者直觉

• 写端：write → close 之后才算“可见最新”。
• 读端：下一次 open 时，系统确保能读到写端关闭时的最新版本。
• 网络抖动：回刷延迟可能导致“看得见但拿不到”的瞬时错觉，接口超时（4s 量级） 需要兜底。(华为开发者官网)

2）冲突处理的系统策略

当多个设备对同名文件“同时下手”，系统会按规则重命名冲突文件，例如追加 *_conflict_dev{id}；目录与文件同名时，远端目录可能被追加 _remote_directory。这不是拍脑袋，官方有显式规则，你可以在 UI 上做友好的提示与合并向导。(华为开发者官网)

3）安全分级：数据能不能跨到“弱设备”，看你标签怎么打

DFS 下，数据有等级，设备也有等级。比如健康/银行卡等敏感数据可以设置更高等级，低安全等级的设备（如部分 IoT）不可读。相关接口在“设置分布式文件数据等级”专题里，实务上就是给目标文件打上合适的安全标签。(华为开发者官网)

---

三、性能优化：带宽借我用用，但 CPU/IO 我自己省

目标：尽量让“跨设备”看起来像“本地”。思路无非三件事：
A）避免不必要的跨网 I/O；B）把 I/O 做成流式/并行/断点续传；C）弱网络时优雅衰退。

1）避免跨网：能移动到分布式目录就别复制两次

在多设备协同里，“把文件移动到 /data/storage/el2/distributedfiles/”常比“先传到对端，再导入沙箱”高效——因为 DFS 会把这块目录虚拟成“跨设备共享视图”，对端直接可见可读。复制只有在确实需要本地离线副本时再做。(华为开发者官网)

2）流式读写 + 分块续传

• 用 fs.createReadStream() / fs.createWriteStream() 做大文件顺序传输，别一次性读进内存；
• 大块/小块的切换可结合网络质量自适应（例如 2MB/512KB 动态）；
• 失败重试要带偏移量，结合 RandomAccessFile 可实现断点续传。以上 API 在 12+ 有完整支持。(华为开发者官网)

3）异步 + 多线程（TaskPool/Worker）

ArkTS 下的 TaskPool/Worker 能把 I/O 调度和哈希校验甩出 UI 线程，多文件并行时可按“每核 1～2 任务”的经验值并发，弱网络环境下适当降并发避免排队拥塞。（并发策略属于工程实践，系统不强制。）

4）fsync/fdatasync 的取舍

• fs.fdatasync 只刷数据不强制刷元数据，速度更快；
• 只有在你确实需要持久化元数据（比如对端马上要读且你关心时间戳/权限）时再用 fs.fsync。(华为开发者官网)

---

四、从 0 到 1：最小可运行闭环（ArkTS）

场景：列出组网内设备 → 选择设备并连接 DFS → 往分布式目录写文件 → 在对端看到变化 → 断开 DFS。
依赖：@kit.DistributedServiceKit（设备管理）、@kit.CoreFileKit（文件）、@kit.BasicServicesKit（错误类型与权限管理）。

0）权限与配置（别跳过！）

// module.json5（节选）
{
  "requestPermissions": [
    { "name": "ohos.permission.DISTRIBUTED_DATASYNC" }
  ]
}

该权限通常为 user_grant，需要在运行时弹窗请求。(华为开发者官网)

运行时请求（示例）：

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

async function ensureDistributedPermission(ctx: common.UIAbilityContext) {
  const at = abilityAccessCtrl.createAtManager();
  return at.requestPermissionsFromUser(
    ctx,
    ['ohos.permission.DISTRIBUTED_DATASYNC']
  ).catch((e: BusinessError) => {
    console.error(`permission denied: ${e.code} ${e.message}`);
    throw e;
  });
}

1）发现设备并拿到 networkId

import { distributedDeviceManager as dm } from '@kit.DistributedServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function listOnlineDevices(bundleName: string) {
  const manager = dm.createDeviceManager(bundleName);
  // 真实项目可监听设备上线/下线事件做热更新
  const devices = manager.getTrustedDeviceListSync();
  // 过滤出在线的设备，并拿到 networkId
  return devices
    .filter(d => d.isOnline)
    .map(d => ({ name: d.deviceName, id: d.networkId }));
}

设备管理 API 在“分布式管理服务”文档下；拿到 networkId 后，后面 DFS 的 connectDfs/disconnectDfs 都用它。(华为开发者官网)

2）连接 DFS（API 12+）

import { fileIo as fs } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function connectRemoteDfs(networkId: string) {
  try {
    await fs.connectDfs(networkId); // 12+
    console.info(`DFS connected: ${networkId}`);
  } catch (e) {
    const err = e as BusinessError;
    console.error(`connectDfs failed: ${err.code}, ${err.message}`);
    throw err;
  }
}

connectDfs/disconnectDfs 等 DFS API 在 @ohos.file.fs 文档中明确标注 12+。(华为开发者官网)

3）跨设备写读：只要路径在 /data/storage/el2/distributedfiles/

import { fileIo as fs, fileUri } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

async function writeToDistributedDir(ctx: common.UIAbilityContext, name: string, content: string) {
  // 获取当前应用沙箱下的分布式目录
  const base = ctx.filesDir + '/distributedfiles';
  const path = `${base}/${name}`;

  const fd = await fs.open(path, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);
  try {
    await fs.write(fd, new TextEncoder().encode(content));
    await fs.fdatasync(fd); // 数据落盘即可，元数据不强刷
  } finally {
    await fs.close(fd);
  }
  return fileUri.getUriFromPath(path);
}

跨设备访问&拷贝的官方指南也强调：把文件放进分布式目录，另一端就能通过同一目录看到它；需要跨应用拷贝时，也围绕该目录完成。(华为开发者官网)

4）大文件跨设备拷贝：流式 + 断点续传雏形

import { fileIo as fs } from '@kit.CoreFileKit';

async function copyLargeFileAcrossDevices(srcPath: string, dstPath: string) {
  const rs = await fs.createReadStream(srcPath);   // 12+
  const ws = await fs.createWriteStream(dstPath);  // 12+

  return new Promise<void>((resolve, reject) => {
    rs.on('data', (chunk) => ws.write(chunk));
    rs.on('end',  () => { ws.close(); resolve(); });
    rs.on('error', reject);
  });
}

生产中你会加：分块编号 + 校验 + 失败重试 + 续传偏移。但起点一定是流式，不然大文件内存占用会把你劝退。(华为开发者官网)

5）断开 DFS（别忘了收尾）

async function disconnectRemoteDfs(networkId: string) {
  await fs.disconnectDfs(networkId); // 12+
}

官方“跨设备访问”章节里也给了 disconnectDfs 的使用示例。(华为开发者官网)

---

五、工程化细节：把“研究报告”落成“线上方案”

1）一致性与用户体验

• Close-to-Open 心智要在 UI 上体现：比如“保存成功后对端可见”，而不是“实时同步每个字节”；
• 冲突 UI尽量人性化——系统会重命名冲突文件，但你最好提示“来自 xx 设备的版本”，给用户合并选项。(华为开发者官网)

2）安全标签与设备等级

• 对敏感文件调用安全标签接口（如设置为高等级），避免弱设备读取；
• 如果对端读取失败，不要只报错，提示“目标设备权限不足或未授权”。(华为开发者官网)

3）性能与资源占用

• 首选移动而非复制：移动到分布式目录即可共享；
• 批量并行：10 个文件以内并发 2～4 条流足够，多了反而拥塞；
• fsync 策略：多数情况下 fdatasync 就行，批量结束再做一次 fsync；
• 弱网兜底：读写超时、BusinessError 码清晰可见，建议统一封装成 DfsRetryPolicy。

4）可观测性

• 打点：connectDfs/firstByte/lastByte/error，测 TTFRO（首次可读时间）、吞吐、失败率；
• 记录 networkId/设备型号/信号质量，帮助你判断是链路问题还是目标设备忙。

---

六、常见陷阱（都是真坑）

1. 把分布式当实时协作：DFS 是 Close-to-Open，不是 CRDT/OT；实时多端编辑请用分布式数据库或对象同步。(华为开发者官网)
2. 没申请 DISTRIBUTED_DATASYNC：设备列表拿不到、访问也异常，别忘了运行时授权。(华为开发者官网)
3. 用 symlink 做花活：不支持；请老老实实用真实路径。(华为开发者官网)
4. 一次性读大文件：内存顶爆；请用 createReadStream/createWriteStream。(华为开发者官网)
5. 忽视冲突策略：重名后文件被系统改名，你不提示用户就会出现“找不到”的错觉。(华为开发者官网)

---

七、FAQ：关于 DistributedFile / DFS API 的几句直白

• 问：分布式文件是不是有单独的“DistributedFile 类”？
  答：没有必要额外学一套。在 ArkTS 下，就用 @ohos.file.fs 那套 open/read/write/copy/stream；跨设备访问由 DFS 路由。API 12+ 里的 connectDfs/disconnectDfs 与 Read/WriteStream 是你要重点关注的新成员。(华为开发者官网)

• 问：权限怎么最小化？
  分布式访问主要是 ohos.permission.DISTRIBUTED_DATASYNC；另外获取设备信息/组网等会用到分布式设备管理模块的接口，按需申请即可。(华为开发者官网)

• 问：能不能把远端目录整体“挂到”本地再用？
  这就是 connectDfs 存在的意义之一：先连，再正常用 fs 访问。结束时记得 disconnectDfs。(华为开发者官网)

---

八、小结 & 心法

文件虚拟化让我们用“本地思维”写“跨设备功能”；多端一致性以 Close-to-Open 为边界，配合系统冲突处理和安全分级，既实用又可控；性能优化说到底是 I/O 工程学：移动优先、流式优先、并发有度、失败可续。
  如果你下一次还在犹豫“要不要自建文件同步服务”，不妨先反问自己一句：**“既然系统已经把设备边界虚化了，我干嘛不趁机少造轮子呢？”**😉

参考与延伸阅读

• 分布式文件系统概述（hmdfs 架构、Close-to-Open、一致性与冲突处理）：华为开发者文档。(华为开发者官网)
• @ohos.file.fs（API 12+：connectDfs/disconnectDfs、流式 I/O、fdatasync 等）：华为开发者 API 参考。(华为开发者官网)
• 跨设备文件访问 / 跨设备文件拷贝：官方场景指南与代码片段。(华为开发者官网)
• 设置分布式文件数据等级（安全标签）：官方指南。(华为开发者官网)
• 分布式管理服务（设备发现、networkId 获取）：API 索引。(华为开发者官网)

---

…

(未完待续)