Electron 跑在鸿蒙 PC 上做笔记附件,文件必须复制进沙箱才算数:一次写入、改名换原子、指纹去重三件事,让 10MB 以内的附件在反复导入时不落第二份

沙箱目录怎么选、写一半被杀进程怎么办、同一份文件反复拖进来为什么只落一次盘——这篇文章用一个跑在鸿蒙 PC 上的 Electron 笔记应用,把附件落盘的这三个问题一次讲透。

欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

0. 环境与实测设备

项版本/型号
设备HarmonyOS PC(aarch64,2in1 形态)
系统 API26
Electron-OHv40.0.1(libelectron.so 预编译,178MB)
壳工程ohos_hap(electron / web_engine / account_quick_login 三模块)
应用形态HAP 内加载 Chromium + Node,前端跑在 resfile/resources/app/
本次改动新增 importer.js,改造 main.js、preload.js、src/index.html、src/renderer.js、src/style.css
数据落点笔记 userData/notes.json,附件 userData/imported/,均在应用沙箱内
包版本versionCode 1000004 / versionName 1.0.4

先把范围钉住:这一轮没有碰 ArkTS,也没有碰窗口和 DPI——那是前一个系列的事。这一轮的全部精力在"文件进来之后怎么办":从用户选中的路径、从拖进来的 File 对象,怎么变成应用自己的、可长期持有的数据。

1. “导入不就是复制个文件吗”——这个问题是怎么找上我的

我一开始也以为它只是"把用户选的文件复制到应用目录里,记下路径,完事"。fs.copyFileSync(src, dst) 一行,这个流程简单到不需要设计。

结果在真机上对着三个现象挨个翻车:

  • 第一件事:源路径靠不住。 选择器返回的是一个 file:// URI,今天能读,重启应用再读就报权限错误。外部存储的读权限是"当次会话"的,不是永久的。把 URI 原样存进笔记,等于存了一个随时失效的引用。
  • 第二件事:写一半的文件比没有更危险。 应用是 HAP 里拉起的 Chromium 子进程,被系统回收是常态。writeFileSync 写到一半被杀,目录里留下一个半截文件——下次 readIndex() 解析元数据,文件本体只有前 4KB。如果元数据和文件是分开写的,这种错位永远存在。
  • 第三件事:用户会重复导入同一份文件。 拖一次、再拖一次,目录里就有 a__会议纪要.md 和 b__会议纪要.md 两个内容一模一样的文件。附件面板越来越长,全是重复。

三个现象指向同一个结论:“导入"不是复制,是"把外部文件收编成应用自有的、可长期持有的资产”。收编有三个动作:落进自己的沙箱、落得原子、落得唯一。

所以这个题目的边界很清楚:所有导入一律复制进 userData/imported/,写入走临时文件加改名,重复内容靠 SHA-256 指纹挡在盘外。源路径、源 URI 只在导入那一刻用一次,用完即弃。

拆下来是三件事:

  • 设计一个附件目录的布局和元数据协议,让"文件本体"和"索引"永远不错位;
  • 把写入改成原子的,坏文件宁可留档也不要混进正式数据;
  • 在落盘前算指纹,重复内容直接短路返回。

下面是干完之后的完整记录,包括我踩的每一个坑。

2. 按老规矩,先给效果再讲原理

请添加图片描述

图1 附件面板:沙箱目录路径直接展示,用户能看出"文件已经被复制进了应用自己的地盘"

面板顶部那一行 files-dir 不是装饰,它是这次设计的核心承诺——列表里每一项都已经躺在 userData/imported/ 里,删除源文件、重启应用、断开外部设备,都不影响这份副本。这个承诺的代价是存储翻倍,但换来的确定性问题后面会反复变现。

请添加图片描述

图2 重复导入:第二次拖入同一份文件,toast 显示"跳过重复 1 个",列表长度不变

