Electron 鸿蒙 PC 启动排错实战:Run 显示 success,窗口却没出现

aa start 说 success、进程活着、桌面上一扇窗都没有——这篇文章用一次完整的启动故障排查,把日志去哪找、崩溃发生在哪一层、报错行和出错文件为什么不在同一个地方——这三个问题一次讲透。

欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/

环境:HarmonyOS PC(aarch64,API 26)+ Electron-OH v40.0.1
素材来源说明:这次故障是我在自己的登录功能上故意埋的一个错误(为了把排查路径写成可复现的文章),但每一步现象、日志和排查动作都是真实发生的,没有编造成分


0. 环境与实测设备

项版本/值
Electron-OHv40.0.1
壳工程ohos_hap(登录 + 笔记应用)
故障注入点app/auth-store.js 的 module.exports
现象捕获DevEco Run 面板 + hilog
实测设备HarmonyOS PC(aarch64)

1. “Run 成功就是启动成功”——这个理解是怎么被推翻的

给登录功能加完账号存储层,我顺手做了一件事:把 auth-store.js 的导出从命名式改成直接式。动机很简单——这个模块只有一个函数,module.exports = createAuthStore 看着更利落。改完没跑测试就构建装机了。

点 Run。DevEco 的 Run 面板刷出一串熟悉的日志:

$ bm install -p .../electron-default-signed.hap
install finished
$ aa start -a EntryAbility -b com.example.ohosnotes
Launch com.example.ohosnotes success

两行全绿。然后我盯着桌面看了十秒:没有窗口。 不是黑窗口,不是白窗口,是什么都没有。进程管理器里应用活着,桌面上干干净净。

我一开始也以为这是签名或者安装的问题——毕竟 bm install 和 aa start 都说成功了。后来才反应过来:这两行日志只证明"包装上了、Ability 拉起来了",证明不了 JS 主进程活到了窗口创建那一步。 Electron 应用的启动链条比原生应用长一层,链条上任何一环断了,那两行 success 照样打。

所以这个题目的边界很清楚:在 Electron-OH 这套结构里,Run 面板的 success 只覆盖到 Ability 层,JS 层的生死要看 hilog——这是两类日志,不能互相替代。

拆下来三件事:

  • 这种"无窗口启动"要先去哪找证据;
  • TypeError 的调用栈怎么读;
  • 报错行和出错文件分离时怎么定位。

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


2. 效果展示

按老规矩,先给"效果"再讲排查。

请添加图片描述

图1 全文最有传播力的一张图:左边 Run 面板 success,右边干净的桌面。这张图本身就是本篇的核心矛盾。

请添加图片描述

图2 真正的证据。整屏只有这一条报错,其余全是无关噪音。

第一张图值得单独说:它不是摆拍,就是那十秒里我看到的东西。对原生开发者的直觉而言,“面板全绿"约等于"启动成功”;对这个结构,它只等于"Ability 层成功"。这个认知差是本篇全部排查时间的来源。


3. 原理:Electron-OH 的启动链条上,success 覆盖到哪里

把启动链条拆开看,success 在哪一步、崩溃在哪一步,一目了然:

步骤谁负责面板里的表现失败的表现
安装 HAPbminstall finished明确报错
拉起 UIAbilityaaLaunch ... success明确报错
AbilityStage / whenReadyArkTS 壳无独立日志静默
JS 模块加载(require)Node无独立日志静默,只进 hilog
whenReady 回调执行Node无独立日志静默,只进 hilog
new BrowserWindowNode窗口出现窗口不出现

看最后一行就明白了:"窗口出现"是这条链上第一个肉眼可见的信号。 它之前断任何一环,现象都一样——什么都没有。所以"没窗口"不是一个具体症状,它覆盖了四五种完全不同的故障,hilog 是唯一的区分手段。

这次的崩溃点在链条第 5 环:whenReady 的回调里,创建窗口的前一行。窗口创建代码一行都没执行到。


4. 排查:从"没反应"到一行 TypeError

排查动作只有三步,但每步都值得展开。

第一步,别盯着 Run 面板了,去看 hilog:

hdc shell hilog | grep -i ohosnotes

grep 的关键词用包名,大小写不敏感——进程名有时是包名有时是 Ability 名,加 -i 不吃亏。

第二步,在日志里找那一条 TypeError:

TypeError: createAuthStore is not a function
    at .../app/main.js:26

全文唯一一条报错,栈指向 main.js 第 26 行——createAuthStore(...) 的调用处。

第三步,就是本文的核心问题了:main.js 第 26 行没有任何问题。 参数对、路径对、文件在。把 main.js 来回看了三遍,没有发现任何可疑之处。

直到回头去看 auth-store.js 的最后一行:

// auth-store.js - 故障现场
module.exports = createAuthStore;      // 被改过:少了 { }

而 main.js 的 require 是这样写的:

// app/main.js - require 行(完全正确)
const { createAuthStore } = require('./auth-store');

真相拼出来了:auth-store.js 直接导出了函数本身,main.js 按"命名导出"的习惯去解构——从一个函数上解构属性,得到 undefined。注意这条链的每一步都不报错:require 成功(文件在)、解构成功(JS 允许从函数上解构,只是拿不到东西)、赋值成功(undefined 也是合法值)。错误被推迟到了最远的地方——调用那一行——才爆炸。

