PicGo OpenHarmony PC 适配说明

YoLo♪

153人浏览 · 2026-10-15 18:10:21

YoLo♪ · 2026-10-15 18:10:21 发布

把 PicGo 桌面端（Electron + Vue 3）移植到 HarmonyOS PC（2in1 形态）的完整记录：适配过程（含构建时间线）、适配方案、真机调试流程、5 张真机运行截图、8 个真实问题（报错与异常行为）的定位与解法、以及上线前必须知道的限制。

真机环境（下文截图与日志全部来自该设备）

项目值
设备 HUAWEI MateBook Pro（型号 HAD-W32，软件版本串 HAD-W24 7.0.0.105(SP10C00E100R13P5)）
形态 2in1（PC）
CPU / API arm64-v8a / const.ohos.apiversion = 26
工具链 DevEco Studio 6.1.1，hdc 3.2.0d
运行时 libelectron（华为 Electron for HarmonyOS 发行版）
代码基线 commit 5fc17e8 feat: add HarmonyOS (OHOS) support for PicGo

项目	值
设备	HUAWEI MateBook Pro（型号 `HAD-W32`，软件版本串 `HAD-W24 7.0.0.105(SP10C00E100R13P5)`）
形态	`2in1`（PC）
CPU / API	`arm64-v8a` / `const.ohos.apiversion = 26`
工具链	DevEco Studio 6.1.1，hdc 3.2.0d
运行时	libelectron（华为 Electron for HarmonyOS 发行版）
代码基线	commit `5fc17e8` feat: add HarmonyOS (OHOS) support for PicGo

开源鸿蒙 PC 社区与代码仓

PicGo 鸿蒙 PC 适配欢迎加入开源鸿蒙 PC 社区，交流适配经验、问题与项目实践。

本项目代码托管在 AtomGit 的 OpenHarmony PC Developer 组织仓库：OpenHarmonyPCDeveloper/ohos_picgo。后续代码、适配说明和问题跟踪以该 PC 仓为准。

欢迎在 OpenHarmony PC Developer 项目申请页申请新建项目；按照社区流程，先提交 Issue，再联系阿太创建仓库。
问题和适配建议请提交到 ohos_picgo Issues。

当前迁移能力按 T0 使用：JS 构建、HAP 打包、安装启动和界面渲染已验证；T1 的真实图片上传及 T2 的发布、稳定性和生态兼容性尚未完成验证。

1. 背景：为什么不能直接复用 Electron 二进制

Electron 官方发行二进制没有 OHOS target，鸿蒙也不是 Linux 的一个发行版（musl + OHOS 内核 + ArkUI 图形栈）。华为给出的路线是 libelectron：

Chromium / Node / V8 按 OHOS 重新编译，产出 .so + 一套 resfile 资源（icudtl.dat、snapshot_blob.bin、resources.pak 等）；
提供一个 ArkTS 的 web_engine HAR，把 Chromium 的窗口、输入、剪贴板、文件、蓝牙等系统能力对接到 ArkUI；
应用侧只需要一个很薄的 HAP 壳（Ability + 页面），把 Electron 的 JS 产物塞进 resfile/resources/app。

于是 PicGo 的适配工作被拆成两半：

不改动业务逻辑：主进程/preload/渲染进程照旧用 electron-vite 打包，产出的 dist_electron 直接进 HAP；
只修平台差异：托盘、迷你窗口、启动模式、静态资源路径、原生 addon —— 这些在鸿蒙上缺失或行为不同。

2. 适配过程

先说清楚证据基础：这次适配在仓库里是一个 commit（5fc17e8），中间步骤没留在 git 历史里。所以本节的过程不是从提交记录读出来的，而是从三类可核对的物证复原：

物证	位置	能证明什么
hvigor 构建报告	`libelectron/ohos_hap/.hvigor/report/report-*.json`（10 份）	每次构建的发起时间
hvigor 构建日志	`.hvigor/outputs/build-logs/build.log.1`、`build.log`	每次构建的成败、耗时、ArkTS 告警原文
设备侧日志	`files/picgo-gui-local.log`、`hilog`、`hidumper`	每次真机运行的实际行为

2.1 起点：华为的 libelectron demo 工程

不是从零搭 HAP。起点是 libelectron 自带的 demo HAP 工程，配 docs/ 下的华为资料与示例（见 §7）。三条证据：