图2 是指纹去重的用户可见面。第一次拖入,toast 是"转为笔记 1 条";第二次拖入同一个文件,toast 变成"跳过重复 1 个"。列表、笔记、磁盘,三处都不会多出东西。

请添加图片描述

图3 笔记与附件的关联:编辑器底部的 chip 来自笔记数据里的 attachments 字段

图3 里的 chip 是笔记和附件之间的桥,它的数据结构在下一篇细讲。这一篇只需要知道:附件记录一旦生成,id 就是它唯一的身份,笔记只存 id,不存路径——路径会变(迁移、重装),id 不会。

这里每一处都不是装饰:

  • 大小标注精确到 B/KB/MB:附件上限是 10MB,用户拖一个 12MB 的文件被拒时,看到具体数字才知道差多少;
  • 文本附件标注"文本":这决定它能不能转成笔记正文、能不能按 utf-8 预览;
  • 删除按钮二次确认:沙箱里的副本删了就是删了,没有回收站。

3. 原理:沙箱是资产的边界,rename 是原子的边界

先说沙箱。鸿蒙给每个 HAP 一个私有的 userData 目录,这个目录的读写权限跟着应用走,不依赖任何运行时授权。应用进程里 app.getPath('userData') 拿到的就是它——Electron-OH 的壳工程把这条路径正确地接给了 Node 的 fs。

所以沙箱内的操作是"无条件可行"的:建目录、写文件、改名、删除,都不需要问系统要权限。沙箱外的操作是"看情况"的:选择器返回的 URI 在当次会话内可读,跨会话、跨应用就不保证。这就是"导入=复制"的根本原因——不是我想复制,是外部的读权限没有"永久"这个选项。

再说原子写。文件系统层面,“写文件"不是原子的:writeFileSync 内部是打开、写、关闭三步,任何一步之间进程被杀,盘上就是一个半截文件。但 rename 是原子的——同一个文件系统内,rename 要么发生,要么不发生,没有"改了一半的目录项”。

非原子:  writeFileSync(file, data)   →  半截文件直接叫 file,读侧会读到
原  子:  writeFileSync(file.tmp, data)
          renameSync(file.tmp, file)   →  读侧要么看到完整的旧 file,要么看到完整的新 file

这套策略在 notes.json 上已经验证过一轮,这次原样搬给 imported/index.json 和每个附件本体。唯一的差别是附件本体的临时文件和正式文件在同一个目录里,rename 永远不跨设备——跨设备的 rename 等价于复制加删除,原子性就没了。

最后是指纹。SHA-256 对 10MB 以内的文件算一次哈希,毫秒级,换来的是 O(n) 的重复检测:index.json 里已经有同指纹的记录,就直接返回那条记录,盘上一个字节都不多写。指纹不是加密,是身份——我不需要从哈希还原文件,只需要判断"这份内容我见过没有"。

截断是个需要想清楚的点:SHA-256 全长 64 个十六进制字符,我只存前 32 位(128 bit)。32 位以上截断,随机碰撞概率大约是 2^-128——附件场景一辈子碰不上一次。省下的 32 个字符让 index.json 矮了一截,值得。

4. 工程怎么搭

web_engine/src/main/resources/resfile/resources/app/
├── main.js              主进程:files:* 五条 IPC、登录守卫、选择器探测
├── importer.js          本次新增:沙箱落盘、指纹去重、读取与删除,无任何 IPC 依赖
├── preload.js           contextBridge 白名单:filesApi(pick/dropImport/list/read/remove)
├── store.js             上一轮的原子写 JSON 存储,本篇策略的原型
├── auth-store.js        账号存储(os 直接 jsonStore 的选型在这里)
├── src/
│   ├── index.html       附件面板 #files-panel、拖拽遮罩 #drop-overlay
│   ├── style.css        附件列表、chip、预览样式
│   └── renderer.js      拖拽事件链、FileReader 分块、附件列表渲染
└── package.json

请添加图片描述

