鸿蒙 PC 上的 Electron 首启排障:白屏、闪退、黑屏、卡死分别查哪一层
欢迎加入开源鸿蒙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。运行时 Electron 40.0.1-release / Chromium 144.0.7559.76 / Node 24.11.1。应用版本从 v0.1.0 升到 v0.1.1。
这是「墨记」系列的第 2 篇。第 1 篇把窗口开出来了,这一篇处理窗口开不出来、开出来不正常、以及开得慢的问题。范围限定在首次启动:四类症状分别对应哪个检查层,冷启耗时拆成哪几段,以及这一版在真机上暴露的几处平台差异。
这一篇的开发、构建、装机、截图仍然全部在鸿蒙 PC 上完成,没有换机器。墨记本身是一个鸿蒙应用,Electron 是加载进它进程里的运行时,下面所有排查都围绕这个前提展开。
先说明测量方式。本文的截图来自 hdc shell snapshot_display,输出 3120×2080 JPEG;界面里的数字用 hdc shell uitest dumpLayout 批量导出,不靠 OCR;所有计时都在应用进程内打点,不包含 hdc 命令本身的往返时间。这台机器上 F12 打不开 DevTools,所以没有用控制台取数,全部走应用内的探针和事件流。
1. 先说结论
四类症状不是四个 bug,是四个不同的层。先确定停在哪一层,再看那一层的日志,比在控制台里从头翻有效。
| 症状 | 检查层 | 探针 | 本机当前结果 |
|---|---|---|---|
| 白屏 | 渲染层 | did-fail-load / DOM 节点数 / console 错误 | 69 个 DOM 节点,加载失败 0 |
| 闪退 | 进程层 | render-process-gone / 启动标记 | 异常退出 0 次,渲染进程退出 0 |
| 黑屏 | 窗口层 | ready-to-show / 首帧 / 背景色 | 首帧时刻 869 ms(分段里「首帧完成」717 ms),背景正常 |
| 卡死 | 事件循环 | 心跳漂移 / IPC 往返 | 最大延迟 0 ms;演练时 2,905 ms |
这四项和冷启时间线放在同一个页面里。默认打开的是第 1 篇的环境基线,切到「启动排障」是这一版新增的内容:

冷启总耗时在 8 次启动里是 880–941 ms,均值 905 ms,中位数 906 ms。其中约 79% 花在最后一段「首帧完成」。这个比例决定了排查顺序:先量页面加载,再量 Electron 初始化。 如果反过来,很容易在只有 20 ms 的「Electron 就绪」上反复折腾,而真正占时间的 700 ms 一直没动。
四层的顺序不是按错误码排的,是按「谁先失去响应」排的。窗口没出现,先看进程;窗口出现但没内容,先看渲染;窗口和内容都在但画面黑,先看窗口层;画面正常但点不动,先看事件循环。这个顺序在后面的演练里会反复用到,因为同一句「打不开」可能停在任何一层。
为什么不先看日志?因为四类症状的日志不在同一个地方。白屏要看渲染层的加载事件和 DOM,闪退要看进程表和启动标记,黑屏要看窗口事件和首帧,卡死要看事件循环的漂移。没有先分层,就会在一堆无关日志里找一个不存在的错误。
2. 冷启拆成四段
2.1 打点方法
主进程启动时先算出进程创建时刻,之后每个节点取相对时间。process.uptime() 返回进程已经跑了多少秒,用它反推:
const BOOT_AT = Date.now() - process.uptime() * 1000;
const marks = {
mainLoaded: Math.round(Date.now() - BOOT_AT),
appReady: 0,
windowCreated: 0,
firstPaint: 0,
rendererReady: 0,
};
function segments() {
const points = [
{ key: 'node', label: 'Node 初始化', at: marks.mainLoaded },
{ key: 'electron', label: 'Electron 就绪', at: marks.appReady },
{ key: 'window', label: '窗口创建', at: marks.windowCreated },
{ key: 'paint', label: '首帧完成', at: marks.firstPaint },
];
let prev = 0;
return points.map((p) => {
const ms = Math.max(0, p.at - prev);
prev = p.at || prev;
return { key: p.key, label: p.label, at: p.at, ms };
});
}
四个打点分别落在:模块加载完、app.whenReady()、new BrowserWindow() 之后、did-finish-load。
mainLoaded 不是「第一行 JS 开始执行」,而是「模块加载完成」。因为 Date.now() - BOOT_AT 里包含了 Node 初始化和全部 require 的时间,这一段时间用户已经感知到了,不能从计时里剔除。
windowCreated 记在 new BrowserWindow() 之后,不是 ready-to-show。这两个事件在本机相差几百毫秒:构造窗口只花 27–37 ms,窗口真正显示要等到首帧前后。如果记在 ready-to-show,这一段会把渲染时间也算进去,四段就没有意义了。
第 1 篇的页面只显示了三段:主进程、窗口、首帧;appReady 虽然打了点,但没有进页面。这一版把四段都放进时间线,能看出窗口构造本身确实只占几十毫秒。这个拆分也解释了后面黑屏和卡死的边界:窗口构造失败是「没窗口」,构造成功但不显示是「黑屏」。
2.2 渲染层补最后一段
主进程不知道页面什么时候能响应,所以渲染层在两次 requestAnimationFrame 之后上报一次:
function reportBoot() {
requestAnimationFrame(() => {
requestAnimationFrame(async () => {
const nav = performance.getEntriesByType('navigation')[0];
const report = {
domContentLoaded: Math.round(nav ? nav.domContentLoadedEventEnd : 0),
load: Math.round(nav ? nav.loadEventEnd : 0),
};
await api.bootReady(report);
});
});
}
两次 rAF 是为了避开「DOM 已经解析但首帧还没提交」的时间窗。一次 rAF 只能保证下一帧开始,两次才能保证上一帧已经绘制。
这里有一个顺序问题:渲染层的上报可能早于 did-finish-load。本机实测出现过「页面可交互 916 ms、首帧 927 ms」的组合,如果按固定顺序算分段,最后一段会变成负数。原因是渲染层的 rAF 回调、IPC 发送、主进程接收,和 did-finish-load 是两套独立的事件流,谁先谁后取决于当时的调度。
处理办法是:四段只取主进程的四个打点,总耗时取 firstPaint 和 rendererReady 的较大值,两者差值单独记录,不混进分段。这样无论谁先到,四段都不会出现负数,总耗时也不会少算。
2.3 八次启动的数据
同一台机器、同一个 HAP,8 次冷启(第 1 行为 aa force-stop 后启动,其余为正常关窗后启动):
| # | 总耗时 | Node 初始化 | Electron 就绪 | 窗口创建 | 首帧完成 | DOMContentLoaded |
|---|---|---|---|---|---|---|
| 1 | 880 ms | 108 ms | 18 ms | 30 ms | 703 ms | 578 ms |
| 2 | 881 ms | 98 ms | 19 ms | 37 ms | 727 ms | 726 ms |
| 3 | 885 ms | 102 ms | 25 ms | 28 ms | 707 ms | 713 ms |
| 4 | 902 ms | 106 ms | 20 ms | 31 ms | 712 ms | 706 ms |
| 5 | 909 ms | 101 ms | 26 ms | 27 ms | 720 ms | 722 ms |
| 6 | 918 ms | 102 ms | 20 ms | 29 ms | 698 ms | 694 ms |
| 7 | 921 ms | 100 ms | 32 ms | 29 ms | 726 ms | 726 ms |
| 8 | 941 ms | 102 ms | 19 ms | 31 ms | 717 ms | 713 ms |
| 分段 | 最小 | 中位数 | 最大 | 占总耗时 |
|---|---|---|---|---|
| Node 初始化 | 98 ms | 102 ms | 108 ms | 11.3% |
| Electron 就绪 | 18 ms | 20 ms | 32 ms | 2.2% |
| 窗口创建 | 27 ms | 30 ms | 37 ms | 3.3% |
| 首帧完成 | 698 ms | 715 ms | 727 ms | 79.0% |
四段之和是 849–887 ms,总耗时是 880–941 ms,差额 0–72 ms,就是渲染层上报到达主进程的时间。这个差额不稳定,所以不要把它算进任何一段,也不要用它去推算页面性能。
结论很直接:优化 Electron 初始化没有意义,约 79% 的时间在页面加载这一段。
这里还有一处口径要写清楚,否则会和表里的分段数字看起来矛盾。表里「首帧完成」的最小值 698 ms、中位数 715 ms、最大值 727 ms,都是 segments() 算出来的段耗时(firstPaint - windowCreated);页面事件流里那句「首帧 869ms,主进程 102ms」是累计时刻(marks.firstPaint),两者相差 Node 初始化、Electron 就绪和窗口创建三段。截图那次的 941 ms 总耗时取的是 rendererReady(页面可交互),所以还会比首帧时刻再大一点。
这 700 ms 里具体发生了什么,可以从 DOMContentLoaded 和 load 的关系看出来。本机两者的差值不超过 6 ms,load 几乎紧跟 DOMContentLoaded,个别采样里 load 还略早于 DOMContentLoaded,属于计时精度和事件顺序的噪声,不影响结论。这说明页面没有异步资源:CSS、JS 都是本地文件,没有网络请求,也没有图片阻塞。时间主要花在 Chromium 建渲染进程、解析 HTML/CSS、执行 676 行 app.js 和首次布局绘制上。
这和桌面端 Electron 的体感不一样。桌面端一个空白窗口通常 200–400 ms 就出来了,因为 Chromium 的渲染进程已经在系统里预热过。鸿蒙上每次冷启都要重新拉起 :Renderer 子进程,再在沙箱里建立资源映射,所以 700 ms 里有一大块是固定的进程和沙箱成本,不是页面代码慢。
8 次数据的极差是 61 ms,主要来自系统调度和磁盘缓存,不来自代码。880 ms 那次是强杀后启动,941 ms 那次是正常关窗后启动,两者没有稳定的大小关系,说明这个量级的差异不能归因到某一个具体操作。文章里报区间和中位数,不报单次最好成绩。
这一版先不优化。原因是:如果没把四段拆开,就分不清「页面慢」和「渲染进程起得慢」。第 3 篇做窗口和 DPI 时会再测一次,到那时才有对比基线。
内存侧,主进程 RSS 在 257–263 MB 之间,八次采样没有明显漂移。页面本身只有 69 个 DOM 节点。这两个数字说明目前的页面还不构成内存压力,卡顿更可能来自启动路径,而不是运行期。
3. 四类症状,四个检查层
3.1 白屏:先确认页面有没有加载
白屏的定义是窗口已经显示,内容区是白的,系统标题栏还在。它落在渲染层,优先查三件事:页面有没有加载失败、DOM 有没有挂上、console 有没有报错。
win.webContents.on('did-fail-load', (_e, code, desc, url) => {
state.faults.didFailLoad.push({ code, desc, url, at: Date.now() });
logEvent('error', 'load', `页面加载失败 code=${code} desc=${desc} url=${url}`);
});
function domProbe() {
const root = document.getElementById('view-startup');
const bg = getComputedStyle(document.body).backgroundColor;
return {
nodes: root ? root.querySelectorAll('*').length : 0,
bg,
};
}
判断顺序不能反。
第一步看 did-fail-load。有记录,说明 HTML、JS 或 CSS 根本没进来,查 resourceRoot() 拼出来的路径和 HAP 内的 resfile 目录。CSP 拦截脚本不会触发 did-fail-load,这种情况要看 console 错误。
第二步看 DOM 节点数。节点数正常,说明页面结构在,问题在样式或可见性;节点数是 0,说明 HTML 根节点没挂上,通常是页面没加载成功;节点数正常但内容不对,去 console 错误里找脚本异常。本机正常状态是 69 个节点。
第三步看背景色和可见性。节点数正常、加载也成功,但页面还是白的,可能是 CSS 把根节点隐藏了、body 背景被设成白色、或者渲染层被一个全屏遮罩盖住了。
这三种情况在日志上的表现完全不同,不能只凭「页面是白的」下结论。第 1 篇的踩坑表里有一条「页面 404 / 白屏但没报错」,原因是用 __dirname 拼了 HAP 外的绝对路径。这一条在 did-fail-load 里会留下 ERR_FILE_NOT_FOUND,属于第一步就能定位的类型。
演练台里的「白屏」用一层全屏白色遮罩模拟页面内容不可见。遮罩盖住整个窗口,只留说明和恢复按钮:

这不是像素级的白屏检测。真正的白屏可能是资源 404、CSP 拦截、脚本异常、CSS 隐藏根节点,这一版只覆盖了「DOM 存在但不可见」和「加载失败」两种可探针的状态。像素级检测要靠截图比对,还要处理窗口缩放、DPI、主题色,不在本文范围内。
本机当前状态:69 个 DOM 节点,did-fail-load 0 条,白屏一项是绿色。
3.2 闪退:看进程还在不在
闪退和黑屏的区别是进程有没有了。窗口消失、桌面回到前台,先执行 hdc shell "ps -ef | grep ohosnotes"。有进程,是窗口或渲染问题;没有进程,才是闪退。
鸿蒙 PC 上的 Electron 不是一个进程,ps 能看到主进程和若干子进程(NetworkService、GPU、Renderer,GPU 有两个 PID)。本机一次采样:
| PID | 进程名 | 作用 | 退出后的现象 |
|---|---|---|---|
| 32286 | com.example.ohosnotes | 主进程、Node、窗口 | 整个应用消失 |
| 34105 | ...:NetworkService | 网络请求 | 页面请求失败,可能白屏 |
| 34116 / 34150 | ...:GPU | 合成与光栅 | 黑屏、花屏 |
| 34121 | ...:Renderer | HTML/CSS/JS | 内容区白屏或停止刷新 |
PID 每次启动都会变,进程名的后缀是稳定的。排查时看后缀,不要记 PID。
这张表解释了一个常见误判:任务管理器里看到四个带包名的进程,不等于开了四个应用实例。它们共用一个应用沙箱、一个 UIAbility 生命周期,只是 Chromium 的多进程架构在鸿蒙上的落法。区分「应用退出了」和「某个子进程退出了」,是闪退排查的第一步。
这些进程由系统托管,普通 shell 杀不掉。实测对 Renderer 执行 kill -9:
$ hdc shell kill -9 26345
/bin/sh: kill: 26345: Operation not permitted
这行输出本身就是一个结论:应用进程受系统保护,不能用「手动杀渲染进程看它能不能恢复」这种方式做实验。要模拟闪退,只能从外部对整包执行 aa force-stop,或者让主进程自己退出。
所以这一版用「启动标记」判断主进程是不是正常退出,用 render-process-gone 判断渲染进程有没有退出:
state.uncleanExit = fs.existsSync(markerFile());
if (state.uncleanExit) {
state.abnormalExits += 1;
logEvent('error', 'lifecycle', `上次未正常退出,累计异常退出 ${state.abnormalExits} 次`);
}
fs.writeFileSync(markerFile(), String(Date.now()), 'utf8');
win.webContents.on('render-process-gone', (_e, details) => {
state.faults.renderGone.push({ reason: details.reason, exitCode: details.exitCode });
logEvent('error', 'renderer', `渲染进程退出 reason=${details.reason} code=${details.exitCode}`);
});
app.on('before-quit', () => {
try { fs.unlinkSync(markerFile()); } catch (err) {}
});
正常关窗走 window-all-closed → app.quit() → before-quit,会删掉 .running 标记;强杀、崩溃、aa force-stop 不会删。下次启动看到标记还在,就记一次异常退出,并把累计次数加一。
实测用 aa force-stop 强杀,再重新 aa start:
$ hdc shell aa force-stop com.example.ohosnotes
force stop process successfully.$ hdc shell aa start -a EntryAbility -b com.example.ohosnotes
start ability successfully.
重启后「闪退」一行变成橙色,写「上次异常退出 · 累计 1 次」,启动历史里那一条标成「异常启动」:

这里有两个容易误读的地方。
第一,累计次数不是「本次启动的结论」。绿色只代表本次启动没有检测到未清理的标记;历史次数单独显示,不改变本次状态。这样区分是为了避免一次旧故障让页面永远报警,掩盖新问题。
第二,render-process-gone 和「整个应用退出」不是一回事。渲染进程退出后,主进程还在,窗口可能还在,只是内容区不刷新。真正让窗口消失的是主进程退出。两者要分开记录,否则会把「页面挂了」误判成「应用闪退」。
另外,uncaughtException 只捕获主进程的异常;渲染层的未捕获异常走 console-message,不会触发主进程退出。第 4 节的「渲染异常」演练就是这一类,它不会让应用闪退。
3.3 黑屏:窗口在,但画面全黑
黑屏时进程和窗口都在,问题在窗口层。三个检查点:ready-to-show 有没有触发、首帧有没有完成、窗口背景是什么颜色。
const win = new BrowserWindow(env.windowOptions({ title: '墨记 · 启动排障' }));
mark('windowCreated');
win.once('ready-to-show', () => {
mark('windowShown');
win.show();
});
win.webContents.on('did-finish-load', () => {
mark('firstPaint');
win.webContents.send('boot:marks', { ...marks, total: bootTotal() });
});
窗口用的是 show: false,ready-to-show 之后再显示。
如果这个事件不触发,窗口不会出现,用户看到的是「点了图标没反应」,不是黑屏。这种情况要查主进程有没有卡在创建窗口之前,或者 BrowserWindow 的参数有没有非法值。
如果触发了但首帧为 0,窗口会出现但内容是黑的。这时查 XComponent 的 type 是不是 SURFACE(第 1 篇踩坑表第 6 条)、GPU 进程在不在、资源路径对不对。
如果首帧正常、背景色也正常,但用户仍然看到黑色,那可能是系统层的问题:窗口被移到了屏幕外、窗口尺寸为 0、或者 GPU 合成失败。这三种在应用内探针里看不出来,要结合 ps 看 GPU 进程和系统日志。
黑屏和白屏的分界是「窗口有没有显示」。窗口没显示,用户看到的是桌面,属于启动失败;窗口显示了但内容黑,属于黑屏;窗口显示了、内容白,属于白屏。这三个现象在用户口里都叫「打不开」,在日志里是三套事件,先按窗口是否出现分类,能少走很多弯路。
演练台的「黑屏」把整窗背景置黑,系统标题栏保留:

它只能证明「背景色被改成黑色」这一种情况。真黑屏还要区分是 GPU 没起来、XComponent 配置错,还是页面背景本身是黑的。这三种在日志上的表现不同,不能只凭一张黑图下结论。
本机当前状态:首帧时刻 869 ms,背景 rgb(242, 244, 247),黑屏一项绿色。这里的 869 和表里的 698–727 不是同一口径:869 是 marks.firstPaint,从进程启动开始累计;表里的 698–727 是 segments() 算出的「首帧完成」这一段的耗时。以截图那次为例,102(Node)+19(Electron)+31(窗口)+717(首帧完成)=869,对得上。8 次采样的「首帧完成」中位数是 715 ms,写文章报区间和这个中位数,不报单次的累计时刻。
3.4 卡死:主进程被同步任务占住
卡死不是崩溃,进程还在,窗口还在,但点按钮没反应。它落在事件循环层。
检测方法是在主进程里跑一个 100 ms 的心跳,记录每次定时器的实际漂移:
function startHeartbeat() {
let last = Date.now();
setInterval(() => {
const now = Date.now();
const lag = now - last - 100;
last = now;
state.heartbeat.ticks += 1;
if (lag > 250) {
state.heartbeat.maxLag = Math.max(state.heartbeat.maxLag, Math.round(lag));
logEvent('warn', 'heartbeat', `事件循环阻塞 ${Math.round(lag)}ms`);
}
}, 100);
}
// drill:hang
const started = Date.now();
while (Date.now() - started < wait) {
/* 这一段里 IPC、定时器、心跳全部排队 */
}
阈值取 250 ms,是 100 ms 周期的 2.5 倍。低于这个值的抖动属于正常调度,不记事件;超过这个值才会进入 maxLag 和事件流。
演练用一段真正的同步循环,不用 setTimeout。setTimeout 只是把任务延后,事件循环还在转;同步循环会把整个主线程占住,IPC、定时器、心跳全部排队,这才是「卡死」的真实形态。
阻塞 3000 ms 后,心跳补记到的最大漂移是 2,905 ms,页面测到的 IPC 往返是 3,003 ms,两者相差 98 ms,是 IPC 排队和渲染层计时的误差:

这一项有一个容易误判的地方:主进程被阻塞时,渲染进程仍然能绘制,窗口不会卡成一张静止画面,按钮的 hover 效果也还在。界面还能动,不代表主进程没卡。 判断依据是心跳漂移和 IPC 往返,不是肉眼观察窗口。
另外,阻塞期间心跳不会更新,所以矩阵里显示的是「上一次唤醒后补记」的值。排查时看 maxLag,不要看 lastLag,后者只代表最近一次采样。如果只看 lastLag,阻塞结束后它会回到 0,很容易误判成「已经恢复、没问题」。
4. 故障演练台
四个演练入口,覆盖四类症状里可以安全注入的部分:
| 演练 | 注入位置 | 注入方式 | 恢复方式 |
|---|---|---|---|
| 白屏 | 渲染层 | 全屏白色遮罩,内容区不可见 | 点「恢复界面」或按 Esc |
| 黑屏 | 窗口层 | 全屏黑色遮罩 | 点「恢复界面」或按 Esc |
| 阻塞 3s | 主进程 | 同步 while 循环 | 3 秒后自动返回 |
| 渲染异常 | 渲染层 | setTimeout 里抛未捕获异常 | 自动,只记录不退出 |
所有演练只改界面状态和事件流,不写业务数据,不触发文件操作,不改变启动标记。恢复后矩阵重新探针,事件流保留记录。
白屏和黑屏的遮罩用 position: fixed; inset: 0;,盖住 Web 内容区,但不影响系统标题栏和窗口本身。这正是白屏、黑屏在现场里的样子:窗口在,标题栏在,内容区不对。遮罩支持 Esc 退出,是因为演练时用户可能点不到按钮,键盘是最低成本的退路。
渲染异常这一项和另外三项不同:它不会让进程退出,每次演练产生一条 console 错误。事件流里能看到完整的错误对象:

Uncaught Error: MOJI_DRILL_JS_ERROR 被 console-message 捕获,写入事件流,但页面的其它三项仍然正常。这也是 Web 层排查的一个边界:JS 异常不等于进程闪退,两件事要分开记录。
为什么不做「真崩溃」演练?因为系统不允许。3.2 节的 kill -9 返回 Operation not permitted,说明应用进程受保护;如果让主进程自己 process.exit,整个应用会退出,演练台也跟着没了,下一次启动才能看到结果。这一版把「真崩溃」放到外部测试:用 aa force-stop 强杀,再重新启动,看启动标记有没有生效。演练台负责可恢复的注入,外部命令负责不可恢复的整包退出,分工是清楚的。
5. 首启与真机差异
5.1 首次启动的权限弹窗
在鸿蒙 PC 上全新安装或清空应用数据后第一次启动,系统会弹一个模态框:
允许“Electron”发现和连接附近的设备?
是否允许不同设备间的数据交换
点「不允许」后应用正常启动,之后不再弹。这个弹窗会影响首启计时:本机这次 windowCreated 是 5,030 ms、firstPaint 是 5,053 ms,而正常冷启是 880–941 ms。差额不是应用代码慢,是模态框挡住了主进程。
这个数字很容易误导人。如果不排除弹窗直接看首启数据,会得出「鸿蒙上 Electron 启动要 5 秒」的错误结论。实际点掉弹窗之后,第二次启动就回到 900 ms 左右。首启数据必须标注是否包含权限弹窗,否则没有可比性。
弹窗里的应用名显示为 Electron,窗口标题是墨记。这段文案由系统弹窗渲染,不在 Web 层。这一段先记录现象,不在应用层处理。
权限弹窗还有一个副作用:它出现的时间不固定。系统可能在窗口创建前弹,也可能在页面加载中弹,所以首启的 5,030 ms 不是一个固定值,只是一个量级。要稳定复现,必须先清数据、再启动、再点掉弹窗,然后正常退出一次,让第二次启动走干净路径。
复现方法:hdc shell bm clean -n com.example.ohosnotes -d 清空应用数据后再启动,弹窗会重新出现。本文的干净数据都是在点掉弹窗、正常退出一次之后采集的。
5.2 platform 不是 ohos
第 1 篇按 process.platform === 'ohos' 判断鸿蒙,这一版在真机上打印出来是 openharmony。结果就是 isOhos 为 false,Menu.setApplicationMenu(null) 没执行,窗口顶部出现两层菜单:系统一层,Electron 一层。
修复只改一行:
const isOhos = process.platform === 'ohos' || process.platform === 'openharmony';
同一个判断还影响 floatWindow 这类只在鸿蒙上出现的窗口参数。所有平台判断都收在 ohos-env.js 里,改一处就够。
第 1 篇的踩坑表里已经写了「顶部菜单两层」,但没写触发条件;这次的触发条件是 process.platform 返回 openharmony,isOhos 为 false,Menu.setApplicationMenu(null) 根本没执行。也就是说,第 1 篇给出的修法是对的,但判断条件漏了一个值,换个运行时版本就会复发。
5.3 CPU 核数是 0
环境基线页的「CPU / 内存」一开始显示 0 核。原因是 os.cpus() 在鸿蒙上返回空数组。改成:
cpus: os.cpus().length || (os.availableParallelism ? os.availableParallelism() : 0)
os.availableParallelism() 返回 9,和 nproc 一致;第 1 篇表里记的是系统侧 14 核、进程可用 9 核两个口径。三个数字口径不同:系统标称、进程可用配额、Node 的 os.cpus()。应用内显示应该用「进程可用配额」,不要用 0,也不要直接把系统标称当运行时核数。修完之后诊断页「CPU」一行就是 9 核,这一篇和第 1 篇从此用同一组口径。
这一项和启动排障无关,顺手修掉,避免第 1 篇的体检页一直显示错误数据。
5.4 小结
| 现象 | 原因 | 处理 |
|---|---|---|
| 首启弹「允许 Electron 发现和连接附近的设备」 | 系统首次运行申请 | 允许或不允许均可,点掉后不再弹 |
| 首启窗口创建 5,030 ms | 模态框阻塞主进程 | 不是应用慢,排除弹窗后重测 |
| 顶部菜单两层 | process.platform 返回 openharmony | isOhos 同时匹配两个值 |
| CPU 显示 0 核 | os.cpus() 返回空数组 | 用 availableParallelism() 兜底 |
6. 这些数字是怎么拿到的
鸿蒙 PC 上的工具链和上一版不同。第 1 篇用 autoshot.js 在应用内截屏,再 POST 到本机;这一版删掉了它,改用系统命令直接取。
| 手段 | 用途 | 局限 |
|---|---|---|
hdc shell snapshot_display | 截整屏,3120×2080 | 只能截当前可见画面,不能截滚动区域 |
hdc shell uitest dumpLayout | 导出渲染后的控件文本和位置,一次 156 个 text 节点 | 依赖鸿蒙辅助功能接口,不含 DOM 树结构 |
| 应用内事件流 | 记录启动、演练、错误,最多 60 条 | 只在应用运行时可见,退出后丢失;启动历史单独写本地,最多 8 条 |
hilog | 系统和 Chromium 层日志 | 应用里的 console.log 没有进入 hilog,实测 grep 0 条 |
| DevTools | 控制台、网络、性能面板 | 这台机器上 F12 打不开,不可用 |
console.log 不进 hilog 这一条是实测结论。一开始想用 hdc shell hilog -x | grep moji 取启动日志,结果是 0 条;改用应用内的事件流之后,四段耗时、异常计数、演练记录都能在页面里看到,截图和文本导出都能取到。这个取舍对排查是够的,因为需要的是「应用自己认为发生了什么」,而不是系统层的完整日志。
uitest dumpLayout 是这一版效率最高的工具。它把页面上的每个文本节点导出成 JSON,941 ms、最大延迟 0ms、异常退出 1 次 这些值可以直接解析,不用一张张截图肉眼读。本文的 8 组冷启数据就是连续采集的 8 次冷启、每次导出一次 JSON 得到的。
还有一点:本文没有用 DevTools 的性能面板。F12 打不开只是表面原因,更实际的原因是 DevTools 打开后会改变渲染进程的调度,测出来的首帧和正常启动不一致。用应用内的打点,测的是用户实际走的路径,代价是要自己维护探针代码。
截图和文本导出的分工:截图用于文章展示和故障现场,文本导出用于批量取数。两者都来自同一台机器、同一个 HAP 版本,不混用不同版本的数据。
7. 这一版还差什么
- 白屏和黑屏是演练,不是像素级检测。真故障现场需要截图比对,这一版只做 DOM 和状态探针。像素级检测还要处理窗口缩放、DPI、主题色,不在本文范围内。
- 渲染进程退出后不会自动 reload,只记录
render-process-gone。自动恢复要配合窗口重建,第 24 篇多窗口时一起做。 - 没有监控 GPU 子进程的存活。
child-process-gone已经挂上,但没有做恢复动作,也没有把 GPU 退出和黑屏关联起来。 - 没有测热启。这一版的 8 次数据全是冷启,热启需要保留进程后二次
aa start,第 3 篇测窗口状态时补。 - 卡死只测了主进程同步阻塞。ArkTS UI 线程和 Chromium IO 线程的阻塞还没有分开测,第 9 篇专门做。
- 没有做启动耗时的自动上报。目前每次启动写一条本地历史,最多保留 8 条,没有跨设备对比。
这些缺口不影响本文的结论:四类症状的层是分开的,冷启的大头在页面加载,这两个结论不会因为补测热启或 GPU 监控而改变。
8. 改动清单
| 文件 | 改动 |
|---|---|
package.json | 版本 0.1.0 → 0.1.1 |
src/main/index.js | 冷启四段、心跳、故障记录、演练 IPC、启动标记 |
src/main/ohos-env.js | isOhos 兼容 openharmony |
src/preload/index.js | 新增 6 个白名单方法:bootReady / probe / resetProbe / log / drill / history |
src/renderer/index.html | 新增「启动排障」标签页、时间线、症状矩阵、演练遮罩 |
src/renderer/app.js | 时间线渲染、矩阵探针、演练逻辑、事件流 |
src/renderer/style.css | 新增标签页、时间线、矩阵、遮罩样式 |
src/main/autoshot.js | 删除,截图改由 hdc shell snapshot_display 完成 |
上一篇的 autoshot.js 会在启动后自动截屏并开第二个窗口,用来生成第 1 篇的图。这一版不需要它,删掉后启动流程少一个副作用:应用启动不会再自己弹第二个窗口。这个改动也影响第 1 篇的复现步骤:现在启动后只有一个窗口,第二个窗口要用页面上的「打开新窗口」按钮手动开。
HAP 体积:v0.1.1 签名包 219,693,198 B,比 v0.1.0 的 219,664,649 B 多 28,549 B。增量来自新增页面和探针代码;libelectron.so 仍是 186,990,528 B,没有变化。签名块带时间戳,每次重签字节数会浮动几十字节,对比体积时看量级,不要看个位。
9. 复现
这一版的关键命令都在鸿蒙 PC 上执行:
- 构建:
node $NODE_HOME/bin/hvigorw.js assembleHap --mode module -p product=default -p module=electron@default --no-daemon - 安装:
hdc install -r electron-default-signed.hap - 启动:
hdc shell aa start -a EntryAbility -b com.example.ohosnotes - 强杀:
hdc shell aa force-stop com.example.ohosnotes - 截图:
hdc shell snapshot_display -f /data/local/tmp/shot.jpeg,再hdc file recv取回,输出 3120×2080 JPEG - 读界面文字:
hdc shell uitest dumpLayout -p /data/local/tmp/layout.json,一次导出 156 个 text 节点
复现本文的数据需要注意三点:第一次启动会有权限弹窗,必须点掉后再计时;每次冷启前要正常关窗,让 .running 标记被清掉,否则会多记一次异常退出;清空应用数据会让权限弹窗重新出现,数据会从 0 开始。
参考
- 框架仓库:https://atomgit.com/CPF-Electron/Electron
- 预编译包:https://atomgit.com/CPF-Electron/Electron/releases/tag/v40.0.1
- 第 1 篇:从 367MB 预编译包到第一个能开窗的 HAP
- 开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
更多推荐



所有评论(0)