AppWindowAdapter.ets:33 的字段默认值至今是 private bundleName: string = 'com.huawei.ohos_electron';——华为 demo 的 bundleName。它在构造函数里被 bundleManager.getBundleInfoForSelfSync(...).name 覆盖（同文件 58-64），所以改了包名也不会串到 demo 应用上去。
electron 模块里保留着 demo 的演示页：pages/Index（XComponent 版）、pages/WindowNode、pages/WebPage、pages/Login、pages/SubWindow、pages/EmbeddedWindow、pages/StatusBarPage，以及华为账号登录用的 QuickLoginButtonComponent.ets（24.6 KB）；resources/base/profile/main_pages.json 把它们全部登记着。
web_engine/oh-package.json5 里仍挂着 demo 的 libadapter.so 本地依赖路径。

遗留项（未清尾）：AppScope/resources/base/element/string.json 的 app_name 至今是 "Electron"，而 app.json5 里 label: "$string:app_name"。真机 bm dump 查到的 labelResource 仍指向该字符串——桌面与任务栏上显示的应用名是 “Electron”，不是 PicGo。

与 demo 最关键的差别：demo 的 JS 侧只有一个 index.js + index.html（见 docs/electron-example/），而 PicGo 要跑的是 electron-vite 的 main/preload/renderer 三件套，外加 node_modules 与 public/ 静态资源。

2.2 第一步：把 JS 产物塞进 HAP

libelectron 的资源根就是 process.resourcesPath，在 HAP 内落于 .../resources/resfile/。scripts/build-ohos.js 按 electron-builder 的布局把三样东西搬进去（七步流程见 §3.2），真机上由此得到可用的入口路径：

file:///data/storage/el1/bundle/electron/resources/resfile/resources/app/dist_electron/renderer/index.html#/main/...

这一步踩了两个坑：

externalizeDepsPlugin() 会让 bundle 里保留 require()，所以必须在 resfile/resources/app/ 下再装一次生产依赖，否则运行时 MODULE_NOT_FOUND；
src/main/utils/env.ts 原本按 isDev 判断静态资源目录（cwd()/public vs resourcesPath/public），而 libelectron debug 构建下 app.isPackaged 恒为 false——不加例外就会指向根本不存在的 cwd()/public。修法是引入 isOhosRuntime：鸿蒙一律走 resourcesPath/public。

2.3 第二步：白屏，换掉渲染链路

Ability 起来了、窗口也画出来了，但内容区永远空白。定位方法是直接看适配层日志：

hdc shell hilog -x | grep -iE "NodeHandle|NodeContent|bind node handle"

只看到 bind node handle with node content failed, not find node content for id... → 走的是 demo 默认的 XComponent 链路（pages/WindowNode）；
看到 NodeHandleImpl Initialize success, support node handle feature → NodeContent 链路已生效。

改法是让 BrowserAbility 用回 WebBaseAbility 默认的 getContentPath()（pages/NodeHandleWindow），并把 AppWindowAdapter.bind() 从"一次性取 NodeContent"改成"轮询取"（100 次 × 100ms，最长 10s）。两处细节问题见 §5.1、§5.2。

2.4 第三步：把鸿蒙没有的能力摘掉

逐个决定"关掉"还是"降级"。判断顺序是：先让它跑起来 → 看哪里报错、哪里功能空转 → 再加 isOhos 分支兜住。完整改动清单见 §3.3，其中四处是"看起来正常、其实点不动"的典型：

看起来	实际	处理
有托盘图标	鸿蒙没有托盘 API，创建即失败	`system/index.ts:271` 直接不创建
标题栏有迷你窗口按钮	鸿蒙不创建该窗口，点了抛异常	见 §5.6（按钮本身也应隐藏）
启动时弹 DevTools	debug 构建 `isDev` 恒真	`windowList.ts:120` 加 `&& !isOhos`（§5.3）
设置页能选"启动模式"	鸿蒙端硬编码直开主窗口	设置项应置灰，见 §6.2

另外有一处真机结论留在代码注释里：AppWindowAdapter.ets:107-108 记载，StartOptions 里若带 processMode / startupVisibility / startWindowIcon，从 JS/Node 上下文发起窗口创建会报 401 invalid parameter，因此窗口只传 bounds。

2.5 第四步：处理原生模块