importer.js 的位置是刻意的:它是一个纯 Node 模块,不 import electron,不碰 ipcMain,构造函数只吃一个目录路径。这意味着它可以在本机用 node importer.test.js 直接跑单测——7 个用例,不需要 HAP、不需要真机。能被 node 单测跑出来的问题,不要留给真机。

元数据协议就是 index.json 的形状:

{
  "files": [
    {
      "id": "m3xk9a2f1b8c4d7e",
      "name": "会议纪要.md",
      "stored": "m3xk9a2f1b8c4d7e__会议纪要.md",
      "size": 24317,
      "ext": ".md",
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "isText": true,
      "isImage": false,
      "importedAt": 1795145384223
    }
  ]
}

几条协议约定值得单独说:

  • id 是唯一身份:时间戳的 36 进制加 4 字节随机数。笔记里的 attachments[] 只存这个 id;
  • stored 是盘上文件名:id__原名,既保证唯一,又让人类能在文件管理器里认出它;
  • hash 是内容身份:去重的依据,32 位十六进制;
  • isText / isImage 是能力标记:决定这个附件能被怎么消费——转正文、按图渲染、还是只能当二进制。

主进程的 IPC 面是五条窄通道:

通道方向参数返回
files:pick渲染层 → 主进程无{ok, canceled, imported[], failed[]}
files:drop-import渲染层 → 主进程{name, base64} 单对象{ok, imported} 或 {ok:false, error}
files:list渲染层 → 主进程无{ok, dir, files[]}
files:read渲染层 → 主进程{id}{ok, file}
files:remove渲染层 → 主进程{id}{ok, removed}

全部单对象参数。这不是洁癖:壳工程的 ipcRenderer.invoke 对多参数的透传不可靠,单对象是把"参数会不会丢"这个问题从链路上删掉。每一条都有登录守卫,未登录直接 {ok:false, error:'未登录'},不抛异常。

5. 把代码讲透

5.1 目录布局:文件名里藏着防穿越

接收外部文件名的第一件事是假设它是恶意的。拖拽进来的 name 来自 File.name,选择器进来的来自 path.basename——但"来自"不等于"干净"。

// importer.js - sanitizeName()
function sanitizeName(name) {
  const base = String(name || '').split(/[\\/]/).pop().trim();
  const cleaned = base.replace(/[\x00-\x1f]/g, '').slice(0, 120);
  return cleaned || '未命名';
}

请添加图片描述

三个细节值得单独说:

第一,先按斜杠切开取最后一段。 ../../etc/passwd 进来,split(/[\\/]/).pop() 之后只剩 passwd。../ 穿越在拼路径之前就被拆掉了,而不是在拼完之后校验——校验总有漏网的分支,拆解没有。

第二,剥掉控制字符再截断。 \x00 能让某些文件系统调用提前截断字符串,\x1f 以内的控制字符都不该出现在文件名里。120 字符的上限是给 stored 文件名留余量:id 16 位加分隔符,总长不会顶到文件系统的 255 字节红线。

第三,兜底叫"未命名"而不是抛错。 名字清洗失败不该挡住导入——文件内容还在,名字可以事后在笔记里改。

5.2 原子写:tmp 加 rename,坏文件留档不混入

附件本体和 index.json 都走同一套写入纪律:

// importer.js - importBytes()(节选)
const tmp = path.join(dir, stored + '.tmp');
fs.writeFileSync(tmp, buffer);
fs.renameSync(tmp, path.join(dir, stored));   // rename 原子性:读侧永远不会看到半截文件

index.json 同款:

// importer.js - writeIndex()
const tmp = indexFile + '.tmp';
fs.writeFileSync(tmp, JSON.stringify({ files }, null, 2), 'utf-8');
fs.renameSync(tmp, indexFile);

而读侧对损坏的兜底不是恢复,是承认损失并留档:

// importer.js - readIndex()
try {
  const data = JSON.parse(fs.readFileSync(indexFile, 'utf-8'));
  return Array.isArray(data.files) ? data.files : [];
} catch (_) {
  return [];
}

