在鸿蒙 PC 上用 Electron 开发鸿蒙应用:从 367MB 预编译包到第一个能开窗的 HAP
欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
配套工程源码(墨记 MoJi):https://atomgit.com/gcw_TvBBemqt/moji-electron-ohos
验证环境:HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26,aarch64(2in1),HongMeng Kernel 1.13.0,系统侧 14 核、进程可用 9 核,23.3 GB。用到的框架是 CPF-Electron/Electron 的 v40.0.1 预编译包,运行时自报 Electron 40.0.1-release / Chromium 144.0.7559.76。
文中所有解压体积、strings 输出、构建日志、HAP 字节数都来自这台机器;界面上的三段启动耗时由页面在每次启动时计算。
这是「墨记」系列的第 1 篇。墨记是一个鸿蒙 PC 上的纪要工作台,后面 29 篇都在这一个工程上改,不另起项目。这一篇只做一件事:把 Electron 运行时加载进鸿蒙应用进程,开出一个窗口,窗口里显示这台机器的环境数据。
1. 先说结论:做到什么程度
下图是墨记 v0.1 启动后的界面,窗口压在 DevEco Studio 的 ohos_hap 工程上:

这一版做到四件事:
- 一个标准 HAP,包名
com.example.ohosnotes,从桌面图标启动,得到的是鸿蒙原生窗口。 - 渲染层是普通 HTML/CSS/JS,
document、localStorage、fetch均可用。 - 主进程是 Node 运行时,
process.versions.node、fs.writeFileSync、app.getPath()均可调用。 - 数据写在应用沙箱,路径卡片显示真实路径,重启后仍然存在。
版本与体积记录
下面这些数字是这篇文章所有结论的依据。按同样步骤操作应该能对上;对不上,说明某一层版本不同。
| 项目 | 实测值 |
|---|---|
| 设备 | HUAWEI MateBook Pro S(MOR-M1) |
| 系统 | HarmonyOS 7.0.0.111(SP15C00E101R9P2) |
| API / 架构 | API 26 / aarch64(2in1) |
| 内核 | HongMeng Kernel 1.13.0 |
| CPU / 内存 | 系统 14 核 / 进程可用 9 核 · 23.3 GB |
| 发行包 | v40.0.1.20261028.2-release.zip,367.6 MB |
| 中间层 | libelectron_144.tar.gz,389,351,686 B |
| 解压后总占用 | 2,318,615,602 B(约 2.16 GB) |
ohos_hap 工程 | 1,084,983,986 B(约 1.01 GB) |
lib.unstripped | 1,233,631,616 B(约 1.15 GB,可删) |
| 三个 so 合计 | 197,004,128 B |
| 运行时版本 | Electron 40.0.1-release / Chromium 144.0.7559.76 / Node 24.11.1 |
| 构建工具 | hvigor 7.26.11 / ohpm 6.0.1 / hdc 3.2.0f / node 24.18.1 |
| 构建命令行 | DevEco SDK 26.0.0.105 自带 hmos-clt |
| 签名 HAP | 219,664,649 B(约 209.5 MB,v0.1.0 首次构建) |
| 全量构建耗时 | 17 s 201 ms(52 个任务,0 个命中缓存) |
表里的版本号不是从文档抄的,是这台机器上下面这段命令的输出。系统属性、引擎里的版本字符串、解包命令都在同一段里,可以整段复跑:
# 系统与工具链
$ uname -a
HarmonyOS localhost HongMeng Kernel 1.13.0 #1 SMP Tue Sep 29 10:29:30 UTC 2026 aarch64 Toybox
$ param get const.product.model
MOR-M1
$ param get const.product.software.version
MOR-W52 7.0.0.111(SP15C00E101R9P2)
$ param get const.ohos.apiversion
26
$ node -v
v24.18.1
$ ohpm -v
6.0.1
$ hdc -v
Ver: 3.2.0f
$ node $HMOS_CLT_HOME/hvigor/bin/hvigorw.js --version
7.26.11
# so 里的版本字符串:不装 HAP 也能确认手上是哪个包
$ cd electron/libs/arm64-v8a
$ file libelectron.so
libelectron.so: ELF shared object, 64-bit LSB arm64, BuildID=b1769ad7b6d856e967e940311fb30fdf166aab51, stripped
$ llvm-readelf -d libelectron.so | grep NEEDED | wc -l
40
$ strings -a libelectron.so | grep -E '^Chrome/[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | sort -u
Chrome/144.0.7559.76
$ strings -a libelectron.so | grep -E '^Electron v[0-9]+\.[0-9]+\.[0-9]+$' | sort -u
Electron v40.0.1-release
$ strings -a libelectron.so | grep -E 'node\.js/v[0-9]+\.[0-9]+\.[0-9]+' | sort -u
node.js/v24.11.1
# 解两层压缩(体积变化见 §2.3)
$ unzip v40.0.1.20261028.2-release.zip
# 得到一个文件:libelectron_144.tar.gz
$ tar -xzf libelectron_144.tar.gz
# 得到 libelectron/
param get 是系统自带的属性读取命令,不需要 hdc 连设备,直接在本机 shell 里就能执行。查系统版本、API 版本、设备型号,比翻设置界面快。
表里有两个 Node 版本,用途不同:24.18.1 是 hmos-clt 自带的,用来执行 hvigor 和 ohpm;24.11.1 内嵌在 libelectron.so 里,应用主进程的 process.versions.node 返回这个值。构建用一个,运行时用另一个,两者不冲突,但排查问题时不要混。
版本号有一处不一致:发行页写的是 v40.0.1,运行时自报的是 40.0.1-release。不是笔误,是 tag 和内部版本号没有对齐。代码里判断版本、文章里写版本,都应该以 process.versions.electron 为准。
2. 为什么这套流程在鸿蒙 PC 上不一样
如果你在 Windows 或 macOS 上写过 Electron,第一反应一定是"npm install electron 然后 electron ."。在鸿蒙 PC 上这条路走不通,原因不是缺个包,是五个结构性的差别。
2.1 鸿蒙上没有"Electron 进程"
这一条决定了后面所有代码的写法。
在桌面端,Electron 是一个独立进程:主进程、渲染进程、GPU 进程,各自有 PID,你用任务管理器能看到。在鸿蒙上不是这样——你的应用是一个鸿蒙应用,Electron 是被加载进它进程里的一个动态库。层次是四层:
- 鸿蒙应用进程(一个 UIAbility 实例);
libelectron.so:Chromium + Node,被dlopen进来;libadapter.so:ArkTS ↔ C++ 的 JSBind 桥;- ArkTS 壳(
EntryAbility/WebAbility/XComponent),再往下是你的 HTML/CSS/JS。
由此产生四点:
- 任务栏和多任务界面里看到的是「墨记」,不是「Electron」;
- 崩溃时是整个应用一起退出,不是某个 renderer 单独退出;
- 不能用
process.pid去对照外部进程表,它只是这个鸿蒙进程里的一个值; - 多窗口不等于多进程,后面第 24 篇会专门讲这件事。
2.2 目标架构只有 arm64-v8a
预编译包里只有一套库:electron/libs/arm64-v8a/ 下只有 libelectron.so、libadapter.so、libffmpeg.so 三个文件,体积见 §3.2 的表。
没有 x86_64、没有 armeabi-v7a。这台机器是 aarch64,正好对上;如果你的鸿蒙设备是别的架构,这套包直接用不了,得自己编。
2.3 包是两层压缩,解开 2.16 GB
发行页给的 zip 解开,里面不是目录,是另一个 tar.gz:unzip v40.0.1.20261028.2-release.zip 得到一个 libelectron_144.tar.gz,再 tar -xzf libelectron_144.tar.gz 得到 libelectron/(两条命令在 §1 那段命令的末尾)。
体积变化是这样的:
| 阶段 | 大小 |
|---|---|
| 发行 zip | 367.6 MB |
| 中间 tar.gz | 389,351,686 B |
| 解开后 | 2,318,615,602 B |
| 其中 ohos_hap | 1,084,983,986 B |
| 其中 lib.unstripped | 1,233,631,616 B |
lib.unstripped 不要拷进工程。它是 Chromium 的调试符号,只有追崩溃栈时才用得上,占 1.15 GB,日常开发不需要。
2.4 签名绑定了 bundleName 和 UDID
鸿蒙的调试签名不是"随便生成一个就能装"。DevEco 的自动签名会在 ~/.ohos/config/ 下生成三个文件:default_ohos_hap..._4.p12(密钥库)、..._4.cer(证书)、..._4.p7b(描述文件/profile)。
p7b 是核心,它是一段签过名的 JSON,里面写着两件事:包(bundle-info 里的 bundle-name,以及权限等级 apl,调试签名是 normal)和设备(debug-info.device-ids,允许安装的 UDID 列表,device-id-type 为 udid)。包名对不上和 UDID 对不上,分别对应下面两条约束。
由此产生两个硬约束:
AppScope/app.json5里的 bundleName 必须和 p7b 里的bundle-name完全一致,差一个字符就装不上;- debug profile 绑定了设备 UDID,换一台机器必须重新签名。
这一篇的包名固定为 com.example.ohosnotes。这套签名材料只对这一个名字有效,改包名必须重新申请 profile。
2.5 npm install electron 为什么不行
在桌面端,npm install electron 装的是一个下载器,postinstall 阶段按 process.platform + process.arch 去拉对应的二进制:electron-v40.0.1-release-linux-x64.zip、electron-v40.0.1-release-darwin-arm64.zip,诸如此类。
这个矩阵里没有 ohos。
即使你强行把平台改成 linux、架构改成 arm64,拉下来的也是 glibc 的 Linux 二进制。鸿蒙的用户态是 musl + aarch64-linux-ohos 目标三元组,二进制不匹配,装上也跑不起来。
判断一个 so 是不是为鸿蒙编译的,两条命令就够:file libelectron.so 看目标架构,llvm-readelf -d libelectron.so | grep NEEDED | wc -l 数依赖。本机输出是 ELF shared object, 64-bit LSB arm64, stripped 和 40(命令和输出都在 §1 那段里)。
那 40 个 NEEDED 里,有一半是鸿蒙独有的系统库:libability_access_control.so、libbundle_ndk.z.so、libhilog_ndk.z.so、libhitrace_ndk.z.so、libhuks_ndk.z.so、libnative_display_manager.so、libnative_window_manager.so、libohfileuri.so、libohinput.so、libohinputmethod.so、libohprint.so、libpasteboard.so、libohcamera.so、libohavsession.so、libudmf.so、libqos.so。
普通 Linux 上根本没有 libhilog 和 libhuks。后面 30 篇要用的打印、剪贴板、输入法、拖拽、相机,入口也都在这一列里:
| 依赖 | 对应能力 | 第几篇会用 |
|---|---|---|
libohinputmethod.so | 中文输入法 | 第 5 篇 |
libudmf.so | 拖拽与分享数据 | 第 4 / 22 / 25 篇 |
libohprint.so | 系统打印 | 第 27 篇 |
libohcamera.so | 拍照取字 | 第 28 篇 |
libohavsession.so | 媒体会话 | 第 17 篇 |
所以"能不能用某个系统能力",不用查文档猜,先看引擎有没有链这个库。
2.6 一句话总结
| 差异维度 | 鸿蒙 PC 的实际情况 | 对你的影响 |
|---|---|---|
| 进程模型 | 没有独立 Electron 进程 | 崩溃是整个应用崩,排查要看应用日志 |
| 架构 | 只有 arm64-v8a | 换架构要自己编 |
| 依赖获取 | npm 的 electron 没有 ohos 目标 | 只能用预编译包,不能 npm install |
| 动态依赖 | 链了 40 个鸿蒙系统库 | 能力边界由引擎决定,不是文档决定 |
| 分发形态 | 两层压缩,解开 2.16 GB | 磁盘要留 5 GB 以上 |
| 签名 | p7b 绑定 bundleName + UDID | 改包名 = 重签;换机 = 重签 |
| 菜单 | 系统自带窗口菜单区 | 应用内菜单必须置空 |
| 资源路径 | HAP 内 resfile 只读 | 数据只能写 userData |
3. 预编译包里到底有什么
3.1 下载与解包
发行页在 https://atomgit.com/CPF-Electron/Electron/releases/tag/v40.0.1。直链下载 367.6 MB,支持断点续传。
解包后是两层目录,第二层各自是什么:
| 目录 | 体积 | 内容 |
|---|---|---|
ohos_hap/ | 1.01 GB | 完整 DevEco 工程,可以整层用 DevEco 打开 |
ohos_hap/AppScope/ | — | 应用级配置:bundleName、图标、版本号 |
ohos_hap/account_quick_login/ | — | HAR:华为账号快捷登录,不用可以删 |
ohos_hap/electron/ | — | entry 模块:主入口 + 三个 so |
ohos_hap/web_engine/ | — | HAR:窗口系统 + 适配层(主体) |
lib.unstripped/ | 1.15 GB | 调试符号,不要带进工程 |
3.2 三个 so 各管什么
| 文件 | 字节数 | 职责 |
|---|---|---|
libelectron.so | 186,990,528 | Chromium + Node 运行时,HAP 的 85% 是它 |
libadapter.so | 7,807,136 | ArkTS ↔ C++ 的 JSBind 桥,双向 RPC |
libffmpeg.so | 2,206,464 | 音视频解码 |
libadapter.so 负责 ArkTS 与 C++ 之间的调用转发。ArkTS 侧拿 native context,再用 JSBind.bindFunction(name, func) 把函数注册给 C++,窗口、菜单、剪贴板、通知都由这一层转发。第 6 篇会拆开这层桥。
3.3 哪一层是你该动的
改错层的代价是一天。
| 目录 | 类型 | 你该不该动 |
|---|---|---|
AppScope/ | 应用配置 | 要动:改应用名、版本号 |
electron/ | entry | 基本不动:入口只有几十行,全转发给 WebAbility |
electron/libs/arm64-v8a/ | 原生库 | 不动:换了就跑不起来 |
web_engine/ | HAR | 偶尔动:改适配层时动 src/main/ets/adapter/ |
web_engine/.../resources/resfile/resources/app/ | 你的应用 | 主要工作区:所有业务代码在这里 |
account_quick_login/ | HAR | 可以删:不用华为账号登录就移除 |
electron/src/main/ets/entryability/EntryAbility.ets 一共 59 行,不是五行。文件里是 import { WebAbility } from 'web_engine' 加一个 class EntryAbility extends WebAbility,然后七个生命周期钩子:onCreate、onDestroy、onWindowStageCreate、onWindowStageDestroy、onForeground、onBackground、onConfigurationUpdate,每个都是先 super.xxx() 再补自己的事;isAppEntry() 返回 true。真正多出来的只有一段:onCreate 里调 abilityAccessCtrl.createAtManager().requestPermissionsFromUser(this.context, ['ohos.permission.MICROPHONE']),把麦克风权限的申请放在应用入口,失败只打一行 [moji][mic] 日志。
其余全是转发。这是刻意设计的:平台适配收在一个 HAR 里,业务入口只做两件事——声明「我是应用入口」,以及申请系统权限。除了这一段 ArkTS,应用层代码不需要接触 ArkTS。
3.4 怎么确认手上的包是哪个版本
发行页的 tag 和运行时自报的版本可能不一致。这篇用的包,tag 是 v40.0.1,运行时是 40.0.1-release。
不装到机器上也能确认。so 里带着版本字符串,三条 strings 就够:一条抓 Chrome/ 前缀、一条抓 Electron v 前缀、一条抓 node.js/v 前缀(命令和输出都在 §1 那段里)。三条命令对应三个版本:Chromium 144.0.7559.76、Electron 40.0.1-release、Node 24.11.1。strings 扫 187 MB 的 so 大约要两三秒,比装一遍 HAP 快得多。
换任何一个预编译包,先跑这三条 strings。文档版本和运行时版本不一致的情况,在这一步就能发现,不用等到装到机器上。
4. 环境准备
4.1 需要的组件
| 组件 | 来源 | 本次实测版本 | 用途 |
|---|---|---|---|
| DevEco Studio | 华为官网,鸿蒙电脑版 | 6.0 系列 | 打开工程、自动签名、Run |
| hvigor | hmos-clt 自带 | 7.26.11 | 组装 HAP |
| ohpm | hmos-clt 自带 | 6.0.1 | 拉 ArkTS 依赖 |
| Node | hmos-clt 自带 | 24.18.1 | 跑 hvigor / ohpm |
| hdc | SDK toolchains | 3.2.0f | 装 HAP、看日志 |
| DevEco SDK | hmos-clt 自带 | 26.0.0.105 / API 26 | 编译器、打包、签名 |
命令行工具链在本机的固定位置是 /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/,下面分 node/bin/node、hvigor/bin/hvigorw.js、ohpm/bin/ohpm 和 sdk/ 四项,DEVECO_SDK_HOME 指的是最后一项。
4.2 环境变量:两个必需,两个可选
四个变量都在 §6.1 那段构建命令 的开头,这里只说各自的作用。NODE_HOME 指向 hmos-clt 自带的 Node,DEVECO_SDK_HOME 指向同一套工具链里的 sdk 目录,这两个是必需的;PATH 里加 Node 的 bin 和 SDK 的 toolchains(放 hdc)是可选的,不加就每次写全路径。
DEVECO_SDK_HOME 最容易漏。不给它,hvigor 会直接报:
00303217 Invalid value of ‘DEVECO_SDK_HOME’ in the system environment path
看到这个错误码,不用查别的,就是环境变量没指对。
4.3 签名:三种来源
| 方式 | 怎么来 | 能不能装真机 |
|---|---|---|
| DevEco 自动签名 | Project Structure → Signing Configs → 勾选自动生成 | 能,登录华为账号即可 |
| 手填 material | 把 p12/cer/p7b 路径写进 build-profile.json5 | 能,但换机要改 |
| SDK 自带 OpenHarmony 证书 | $DEVECO_SDK_HOME/default/openharmony/toolchains/lib/ | 不能,只能本地验签 |
第三种只能本地验签,不能装真机。SDK 里确实带了 OpenHarmony.p12,但 HarmonyOS 设备不认 OpenHarmony 根证书,构建能过,安装报错。
这一篇的工程里,build-profile.json5 的 signingConfigs 是占位符,不是可用材料:
| 字段 | 工程里的值 | 你要换成什么 |
|---|---|---|
certpath / profile / storeFile | ./signing/your-cert-or-profile | 你自己 ~/.ohos/config/ 下的 .cer / .p7b / .p12 绝对路径 |
storePassword / keyPassword | <ENCRYPTED_STORE_PASSWORD> / <ENCRYPTED_KEY_PASSWORD> | DevEco 自动签名生成的那两条密文 |
keyAlias | debugKey | 与 p12 里一致 |
signAlg | SHA256withECDSA | 一般不改 |
也就是说,直接 clone 工程是构建不出可安装包的:签名材料必须自己配。最省事的做法是上面表格第一行的 DevEco 自动签名——勾选后 DevEco 会把这三项写回 build-profile.json5,占位符被替换掉。storePassword 和 keyPassword 是 DevEco 加密过的串,不是明文,这两项由 DevEco 写入和解密,不需要手工构造。
4.4 SDK 是 26,为什么工程里写 20
打开 build-profile.json5,products[0].compatibleSdkVersion 写的是 "6.0.0(20)",而本机装的 SDK 是 26.0.0.105,设备系统是 7.0.0.111。三个数字对不上,但都对。
| 名字 | 值 | 含义 |
|---|---|---|
compatibleSdkVersion | 6.0.0(20) | 最低兼容 API 20,低于它的设备不装 |
| 本机 SDK | 26.0.0.105 | 编译时用的工具链和 API 定义 |
| 设备 API | 26 | 实际运行的系统能力 |
编译用 26 的定义,产物声明最低兼容 API 20。由此产生一个约束:调用的 API 必须是 API 20 就存在的。用了 21–26 才加的接口,编译能过(因为 SDK 是 26),装到 API 20 的设备上运行时失败。
判断方法是看 SDK 里的声明文件:$DEVECO_SDK_HOME/default/openharmony/ets/api/@ohos.xxx.d.ts,每个方法上面都有 @since。写原生适配层时先确认这一项。
这一篇是纯 Web 应用,不碰 ArkTS 新 API,所以 20 这个值不用改。等第 21 篇开始用沉浸光感、第 28 篇用端侧 OCR,就得逐个确认那些接口的 @since,必要时把 compatibleSdkVersion 抬上去。
5. 放应用代码:一个能开窗的主进程
5.1 代码放在哪
只有一处:web_engine/src/main/resources/resfile/resources/app/。它下面只有两个东西:package.json(main 指向 src/main/index.js,version 是 1.1.0)和 src/,src/ 再分 main/、preload/、renderer/ 三个目录(完整树见 §11.1)。
这个目录会被原样打进 HAP 的 resfile,运行时以只读方式挂载。不要把数据写在这里,写不进去。
5.2 最小主进程
最小可运行的主进程只有三件事:等 ready、开窗口、加载页面。
const { app, BrowserWindow, Menu } = require('electron');
const path = require('node:path');
// 鸿蒙 PC 上 platform 报的是 openharmony,只判断 ohos 会让下面的置空不执行
const isOhos = process.platform === 'ohos' || process.platform === 'openharmony';
app.whenReady().then(() => {
// 鸿蒙 PC 的窗口自带系统菜单区,再挂一套就是两层
if (isOhos) Menu.setApplicationMenu(null);
const base = {
width: 1180,
height: 760,
minWidth: 900,
minHeight: 620,
title: '墨记 · 环境基线',
backgroundColor: '#f5f7fa',
show: false,
webPreferences: {
preload: path.join(__dirname, '..', 'preload', 'index.js'),
contextIsolation: true,
nodeIntegration: false,
sandbox: false,
},
};
// 鸿蒙特有:只有设了环境变量 OHOS_FLOAT_WINDOW=1 才加,桌面端传了会报错
if (isOhos && process.env.OHOS_FLOAT_WINDOW === '1') {
base.type = 'floatWindow';
}
const win = new BrowserWindow(base);
win.once('ready-to-show', () => win.show());
win.loadFile(path.join(__dirname, '..', 'renderer', 'index.html'))
.catch((err) => {
console.error('loadFile 失败:', err.message);
win.loadURL(require('node:url').pathToFileURL(
path.join(__dirname, '..', 'renderer', 'index.html')).href);
});
});
这段代码里每个参数都不是随手写的:
| 参数 | 值 | 为什么 |
|---|---|---|
width / height | 1180 × 760 | 鸿蒙 PC 默认 2in1 窗口,这个尺寸下三栏布局不挤 |
minWidth / minHeight | 900 × 620 | 再小自检列表会折行,信息读不全 |
backgroundColor | #f5f7fa | 和页面底色一致,避免加载瞬间闪白 |
show | false | 等 ready-to-show 再显示,消掉第一帧空白 |
title | 墨记 · 环境基线 | 系统标题栏显示这个名字 |
preload | src/preload/index.js | 白名单桥,页面只能看到 5 个方法 |
contextIsolation | true | 页面 JS 和 preload 隔离,防止原型污染 |
nodeIntegration | false | 页面里拿不到 require |
sandbox | false | 模板默认值;这一版的 preload 只用了 contextBridge 和 ipcRenderer,第 7 篇会试着打开沙箱 |
type: 'floatWindow' 是鸿蒙特有的,只有设了环境变量 OHOS_FLOAT_WINDOW=1 才会加进去。这个值在桌面端不存在,传了会报错,所以放在平台判断里面——就是上面代码里 if (isOhos && process.env.OHOS_FLOAT_WINDOW === '1') 那三行:先判平台,再判环境变量,两个都满足才加 type。
三个参数的补充说明:
Menu.setApplicationMenu(null) 是必须的。 鸿蒙 PC 的窗口顶部有系统绘制的菜单条,不置空的话,应用内菜单会和它叠成两层,一眼就能看出来。
show: false + ready-to-show。 不这么做,窗口会先显示背景色,再出现页面内容。第 2 篇讲白屏时会展开。
loadFile 后面挂一条 loadURL 的退路。 我实测 loadFile 是通的,但 HAP 内的资源路径在不同版本上有过差异,多一条退路成本几乎为零。
5.3 平台判断收在一层里
业务代码里不应该出现 process.platform === 'ohos'。墨记把它收在 ohos-env.js 的三个函数里:isOhos 是一个常量,resourceRoot() 负责找资源根,windowOptions() 负责窗口参数。
resourceRoot() 的写法是先试 __dirname,再退回 process.resourcesPath:path.join(__dirname, '..', '..') 指到 app/,再用 fs.existsSync(path.join(byDirname, 'src', 'renderer')) 验证一下,存在就用它,不存在就返回 process.resourcesPath。官方模板的示例主进程就是用 __dirname 定位资源的,说明运行时可用;但如果你改过产物结构,__dirname 可能指错,这时 resourcesPath 是保底。实测这台机器上 __dirname 那条分支是通的。
另外,process.platform 在鸿蒙 PC 上的实际返回值是 openharmony,不是 linux、不是 darwin;v0.1 只判断了 'ohos',结果 isOhos 为 false,Menu.setApplicationMenu(null) 没有执行,窗口顶部就出现了两层菜单(截图里那行「文件 视图」)。第 2 篇把判断改成 'ohos' || 'openharmony' 之后才正常。写跨平台判断时两个值都要认。
5.4 preload:只暴露白名单
不要 contextBridge.exposeInMainWorld('electron', ipcRenderer)。那等于把整个 IPC 通道交给页面,任何 XSS 都能直接调主进程。
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('mojiAPI', {
diagnostics: () => ipcRenderer.invoke('diag:collect'),
copyText: (text) => ipcRenderer.invoke('diag:copy', text),
newWindow: () => ipcRenderer.invoke('window:new'),
windowCount: () => ipcRenderer.invoke('window:count'),
onMarks: (cb) => ipcRenderer.on('boot:marks', (_e, marks) => cb(marks)),
});
// 主进程侧:channel 要一一对应,多一个少一个都会报 No handler registered
function registerIpc() {
ipcMain.handle('diag:collect', () => collectDiagnostics());
ipcMain.handle('diag:copy', (_e, text) => {
try {
clipboard.writeText(String(text));
return { ok: true };
} catch (err) {
return { ok: false, error: err.message };
}
});
ipcMain.handle('window:new', () => {
createWindow();
return windows.size;
});
ipcMain.handle('window:count', () => windows.size);
}
五个方法,一个都不多。上半段是 preload,下半段是主进程:channel 要一一对应,多一个少一个都会在运行时报 No handler registered。第 7 篇会把参数校验、限流、白名单再收紧一遍。
diag:copy 没有直接 return { ok: true },因为 clipboard 在鸿蒙上不一定实现了。写失败时返回错误信息,页面会把失败原因显示在底栏,而不是静默失败。
5.5 环境基线页
这一版的页面不做业务功能,只做环境检查。目的是确认这套运行时在这台机器上是否正常。
页面分四块:
- 顶部状态:全部自检通过显示「运行时已就绪」,否则显示「N 项需关注」;
- 三段耗时:主进程就绪、窗口创建、首帧完成,单位毫秒,每次启动重算;
- 三张卡:运行时(Electron/Chromium/Node/V8)、平台(platform/arch/内核/CPU 内存)、路径(资源/数据/临时);
- 六项自检:渲染进程、预加载桥、页面来源、数据目录可写、中文字体、显示接口。
每项自检都实际执行:
// 数据目录是否可写:写入、回读、删除
function storageProbe() {
const dir = env.dataDir();
const probe = path.join(dir, '.write-probe');
try {
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(probe, String(Date.now()), 'utf8');
const back = fs.readFileSync(probe, 'utf8');
fs.unlinkSync(probe);
return { dir, writable: true, readback: back.length > 0 };
} catch (err) {
return { dir, writable: false, readback: false, error: err.message };
}
}
// 一次 IPC 返回全部诊断
function collectDiagnostics() {
const disk = storageProbe();
return {
app: { name: app.getName(), version: app.getVersion(), locale: app.getLocale(), isPackaged: app.isPackaged },
runtime: {
platform: process.platform, arch: process.arch,
electron: process.versions.electron, chrome: process.versions.chrome,
node: process.versions.node, v8: process.versions.v8,
},
system: { hostname: os.hostname(), release: os.release(), cpus: os.cpus().length, totalmem: os.totalmem(), freemem: os.freemem() },
display: displayInfo(),
paths: env.paths(),
storage: disk,
boot: { ...marks },
isOhos: env.isOhos,
};
}
// 显示接口不一定有实现,拿不到是一种合法状态,不能让整页挂掉
function displayInfo() {
try {
const d = screen.getPrimaryDisplay();
return { ok: true, width: d.size.width, height: d.size.height,
workWidth: d.workAreaSize.width, workHeight: d.workAreaSize.height,
scaleFactor: d.scaleFactor, rotation: d.rotation };
} catch (err) {
return { ok: false, error: err.message };
}
}
// 启动打点:用 process.uptime() 反推进程创建时刻
const BOOT_AT = Date.now() - process.uptime() * 1000;
const marks = { mainLoaded: Date.now() - BOOT_AT, appReady: 0, windowCreated: 0, firstPaint: 0 };
function mark(name) {
if (!marks[name]) marks[name] = Date.now() - BOOT_AT;
}
中文字体那一项用 canvas 量宽度,同一段话用 sans-serif 和 HarmonyOS Sans 各量一次,宽度不同说明字体已加载,没有回退到系统默认。
displayInfo() 外面包了一层 try/catch,原因很实际:鸿蒙上 screen 模块不一定有实现。拿不到不是错误,是一种合法状态,页面显示"显示接口不可用"就行,不能因为这一项把整页打挂。这种写法在后面会反复出现。鸿蒙上不同 API 的可用性不一致,不能假定都存在。
诊断页从上到下是运行时与环境卡片、六项启动自检,以及点击「打开新窗口」后并排的两个窗口:



5.6 启动耗时是怎么算的
Electron 的 app.whenReady() 之前,你拿不到任何窗口 API。但"用户从点击图标到看见内容"这段时间,必须从进程创建开始算。
用 process.uptime() 反推。这段代码就是 §5.5 那个诊断块的最后四行:const BOOT_AT = Date.now() - process.uptime() * 1000;,再配一个 mark(name) 往 marks 里写相对时刻。
process.uptime() 返回进程已经跑了多少秒,减去它就得到进程启动时刻。这样 mainLoaded 里包含了 Node 初始化和模块加载的时间,和用户感知是对齐的。
DevTools 在这台机器上打不开:F12 和 Ctrl+Shift+I 都没有反应,也没有新窗口出现。这不影响诊断:页面的六项自检和「复制诊断报告」已经覆盖了首屏需要的信息。DevTools 是否可用,留到第 2 篇做白屏排查时再单独验证。
5.7 诊断页的布局约束
页面要满足两个条件:窗口内不滚动就能看全,以及首屏能放下来自这台机器的所有关键数字。三条约束:
一屏之内。 1180×760 的窗口里,四块内容不滚动就能看全。卡片只放 4 行,其余信息不进首屏。需要滚动才能看到的数字,第一眼看不到,也就没法拿来对照。
每个数字都有出处。 页面没有硬编码的版本号。Electron 40.0.1-release 来自 process.versions.electron,23.3 GB 来自 os.totalmem()。CPU 那一项要单独说:v0.1 直接读 os.cpus().length,而这个调用在鸿蒙上返回空数组,所以页面显示的是 0 核(截图里能直接看到);系统侧是 14 核,进程可用配额是 9 核(nproc 与 os.availableParallelism() 一致),第 2 篇改成 os.cpus().length || os.availableParallelism() 之后显示 9 核。三个口径不要混:系统标称 14、进程可用 9、os.cpus() 返回 0。换一台机器,这一页显示的是那台机器的数据。数字不对时,说明环境与预期不同,而不是页面写错了。
允许失败。 六项自检中任何一项失败,页面仍能正常显示,只把该项的勾改成橙色感叹号,顶部徽章显示「N 项需关注」。displayInfo() 的 try/catch 和 storageProbe() 的 catch 分支都是这个用途。
这一版没有引入前端框架,没有 React、Vue,也没有打包器。当前页面只有约 200 行 DOM 操作,引入构建链会让单次改动后的等待时间从约 2 秒增加到 20 秒以上。第 11 篇做依赖体检时会重新评估这个选择。
5.8 从模板示例到墨记:改了哪些文件
预编译包里自带的示例也是一个能跑的应用。从它到墨记 v0.1,实际改动只有下面这些:
| 文件 | 改动 | 原因 |
|---|---|---|
AppScope/resources/base/element/string.json | app_name = 墨记 | 桌面图标下显示的名称 |
electron/src/main/resources/base/element/string.json | EntryAbility_label = 墨记 | 任务栏与窗口标签 |
app/package.json | name / version / description / main | 主进程入口与版本号 |
app/src/main/index.js | 重写 | 窗口创建、诊断 IPC、生命周期 |
app/src/main/ohos-env.js | 重写 | 平台判断、路径、窗口参数 |
app/src/preload/index.js | 重写 | 暴露 5 个白名单方法 |
app/src/renderer/index.html | 重写 | 诊断页结构 |
app/src/renderer/app.js | 新增 | 诊断渲染与自检 |
app/src/renderer/style.css | 重写 | 页面样式 |
build-profile.json5 | 未改 | SDK 版本沿用模板;签名材料是占位符,要自己配 |
electron/(除 string.json) | 未改 | 入口转发给 WebAbility |
web_engine/ | 未改 | 原生适配层不动 |
前 9 行是这一篇的全部工作量,后 3 行是"知道在哪但不动"。把这张表记住,后面每一篇的改动范围都能用它对照:只要不动 web_engine/,就不需要懂 ArkTS。
有一点需要说明:app/package.json 里的 devDependencies 写了 electron: ^40.0.0,这个依赖在鸿蒙构建里不参与打包——真正运行的是 libs/arm64-v8a/libelectron.so。它只是为了让桌面端 npm start 调试时能用。删掉也不影响 HAP 构建。
6. 构建
6.1 一条命令
在我这台机器上,完整命令是(环境变量、构建、成功日志、增量日志都在这一段里):
# 环境变量(两个必需,两个可选)
$ export NODE_HOME=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/node
$ export DEVECO_SDK_HOME=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/sdk
$ export PATH=$NODE_HOME/bin:$PATH
$ export PATH=$DEVECO_SDK_HOME/default/openharmony/toolchains:$PATH
# 构建:跳过 hvigorw 脚本,直接让 node 执行它背后的 js
$ cd /path/to/ohos_hap
$ $NODE_HOME/bin/node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js \
assembleHap --mode module -p product=default -p module=electron@default --no-daemon
> hvigor Finished :electron:default@PackageHap... after 549 ms
> hvigor Finished :electron:default@PackingCheck... after 8 ms
> hvigor Finished :electron:default@SignHap... after 2 s 97 ms
> hvigor Finished :electron:assembleHap... after 1 ms
> hvigor BUILD SUCCESSFUL in 17 s 201 ms
52 tasks in total: 52 executed, 0 up-to-date
# 紧接着再跑一遍,什么都没改
> hvigor BUILD SUCCESSFUL in 2 s 4 ms
49 tasks in total: 20 executed, 29 up-to-date
这里用 node hvigorw.js 直接执行,没有用 ./hvigorw 这个 shell 脚本。
鸿蒙的用户态是 Toybox,/bin/bash 不一定存在。hvigorw 这类脚本的 shebang 通常写的是 #!/bin/sh 或 #!/bin/bash,在某些沙箱环境里会直接报:
/bin/bash: bad interpreter: No such file or directory
绕过去的方法就是跳过脚本,直接让 Node 执行它背后的 hvigorw.js。功能完全一样,少一层解释器依赖。
--no-daemon 是我特意加的。daemon 模式下 hvigor 会复用上一次的工程状态,换了目录、改了依赖之后特别容易出现"明明改了却还是旧结果"的情况。命令行构建我建议一律加它,慢几秒,但每次都是干净的。
6.2 真实日志
成功时最后几行长这样(原文,去掉颜色控制符,就是 §6.1 那段的最后六行):PackageHap 549 ms、PackingCheck 8 ms、SignHap 2 s 97 ms、assembleHap 1 ms,最后 BUILD SUCCESSFUL in 17 s 201 ms,52 tasks in total: 52 executed, 0 up-to-date。
0 up-to-date 说明这是全量构建。52 个任务里耗时最多的是 ArkTS 编译和最后的签名、打包,SignHap 单独占 2.1 秒。
失败时最常见的是这三类,原文照抄:
00303217 Invalid value of ‘DEVECO_SDK_HOME’ in the system environment path
00303074 bundleName in the app.json5 does not match the bundle-name in the profile
00308018 Unknown Error
Failed :electron:default@CompileArkTS…
第一条是环境变量没配,第二条是包名和 profile 不一致,第三条是 ArkTS 编译失败——它最坑,第 8 节单独讲。
6.3 产物与体积构成
产物在 electron/build/default/outputs/default/ 下,三个文件:electron-default-signed.hap(219,664,649 B)、electron-default-unsigned.hap(218,041,022 B)、pack.info。
签名前后差 1,623,627 B,这就是签名块的成本。签名块里带时间戳,每次重新签名字节数会浮动几十字节,以实际产物为准。
体积构成(以 v0.1.0 首次构建的签名包 219,664,649 B 为准):
| 内容 | 大小 | 占比 |
|---|---|---|
libelectron.so | 186,990,528 B | 85.1% |
libadapter.so | 7,807,136 B | 3.6% |
libffmpeg.so | 2,206,464 B | 1.0% |
| ArkTS 字节码 + 资源 + 你的应用 | 22,660,521 B | 10.3% |
体积下限由引擎决定。 libelectron.so 已经占了 85%,业务代码的体积优化对总量影响有限。第 30 篇做上架体检时会用合规口径再算一次,数字不会差太多。
6.4 包内结构
用 unzip -l electron-default-signed.hap | head -25 看,实测输出(截取关键项,完整列表 32 个文件):
| Length | Name |
|---|---|
| 1426064 | ets/modules.abc |
| 7807136 | libs/arm64-v8a/libadapter.so |
| 186990528 | libs/arm64-v8a/libelectron.so |
| 2206464 | libs/arm64-v8a/libffmpeg.so |
| 650014 | ets/sourceMaps.map |
| 6367 | module.json |
| 6530 | resources.index |
| 10822192 | resources/resfile/icudtl.dat |
| 6365866 | resources/resfile/resources.pak |
| 539856 | resources/resfile/locales/zh-CN.pak |
| 750 | resources/resfile/resources/app/package.json |
| 5502 | resources/resfile/resources/app/src/main/index.js |
| 2215 | resources/resfile/resources/app/src/main/ohos-env.js |
| 496 | resources/resfile/resources/app/src/preload/index.js |
| 7418 | resources/resfile/resources/app/src/renderer/app.js |
| 2806 | resources/resfile/resources/app/src/renderer/index.html |
| 6157 | resources/resfile/resources/app/src/renderer/style.css |
你的 app/ 目录在 resources/resfile/resources/app/ 下,以只读资源形式存在。这也解释了为什么数据必须写 userData。
除了 so,剩下的体积主要来自 Chromium 的运行时资源:icudtl.dat 10.8 MB、resources.pak 6.4 MB、两个 chrome pak 约 300 KB。这些也不能删,删了 Chromium 起不来。
鸿蒙 PC 的 HiShell 里没有 unzip,这条命令要在装了 unzip 的构建侧终端里跑。
6.5 增量构建有多快
清完缓存的第一遍是 17 秒。不动任何代码,紧接着再跑一遍,就是 §6.1 那段命令最后的 BUILD SUCCESSFUL in 2 s 4 ms。
2.0 秒。49 个任务里 29 个命中缓存,实际执行 20 个,主要是打包和签名。
不同改动触发的任务数量:
| 改动内容 | 会触发什么 | 大致耗时 |
|---|---|---|
只改 renderer/ 里的 HTML/CSS/JS | 重新打包资源 | 2–4 秒 |
改主进程 index.js | 重新打包资源 | 2–4 秒 |
| 改 ArkTS 适配层 | ArkTS 重编译 | 15–30 秒 |
| 改依赖 / 换 SDK | 全量 | 17 秒起 |
应用层的迭代是秒级的,改原生适配层才需要等待。这也是把业务留在 Web 层的一个实际原因。
7. 装到机器上
7.1 DevEco 里跑
File → Open,选ohos_hap这一层。不是libelectron,不是electron。File → Project Structure → Signing Configs,勾上Automatically generate signature。- 等 Sync 完成,顶部出现
electron ⌄ | 此电脑 ⌄ | ▶。 - 右键左侧
electron模块 →Run 'electron'。
日志形如(具体耗时随机器变化):
Launch com.example.ohosnotes
$ bm install -p …/electron-default-signed.hap
install finished in 1s 232ms
$ aa start -a EntryAbility -b com.example.ohosnotes
Launch com.example.ohosnotes success in 582ms
如果顶部只有设备选择器、没有 ▶,说明 Run Configuration 没生成。右键模块 Run 一次就有了。
7.2 命令行两条
# 装 + 起
$ hdc install -r electron-default-signed.hap
[Info]App install path:/storage/Users/currentUser/Desktop/OBJ/electronOBJ/electronHAP/libelectron/ohos_hap/electron/build/default/outputs/default/electron-default-signed.hap msg:install bundle successfully.
AppMod finish
$ hdc shell aa start -a EntryAbility -b com.example.ohosnotes
start ability successfully.
# 起不来时按三层查
$ hdc shell "bm dump -a | grep ohosnotes"
$ hdc shell "ps -ef | grep ohosnotes"
$ hdc shell hilog -x | grep -i ohosnotes
-r 是覆盖安装。换过签名密钥之后建议先 hdc uninstall com.example.ohosnotes,否则可能报 install sign info inconsistent。
7.3 验证清单
| 检查项 | 命令 / 位置 | 期望 |
|---|---|---|
| 包装上了 | hdc shell bm dump -a | grep ohosnotes | 列出包名 |
| 进程起来了 | hdc shell ps -ef | grep ohosnotes | 有主进程 |
| 窗口出来了 | 桌面 | 一个「墨记」窗口 |
| 页面不是白屏 | 窗口内容 | 显示环境基线页 |
| 版本对得上 | 页面运行时卡片 | Electron 40.0.1-release / Chromium 144.x |
| 沙箱可写 | 自检第 4 项 | 绿勾,路径在 /data/storage/el2/base/... |
六项都过,第 1 篇的目标达成。
命令行实测输出就是 §7.2 那段:hdc install -r 返回 install bundle successfully,aa start 返回 start ability successfully。构建和安装都在命令行里完成;在 DevEco 里点 Run 'electron' 时,日志形如 §7.1 的四行,内容等价。
装完从桌面图标启动,回到环境基线页,先看右下角那行状态栏和运行时卡片:Electron v40.0.1-release、Chromium 144.0.7559.76、Node 24.11.1 三个版本对得上,"版本对得上"这一项才算过。