我本地复现了一遍这条链,输出值得贴出来:

require 返回类型: function
解构出的 createAuthStore: undefined
调用时抛出: createAuthStore is not a function

require 返回的是 function,解构出来却是 undefined——这两个事实放在一起,答案就只剩一个了。


5. 把代码讲透

5.1 两种导出习惯是怎么撞车的

这个错误的根源不是笔误,是两种都合法的导出习惯:

// 习惯 A:命名导出(本工程原先的写法)
module.exports = { createAuthStore };
// 消费方:const { createAuthStore } = require('./auth-store');

// 习惯 B:默认导出("简化"后的写法)
module.exports = createAuthStore;
// 消费方:const createAuthStore = require('./auth-store');

两种写法单看都没错,错的是改了导出没改消费方。JS 不做接口检查,CJS 的 module.exports 就是一个普通对象赋值,改它不会触发任何警告。混用两种习惯的团队里,这个坑迟早有人踩。

5.2 为什么崩在 whenReady 里而不是 require 时

时间线值得理清楚:

时刻发生了什么
模块加载require('./auth-store') 成功,拿到 function
解构得到 undefined,无报错
app.whenReady()注册回调,无报错
ready 事件触发回调执行,第 26 行调用 undefined → 此刻才炸

崩溃点离引入点隔了整整四步。这就是"lazy failure"的经典形态:错误的暴露时间取决于第一次使用的时间。 如果第 26 行在启动三个月后才被某条新路径第一次调到,这个雷就埋三个月。

防御方法很轻,加在 require 后面:

const mod = require('./auth-store');
if (typeof mod?.createAuthStore !== 'function') {
  throw new Error('auth-store 接口不符合预期');
}

请添加图片描述

宁可早崩三秒带一句人话报错,不要静默传 undefined 到最深处。 这两行代码值回票价的地方不是这次,是下次别人重构导出的时候。

5.3 报错栈指向 A 文件,改动在 B 文件,怎么定位

这次的定位路径可以抽象成一条规律:

  1. 栈是最可靠的——它指向的是"爆炸点",不是"错误源",先接受这个事实;
  2. 沿着爆炸点的数据流往回走:createAuthStore 这个值从哪来?——require;
  3. 检查 require 的两端:文件存在(B 在)、路径正确(都对),那就只剩接口形状;
  4. typeof 打印一次,function 还是 object,答案立刻收敛。

栈指向调用,不指向根源;定位的本质是沿着数据流从爆炸点走回根源。 这条规律比任何具体工具都通用。

5.4 为什么 Run 面板一个字都不提

Ability 层把 aa start 执行完就算交差了,JS 层的世界对它不可见。这不是鸿蒙的缺陷,是分层架构的正常代价——但代价是启动失败的可见性完全依赖你去翻 hilog。

实用结论:把这条命令固化成肌肉记忆:

hdc shell hilog | grep -i <包名>

请添加图片描述

每次点 Run 之后顺手扫一眼 hilog,和构建完看一眼产物一样,是这套平台上该长在身上的习惯。


6. 我踩过的坑(每一条都有真实触发链)

坑一:Run 面板全绿,应用没启动。 全文主线。教训:面板的 success 只覆盖到它管的层。 这套结构里,"启动成功"要靠窗口出现来确认,不靠日志。

坑二:改了导出没改消费方,错误延迟到调用点。 module.exports 换形式不报任何警告。改导出形式和改函数签名是同一级别的事,所有调用点必须一起过。

坑三:先怀疑了签名和安装。 bm install 和 aa start 都 success 的情况下,我第一反应是"是不是装的不是这个包",差点去重签名。浪费了几分钟才回到正轨。先看 hilog 再怀疑基础设施,日志比猜测便宜。

坑四:盯着报错行改了半天,而那行根本没错。 TypeError 指向 main.js:26,我对着调用参数看了三遍。栈指向的是爆炸点,排查的起点是它,终点不是它。

坑五:从函数上解构不报错。 const { a } = someFunction 在 JS 里完全合法,拿到 undefined 而已。这个语言特性让接口错位静默通过所有"语法检查"。能靠 typeof 在启动时拦下来的接口错位,不要留给运行时。


7. 复现与接入建议

想在自己工程里复现这个故障(写教程、做培训都用得上):

  1. 找一个用命名导出的模块,把 module.exports = { fn } 改成 module.exports = fn;
  2. 构建装机,点 Run;
  3. 观察桌面(无窗口)+ Run 面板(success)+ hilog(TypeError)三者的反差。

复现成本两分钟,教学价值远超两分钟。

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

  • JS 层异常不进 Run 面板,只进 hilog,hdc shell hilog | grep -i 包名 是这平台的第一排查工具;
  • 无窗口 ≠ 没启动,进程活着但窗口没建是完全可能的中间态;
  • module.exports 的两种习惯在同一个代码库里只能活一种,定一个写进规范;
  • 启动关键路径上的模块,require 之后做一次接口形状检查,两行代码换一个明确的报错;
  • 这类错误没有任何编译期信号,review 时看到导出形式变化,就把所有消费点找出来看一遍。

写到这里,我对"启动失败"的理解已经和最初完全不同了。它不是"应用没跑起来"这一个状态,而是链条上任何一环断掉后的同一个表象——表象收敛成一种,原因散落在五层。排查的全部功力,都在从表象走回原因的那条数据流上。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