clip-filepaths 只提供 macOS/Windows/Linux 的 .node，鸿蒙没有对应构建 → 在组装阶段给它打桩（见 §5.5）。由此得出一条通用规则：凡是带 .node 的依赖，要么有鸿蒙构建，要么打桩，否则启动即崩。

2.6 第五步：真机联调闭环

整个过程就是这一个循环，工具用法见 §4.4：

改代码 → pnpm run build:ohos → ./hvigorw assembleHap … → hdc app install
      → aa start → snapshot_display 截图 / hilog / picgo-gui-local.log / hidumper
      → 定位 → 回到第一步

交互路径用 hdc shell uitest uiInput click x y 注入，比手点更可重复——§5.6 那个崩溃就是这样定点复现出来的。

2.7 构建时间线（有据可查）

hvigor 日志里的完整构建记录（时间为构建机本地时间，UTC−07:00）：

#	时间	结果	耗时	备注
1	2026-07-13 19:27:27	失败	1.5 s	`Unknown mode 'debug' is specified in the command line`（Error Code 00308018）
2	19:28:02	成功	21.9 s	改用 `--mode module` 后首次成功
3	19:31:56	成功	16.2 s
4	19:36:17	成功	34.8 s
5	19:40:40	成功	19.1 s
6	19:57:12	成功	31.4 s	首份 report 落盘于 19:56:41
7	20:02:15	成功	15.1 s
8	20:08:13	成功	59.1 s	当日最慢
9	20:12:53	成功	16.0 s
10	20:35:54	成功	15.8 s
11	20:45:01	成功	30.1 s
12	21:08:09	成功	16.9 s
13	21:16:34	成功	14.7 s	最后一次；21:39:44 提交 `5fc17e8`
14	2026-08-10 20:46:43	成功	17.2 s	距上次构建近一个月
15	20:48:01	成功	29.5 s	产出 `electron-default-signed.hap`（415 MB，20:48 落盘）

读这张表能看出三件事：

主适配集中在 2026-07-13 的 1 小时 50 分钟：13 次构建，1 次失败、12 次成功，成功构建平均约 24 秒。构建之所以快，是因为 HAP 里只有 ArkTS 壳，JS 产物是"拷进去"的——真正耗时的是 build:ohos 里的 electron-vite build 与 npm install，那部分不在这份日志里。
首次失败是 hvigor 命令行用法问题：--mode 只接受 module，debug/release 由 buildMode 决定（日志里可见 buildMode: 'Debug'）。正确命令就是 README 里那条 --mode module -p product=default。
构建成功之后还有一轮真机往返：8 月 10 日又补了 2 次构建（HAP 落盘 20:47/20:48），设备侧日志里对应 08-10、08-11、08-14、09-13 四次运行。构建通过 ≠ 真机可用——渲染链路是否打通，只有 hilog 和窗口截图能回答，这正是 §2.3 那次返工的原因。

2.8 ArkTS 编译告警（每轮都刷，但不是错误）

单次构建会打 337 条 WARN: ArkTS（去重后 308 处）。它们全部来自 libelectron 的 HAR 与 demo 遗留页面，没有一条出自 PicGo 自己改过的代码——所以不影响构建成功，但必须会分辨。按条数分布：

告警	单次条数	出现位置	是否要处理
`Function may throw exceptions. Special handling is required.`	117	`adapter/*.ets` 等	否，提示自行 try/catch
`To use this API, you need to apply for the permissions: …`	70	`adapter/*.ets`、`QuickLoginButtonComponent.ets`	视情况：真正用到置顶/隐私窗/悬浮窗/蓝牙时才报错，权限须在 `module.json5` 申请（出现最多的是 `ACCESS_BLUETOOTH`，38 次）
`Classes cannot be used as objects (arkts-no-classes-as-obj)`	69	各 `jsbindings/*Bind.ets`	否，框架写法
`… has been deprecated`（`vp2px` / `getShared` / `getContext` / `showToast` / `show` / `pushUrl` / `back` / `getParams`）	45	`pages/.ets`、`components/.ets`	否；但自研 ArkTS 代码应避开
`The system capacity of this api '…' is not supported on all devices`	30	`statusBarManager`、`selectMode`、`DocumentSelectMode` 等	要：这些能力在 PC 上不保证存在，用到就得做降级
`The '…' API is supported since SDK version 23. However, the current compatible SDK version is 5.0.5(17).`	6	打印、后台相关 API	要：`compatibleSdkVersion` 是 `5.0.5(17)`，用了更高版本 API 需自行评估（工作区已在 `build-profile.json5` 里补 `targetSdkVersion: 6.1.1(24)`）