7.4 出问题先看哪一层
应用没起来时,按安装、进程、日志的顺序查,三条命令就是 §7.2 那段的后三行。三层与现象的对应关系:
| 现象 | 停在哪一层 | 大概率原因 |
|---|---|---|
| 第一条就没输出 | 安装失败 | 签名不匹配、UDID 不对 |
| 有包名,但没有进程 | 启动失败 | Ability 配置错、so 没进包 |
| 有进程,但没窗口 | 窗口创建失败 | XComponent、资源路径 |
| 有窗口,但是黑的/白的 | 页面加载失败 | 资源 404、CSP、JS 报错 |
这篇的 demo 在第一层就加了探针:did-fail-load、render-process-gone、uncaughtException 三个回调都会往 stderr 写一行带 [moji] 前缀的日志。查的时候先 grep moji,可以少看很多无关日志。
第 2 篇会把这张表展开成完整的排障流程,包括白屏的七种成因。
8. 工程换目录之后,构建为什么会失败
这个问题单独用一节说明。
8.1 现象
把 libelectron/ohos_hap 从一个目录复制到另一个目录,代码一行没改,构建直接失败:
hvigor ERROR: Failed :electron:default@CompileArkTS…
hvigor ERROR: Error Code: 00308018 Unknown Error
详细日志里有用的只有这几行:
Failed to resolve OhmUrl.
Failed to get a resolved OhmUrl for
“/storage/Users/currentUser/libelectron/libelectron/ohos_hap/web_engine/Index.ets”
imported by
“/storage/Users/currentUser/Desktop/OBJ/electronOBJ/electronHAP/libelectron/ohos_hap/electron/src/main/ets/pages/Index.ets”.
注意两个路径:imported by 是当前工程,被导入的却还是旧工程。
8.2 根因
DevEco 和 ohpm 在工程里留了四类"绝对路径",它们不会随着目录复制自动更新:
| 位置 | 内容 | 表现 |
|---|---|---|
electron/oh_modules/* | 指向 ../web_engine 的符号链接 | OhmUrl 解析到旧路径 |
web_engine/oh_modules/* | 指向 inversify、reflect-metadata、libadapter.so 的链接 | 第三方包解析失败 |
oh_modules/.ohpm/oh_modules/* | ohpm 的包索引链接 | 200 条编译错误 |
.bitfun/project.json | DevEco 记录的工程根 | IDE 打开的是旧目录 |
第一遍只修了 electron/oh_modules 下的两个链接,构建仍然失败,报错变成 inversify 解析不到。原因是 web_engine/oh_modules 里还有三个链接指向旧路径。
8.3 一次修干净
用一个脚本一次处理:
const fs = require('fs');
const path = require('path');
const OLD = '/旧/工程/根/ohos_hap';
const NEW = '/新/工程/根/ohos_hap';
function walk(dir) {
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
if (e.name === 'build' || e.name === '.trash') continue;
const p = path.join(dir, e.name);
const st = fs.lstatSync(p);
if (st.isSymbolicLink()) {
const target = fs.readlinkSync(p);
if (target.includes(OLD)) {
fs.unlinkSync(p);
fs.symlinkSync(target.split(OLD).join(NEW), p);
console.log('fixed', p);
}
} else if (st.isDirectory()) {
walk(p);
}
}
}
walk('.');
这篇的工程里,一共命中 9 个符号链接,分三处:
electron/oh_modules/下 2 个:account_quick_login、web_engine;web_engine/oh_modules/下 3 个:inversify、reflect-metadata、libadapter.so;oh_modules/与oh_modules/.ohpm/oh_modules/下 4 个:@ohos/hypium、inversify、reflect-metadata(@ohos/hypium出现两次)。
再加上 .bitfun/project.json 里 22 处旧路径字符串。全部替换完,清掉 build/ 和 .hvigor/cache,构建通过。
8.4 怎么快速判断是不是这个问题
只看一件事:报错里的绝对路径,等不等于你现在的工程路径。
不相等,就是这个问题。不需要去读 ArkTS 代码。
反过来说,如果你看到 00308018 但路径是对的,才需要往别处查:SDK 版本、ArkTS 语法、依赖缺失。这个错误码本身没有信息量,有信息量的是它前面那几行路径。
9. 踩坑总表
这一篇踩到的坑,按耽误时间排序:
| # | 现象 | 原因 | 改法 |
|---|---|---|---|
| 1 | CompileArkTS 报 00308018 Unknown Error,日志里路径指向另一个目录 | 工程被复制/移动过,oh_modules 里的符号链接还指向旧绝对路径 | 用 §8.3 的脚本扫一遍,重建所有链接 |
| 2 | 同上,链接修好后还报 Failed to get a resolved OhmUrl | .bitfun/project.json 里记着旧工程根 | 替换 .bitfun/ 下所有旧路径,或删掉让 DevEco 重建 |
| 3 | 00303217 Invalid value of 'DEVECO_SDK_HOME' | 命令行没导出 DEVECO_SDK_HOME | export DEVECO_SDK_HOME=.../sdk |
| 4 | 00303074 bundleName ... does not match | app.json5 的 bundleName ≠ p7b 里的 bundle-name | 改包名或重签,两者必须一致 |
| 5 | 构建报 signingConfigs 为空 | 模板只写了引用,没写材料 | 开自动签名,或手填 material |
| 6 | 窗口全黑 | XComponent 的 type 写成了 NODE | 必须是 SURFACE |
| 7 | 顶部菜单出现两层 | isOhos 只判断 ohos,实际返回 openharmony,Menu.setApplicationMenu(null) 没执行 | 两个值都认,再置空应用菜单 |
| 8 | 页面 404 / 白屏但没报错 | 用 __dirname 拼了 HAP 外的绝对路径 | 统一走 resourceRoot() |
| 9 | 数据写完重启就没了 | 写到了 resfile 下(只读) | 写 app.getPath('userData') |
| 10 | process.platform 判断全走错分支 | 鸿蒙 PC 上返回 openharmony(也见过 ohos),不是 linux | 'ohos' || 'openharmony' 一起判断 |
| 11 | 首次构建特别慢 | 全量编译 + 三个大 so 打包 | 正常,增量 2 秒 |
| 12 | 装上了但打不开,闪退 | 签名 profile 的 UDID 不是这台机器 | 重新生成签名 |
| 13 | screen.getPrimaryDisplay() 抛异常 | 鸿蒙上显示接口不一定实现 | try/catch,当作合法降级 |
10. 这一版还差什么
v0.1 只证明了"能开窗、能读环境",明确没做的事:
- 没有持久化业务数据,只有一个写探针;
- 没有多窗口管理,点"打开新窗口"只是再
new一个 BrowserWindow,没有窗口间通信; - 没有处理 DPI、多屏、自绘标题栏;
- 没有测冷启耗时分布,只有三个粗略打点;
- 没有做任何错误恢复,渲染进程挂了就是挂了。
这些内容安排在后面 29 篇里。下一篇从影响第一印象的问题开始:白屏、闪退、黑屏、卡死,四类症状分别对应哪一层,以及冷启的耗时分布。
11. 工程结构与一键复现
11.1 目录树
只列跟这一篇有关的层:
ohos_hap/
├── AppScope/
│ ├── app.json5 bundleName / versionName
│ └── resources/base/element/string.json app_name = 墨记
├── electron/ entry 模块
│ ├── src/main/ets/entryability/
│ │ ├── EntryAbility.ets 59 行,转发 WebAbility + 申请麦克风权限
│ │ └── BrowserAbility.ets 44 行,浏览器形态
│ ├── src/main/module.json5 deviceTypes: 2in1 / tablet
│ └── libs/arm64-v8a/
│ ├── libelectron.so 186,990,528
│ ├── libadapter.so 7,807,136
│ └── libffmpeg.so 2,206,464
├── web_engine/ HAR:适配层
│ ├── src/main/ets/ability/WebAbility.ets
│ ├── src/main/ets/adapter/*.ets 40 多个适配器
│ ├── src/main/ets/components/WebWindow.ets
│ └── src/main/resources/resfile/resources/app/ ← 你的代码
│ ├── package.json
│ └── src/{main,preload,renderer}/
├── account_quick_login/ HAR:可以删
├── build-profile.json5 签名材料、SDK 版本
└── hvigor/hvigor-config.json5
11.2 从零到装上,七步
命令都在前面几节里,这里只给顺序和落点,不重复贴:
| 步 | 做什么 | 命令在哪 |
|---|---|---|
| 0 | DevEco Studio 装好,登录华为账号 | — |
| 1 | 下预编译包(367.6 MB) | §3.1 的发行页链接 |
| 2 | 解两层压缩 | §1 那段命令的末尾 |
| 3 | 把应用代码放进模板的 resources/app/ | §5.1、§5.8 |
| 4 | 改应用名(可选) | §5.8 表格前两行 |
| 5 | 配环境变量 | §6.1 那段开头 |
| 6 | 构建 | §6.1 的 assembleHap |
| 7 | 装 + 起 | §7.2 |
全程磁盘要留 5 GB:解压 2.16 GB,工程里还会产生约 200 MB 的 build 产物,加上 HAP 本身 210 MB。
11.3 三个必须一致的名字
这是最容易改一处漏两处的地方:
| 名字 | 出现在哪 | 不一致的后果 |
|---|---|---|
com.example.ohosnotes | AppScope/app.json5 的 bundleName、p7b 的 bundle-name、aa start -b 参数 | 00303074,装不上 |
electron | 根 build-profile.json5 的 modules、-p module=electron@default | 构建找不到目标 |
src/main/index.js | package.json 的 main | 应用起来是空白,主进程没加载 |
前两个是鸿蒙侧的要求,第三个是 Electron 自己的要求。三个都对上,aa start 之后才有窗口。
参考
- 框架仓库:https://atomgit.com/CPF-Electron/Electron
- 预编译包:https://atomgit.com/CPF-Electron/Electron/releases/tag/v40.0.1
- 项目源码:https://atomgit.com/gcw_TvBBemqt/moji-electron-ohos
- 应用代码位置:
web_engine/src/main/resources/resfile/resources/app/ - 开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
更多推荐



所有评论(0)