三个细节值得单独说:

第一,tmp 文件带 .tmp 后缀留在同一个目录。 不是系统的临时目录——跨目录的 rename 不保原子性。.tmp 残留无害,下一次同名导入会覆盖它。

第二,readIndex 解析失败返回空数组,不抛。 索引坏了不应该让附件面板整个打不开——用户还能看到目录路径,手动抢救文件。这是"半截文件比没有更危险"的反面:半截索引比崩溃好。

第三,rename 的窗口不是零。 写 tmp 和 rename 之间进程被杀,盘上多一个 .tmp 孤儿。它不进索引、不占逻辑空间,属于可接受损耗。追求零窗口要上日志型文件系统自己实现,10MB 附件场景不值得。

5.3 指纹去重:先算哈希,再摸盘

写入的前置动作是查重:

// importer.js - importBytes()(节选)
const ext = (/\.[a-z0-9]+$/i.exec(name) || [''])[0].toLowerCase();
const isImage = IMAGE_EXTS.has(ext.slice(1));
const hash = crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 32);

const existing = readIndex();
const dup = existing.find((f) => f.hash === hash);
if (dup) {
  // 不重复写盘:返回已有记录 + 标记,上层决定是提示还是忽略
  return Object.assign({}, dup, { duplicate: true });
}

请添加图片描述

三个细节值得单独说:

第一,指纹挂在内容上,不挂在名字上。 Buffer 先算哈希再落盘,名字只是展示用。所以"换个名字再拖一次"和"原样再拖一次"结果一样——这是特性不是缺陷,用户重复导入的动机就是"我不确定刚才那次成没成功",按名字去重会误伤,按内容去重刚刚好。

第二,重复返回的是已有记录加 duplicate 标记。 不是返回 null 也不是抛错。调用方拿到完整记录可以做两件事:告诉用户"跳过了",以及如果笔记还需要这条附件,引用照样能建。

第三,去重挡的是盘,不挡笔记。 同一份文件在两条笔记里被引用是合法的——附件是资产,笔记是资产的使用记录,资产只存一份,记录随便记。这个分层让"删除附件"变成了纯资产操作,不需要去猜几条笔记在用。

5.4 容量预算:三个数字各管一段

importer 里写死了三个上限,各管一段链路:

常量值管什么
MAX_FILE_BYTES10MB单文件落盘上限,超了直接拒绝
IMAGE_PREVIEW_BYTES2MB图片转 base64 走 IPC 的上限
PREVIEW_BYTES64KB文本预览/转笔记正文的截断点

这三个数字不是拍脑袋:

  • 10MB 是拖拽链路的实际约束——渲染层 FileReader 读 ArrayBuffer,分块转 base64 走 IPC,超过 10MB 的文件转出来的 base64 有 13MB+,一次 IPC 调用的序列化开销开始伤手感。上限卡在这里,超限文件引导用户走别的方式;
  • 2MB 是图片预览的折中——2MB 图片转 base64 约 2.7MB,IPC 一来一回能接受;再大就只报 tooLarge,面板里给一句说明,不硬传;
  • 64KB 是笔记正文的舒适上限——正文进 notes.json,每次保存都是全量重写,单条笔记的正文超过 64KB,保存延迟肉眼可见。截断处在笔记里注明"完整内容见附件面板",资产没有丢,只是引用了。

5.5 存储选型:为什么附件元数据用 JSON 不用 SQLite

index.json 只有几 KB 到几百 KB,JSON 加全量重写是最省事的方案。真正要想清楚的是反过来那半句:为什么笔记和账号也不用 SQLite。

上一轮在真机上试过 SQLite。建表、插入都顺利——直到真正 INSERT 数据的那一刻才爆锁错误(具体报错原文待补,现象是:建表不报、预编译不报、INSERT 必报)。hmdfs 对 SQLite 文件的锁支持和 Linux 原生文件系统不一样,better-sqlite3 这类同步接口在鸿蒙沙箱里属于"能编译、不能信"。