还有一条有意思的编辑痕迹：同一批告警的行号会随构建漂移——AppWindowAdapter.ets 里的告警在第 3 次构建位于 153/157/159 行，第 10 次变成 152/156/158，第 13 次又变成 141/145/147。行号整体上移，说明这个文件在那两小时里被反复改短过，正好对应 §2.4 里"StartOptions 只传 bounds 以避开 401"那处改动。

3. 适配方案

3.1 三层结构

窗口渲染链路（实测）：

ArkUI NodeHandleWindow
  └─ WebNodeHandleWindow (web_engine 组件)
       └─ NodeContent  ──绑定──▶  AppWindowAdapter.bind(id, cb)
                                     └─▶ Chromium ContentSlot 绘制窗口表面

WebBaseAbility.getContentPath() 决定用哪条链路（web_engine/src/main/ets/ability/WebBaseAbility.ets:85-91）：

protected getContentPath(): string {
   if (this.nativeContext.IsSupportNodeHandleFeature()) {
    return 'pages/NodeHandleWindow';   // NodeContent：Chromium 直接绘制到窗口表面
  } else {
    return 'pages/Index';              // 旧链路：XComponent 中转
  }
}

真机日志确认走的是前者（hdc shell hilog -x，2026-09-13 11:38:39.463）：

09-13 11:38:39.463  A00001/com.jiujiang.picgo/Adapter:
  NodeHandleImpl Initialize success, support node handle feature

3.2 JS 产物如何进 HAP

scripts/build-ohos.js 做了 7 件事，目录映射刻意对齐 electron-builder 的产物布局：

步骤	行为	目标路径
1	调 `electron-vite build` 编译 main/preload/renderer	`dist_electron/`
2	清空目标目录	—
3	拷贝编译产物	`resfile/resources/app/dist_electron`
4	拷贝静态资源（对齐 `process.resourcesPath + '/public'`）	`resfile/resources/public`
5	写最小 `package.json`（`main: dist_electron/main/index.js`）	`resfile/resources/app/package.json`
6	在 `app/` 内 `npm install --omit=dev`（`externalizeDepsPlugin` 保留了 `require()`）	`resfile/resources/app/node_modules`
7	给不支持鸿蒙的原生模块打桩	见 5.5

渲染进程在真机上的实际 URL（hilog 抓取，能直接证明第 3~5 步生效）：

file:///data/storage/el1/bundle/electron/resources/resfile/resources/app/dist_electron/renderer/index.html#/main/plugins

3.3 应用侧代码适配清单

全部改动都遵循一个原则：新增 isOhos 分支，不改动其它平台行为。

位置	改动	为什么
`src/universal/utils/common.ts:147-148`	新增 `isOhos`；`isLinux` 顺带并入 `isOhos`	`process.platform` 在 libelectron 下为 `ohos`/`openharmony`
`src/main/utils/env.ts:7-13`	`isDev` 仍为 `!app.isPackaged`，但静态资源目录改为「非 OHOS 才用 `cwd()/public`，否则用 `process.resourcesPath/public`」	libelectron debug 构建下 `app.isPackaged` 恒为 `false`，按 isDev 走会取错 `public` 目录
`src/main/apis/app/window/windowList.ts:43`	启动模式兜底值：OHOS → `SHOW_MAIN_WINDOW`	鸿蒙没有托盘/悬浮窗，只能直开主窗口
`src/main/apis/app/window/windowList.ts:114`	`SETTING_WINDOW` 的 `options.show = true`	OHOS 上从 JS 调 `showAbility()` 会失败（`16000067`），必须创建即可见
`src/main/apis/app/window/windowList.ts:120`	`if (isDev && !isOhos) openDevTools()`	OHOS debug 构建 `isDev` 恒真，会每次启动都弹 DevTools
`src/main/apis/app/window/windowList.ts:161`	`MINI_WINDOW.isValid = process.platform !== 'darwin' && !isOhos`	没有悬浮窗能力，不创建该窗口
`src/main/lifeCycle/index.ts:89-101`	OHOS 跳过 `settingWindow.show()/focus()` 与迷你窗创建	同上，窗口已 `show: true` 直出
`src/main/apis/app/system/index.ts:271`	`if (!isOhos && !tray) createTray()`	鸿蒙无系统托盘 API
`libelectron/ohos_hap/electron/src/main/ets/entryability/BrowserAbility.ets:45-49`	使用 `WebBaseAbility` 默认的 `getContentPath()`，不再显式指向 `pages/WindowNode`	`WindowNode` 走 XComponent，永远不会注册 `NodeContent`，导致 `bind()` 超时、Chromium 不绘制（见 5.1）
`web_engine/.../adapter/AppWindowAdapter.ets:794-819`	`bind()` 加 100 × 100ms 轮询重试	Ability 启动与 NodeContent 注册存在时序竞争（见 5.2）

3.4 HAP 工程配置

// AppScope/app.json5
{ "app": { "bundleName": "com.jiujiang.picgo", "versionName": "1.0.0", ... } }

// build-profile.json5（app 级）
"compatibleSdkVersion": "5.0.5(17)",
"targetSdkVersion": "6.1.1(24)",
"runtimeOS": "HarmonyOS"

// electron/src/main/module.json5
"deviceTypes": ["2in1", "tablet"],
"abilities": [
  { "name": "EntryAbility",   "srcEntry": "./ets/entryability/EntryAbility.ets" },
  { "name": "BrowserAbility", "srcEntry": "./ets/entryability/BrowserAbility.ets",
    "process": ':browser' }   // Chromium 跑在独立进程
]

真机校验：

$ hdc shell bm dump -n com.jiujiang.picgo | grep -E 'deviceTypes|versionName|compileSdkVersion'
"deviceTypes": [ "2in1", "tablet" ]
"compileSdkVersion": "6.1.1.125"
"versionCode": 1000000
"versionName": "1.0.0"

3.5 README 规范：软件迁移能力分级

面向 OpenHarmony PC 的迁移项目，README 必须同时说明原软件、运行时、构建入口、已验证能力、已知限制和证据环境，不能只写“支持鸿蒙”或只提供一个 HAP 下载地址。迁移能力按项目当前已经验证的最低完整阶段标注：

阶段	能力定义	README 必须给出的证据
T0：可构建运行	能完成依赖安装、JS 产物构建、HAP 打包、安装并在 OpenHarmony PC 上启动	工具链版本、完整构建命令、产物路径、设备启动命令
T1：核心功能适配	主界面、核心业务流程、PC 输入与窗口交互可用；平台不支持的能力已明确禁用或降级	功能验证清单、设备与系统版本、截图或日志、未验证功能
T2：可交付与生态适配	具备稳定的 PC 体验和发布条件，完成签名、性能、异常恢复、升级以及插件/原生模块兼容性验证	发布包信息、稳定性与性能结果、签名说明、兼容性矩阵、问题反馈入口

README 应在醒目位置写明当前阶段，并分别列出“已验证”“不支持/已降级”“未验证”。阶段结论以实际设备验证为准：能打包不等于核心功能可用，核心功能可用也不等于达到发布条件。本文件按上述规范记录 PicGo 的 OpenHarmony PC 迁移能力，分级示例参考 ohos_markdownify。

4. 真机调试全流程

以下命令里的 hdc 来自 DevEco Studio：
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc

4.1 构建 + 安装

# 1) JS 产物 + 资源组装进 HAP 工程
pnpm run build:ohos

# 2) 构建 HAP（在 libelectron/ohos_hap 下）
./hvigorw assembleHap --mode module -p product=default

# 3) 安装（先确认设备在线）
hdc list targets -v                 # 3QC0****1875  USB  Connected
hdc app install electron/build/default/outputs/default/electron-default-signed.hap

产物体积：electron-default-signed.hap ≈ 415 MB，electron-default-unsigned.hap ≈ 414 MB（本地实测）。绝大部分是 Chromium 运行时 + node_modules，属于预期，不是打包错误。

4.2 启动与观察

hdc shell aa start -a EntryAbility -b com.jiujiang.picgo
hdc shell ps -ef | grep picgo          # 主进程 + :Renderer + :GPU + :NetworkService

真机进程形态（多进程架构可作启动成功的第一个信号）：

com.jiujiang.picgo                 # 主进程（Node）
com.jiujiang.picgo:NetworkService
com.jiujiang.picgo:Renderer
com.jiujiang.picgo:GPU