而 JSON 加原子 rename 的方案,全部依赖只是 fs.writeFileSync 和 fs.renameSync——两个在沙箱里验证过无数次的调用。存储选型不选最先进的,选每一步都在真机上验证过的。

这里有一个很容易被忽略的窗口期:readIndex() 在内存里缓存过一次的结果和盘上的最新状态之间,没有同步机制。单窗口单用户场景下,主进程是唯一的写者,内存即真相;如果以后做多实例(multiAppMode 现在钉死了 maxCount: 1),这一层就要重新设计。现在的答案写在配置里:单实例,所以单写者。

6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。

坑一:SQLite 在 hmdfs 上"建表成功、INSERT 必炸"。 最初笔记存储选了 better-sqlite3,CREATE TABLE 正常返回,预编译语句也正常,信心满满。真机上注册第一个用户,INSERT 的一瞬间爆锁(报错原文待补,现象稳定复现:建表不报、查询不报、写必报)。排查了一晚上连接串、WAL、busy_timeout,全没用。后来才反应过来:hmdfs 是分布式文件系统,它对 SQLite 依赖的 POSIX 锁语义支持不完整。在鸿蒙沙箱里,SQLite 的锁不是慢,是假。 整个存储层换 JSON 加原子 rename,问题消失。

坑二:错误处理只包住了构造,没包住使用。 new Database(file) 包在 try/catch 里,构造失败会回落到备用方案——看起来很稳。但锁的爆点在 INSERT,不在构造,catch 根本够不着。错误在"使用"的第一刻才出现,而那时 catch 已经退出了。try/catch 的范围必须覆盖"错误实际发生的位置",不是"错误看起来该发生的位置"。

坑三:../ 穿越差点写穿沙箱。 附件文件名直接用 path.join(dir, name) 拼接,测试时拖了一个名为 ../../notes.json 的文件进去——没有报错,notes.json 被附件内容覆盖了,笔记全没了。这就是 sanitizeName 里"先切斜杠再清洗"的由来。外部输入拼路径之前先拆解,拼完再校验是赌运气。

坑四:同名不同内容的文件被误判为重复。 第一版去重键用的是 name + size,结果两个不同内容的同名同大小文件被吞了。改成 SHA-256 内容指纹之后,这个坑从根上消失。去重的键必须是内容本身,任何代理键(名字、大小、时间)都是猜。

坑五:index.json 写坏过一次,附件面板全空。 排查发现是某次导入时进程被回收,index.json 正好写了一半。修复前解析失败直接抛异常,面板白屏;修复后 readIndex 失败返回空数组加 .broken-时间戳 留档。坏文件的正确待遇是留档降级,不是崩溃现场。

坑六:base64 让 10MB 变 13.3MB,IPC 序列化肉眼可见地卡。 拖一个 10MB 文件,FileReader 转 base64 后体积膨胀三分之一,ipcRenderer.invoke 的序列化让窗口明显顿了一下。10MB 上限就是在这里定下来的——不是文件系统限制,是交互手感限制。上限要卡在体验崩坏的临界点上,而不是技术的极限上。

坑七:指纹只截 32 位,被质疑碰撞风险。 128 bit 指纹的随机碰撞概率约 2^-128,比"这台设备在这一秒被陨石击中"的概率低几个数量级。但为了保险,碰撞后的行为是安全的:重复导入返回已有记录,最坏情况是用户少了一个附件副本,不会丢数据。截断可以,行为必须往"无害"方向截。

坑八:importedAt 用了本地时间,两台设备对不上账。 Date.now() 是 UTC 毫秒,展示层用 getFullYear() 系列转本地——这个没问题。坑在于我一度想用"文件修改时间"当 importedAt,外部文件的 mtime 在复制后会保留源值,排序立刻乱了。资产的时间戳记录"入账时间",不继承源文件的"产生时间"。

7. 现在怎么用:从导入到资产

这一轮的导入入口有三个,全部汇到 importer.importBytes():

// renderer.js - 拖拽路线(渲染层读内容)
const base64 = await fileToBase64(file);
const r = await filesApi.dropImport(f.name, base64);

// main.js - 选择器路线(主进程读路径)
const r = importer.importMany(result.filePaths);

单测在本机跑:

node /tmp/importer.test.js
# PASS - 文本导入成功且带 hash
# PASS - 同内容重复导入 → duplicate 标记,不新增记录
# PASS - 图片导入 → isImage 识别
# PASS - 图片 readFile → 带 mime 的 base64
# PASS - 超过 10MB → 明确报错
# PASS - IMAGE_MIME 表覆盖常用格式
# PASS - 不同内容同名 → 正常新增

真机上用 versionCode 1000004 的包验证过完整链路:拖入、去重、重启后附件仍在、删除笔记附件保留。

硬限制清单,免得读者踩到同一堵墙:

  • 源路径只在导入那一刻用一次,不存 URI、不存外部路径,附件面板里的路径永远是沙箱的;
  • 单实例是前提,multiAppMode.maxCount: 1 钉死了单写者假设,放开多实例前 index.json 要加合并逻辑;
  • 10MB / 2MB / 64KB 三个上限是体验参数,改大之前先在真机上拖一个对应大小的文件感受一下 IPC;
  • SHA-256 指纹截 32 位,碰撞行为是"返回已有记录",不是丢数据;
  • SQLite 不要在 hmdfs 沙箱里碰,至少在 better-sqlite3 这类同步接口上不要。

8. 快问快答

Q1:hash 只存 32 位,不怕碰撞吗?
128 bit 的随机碰撞概率约 2^-128,附件场景可以视为零。更关键的是碰撞行为是无害的:指纹相同返回已有记录,最坏情况是用户少一个副本,不会丢数据。截断的前提是"截断后的行为往无害方向截",这两件事凑齐了才敢截。

Q2:附件本体和 index.json 谁先写?
先写本体,再更新 index.json。反过来会出"索引里有、文件没有"的幽灵记录;正顺序的坏结果是孤儿文件——本体在、索引没有,占点磁盘但不可见、不干扰。幽灵记录是逻辑错误,孤儿文件只是损耗,损耗永远比错误好。

Q3:用户删了笔记,附件要不要跟着删?
不跟着删。附件是资产层,笔记是使用记录,删笔记只是删记录。真正的清理是单独的"孤儿文件扫描":遍历 index.json,看哪些附件 id 没有被任何笔记的 attachments 引用,列出来让用户确认后删。自动连删的风险是误删共享附件——两条笔记引用同一个文件,删一条笔记就连带删文件,另一条立刻断链。

Q4:指纹去重会不会挡掉"我就是想要两份"的需求?
到目前为止没遇到这个需求。重复导入的用户动机几乎都是"我不确定刚才成没成功",去重恰好是对这个动机的正确回应。真有一天用户要两份,解法也不是去掉去重,是加一个"强制复制"入口——默认路径要贴大多数人的预期。

Q5:index.json 多大要担心性能?
readIndex 是全量读加 JSON.parse,writeIndex 是全量重写。按每条记录 300 字节算,一万条附件是 3MB,读写都在毫秒级。真正的阈值在于:全量重写意味着写放大,附件数量涨到十万级时每次导入要重写 30MB——到那个量级再换追加日志型存储,现在不预支这个复杂度。

Q6:stored 文件名为什么保留中文?
id__会议纪要.md 在文件管理器里人类可读,用户手动进沙箱抢救文件时认得出。代价是文件名编码问题——鸿蒙沙箱的 fs 对 UTF-8 文件名支持没有问题,实测过。如果哪天遇到不认中文的环境,改起来只动 sanitizeName 一处,因为盘上文件名的生成只有一个出口。

Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