Electron 鸿蒙 PC 排错实战:登录按钮永远“请求失败“的那半天
Electron 鸿蒙 PC 排错实战:登录按钮永远"请求失败"的那半天
界面好好的、按钮能点、报错只有一句"请求失败"——这篇文章用一次 preload 失效的完整排查,把日志最早喊的为什么最没人听、兜底代码怎么把故障藏起来、一句 catch 吞掉的两种故障怎么区分开——这三个问题一次讲透。
欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
环境:HarmonyOS PC(aarch64,API 26)+ Electron-OH v40.0.1
素材来源说明:和上一篇一样,这是我在自己的工程里故意埋的第二个错误,用于把"静默失效"这类最耗时间的故障写成可复现的排查记录。现象、日志、推理全部真实
0. 环境与实测设备
| 项 | 版本/值 |
|---|---|
| Electron-OH | v40.0.1 |
| 壳工程 | ohos_hap(登录 + 笔记应用) |
| 故障注入点 | app/main.js 的 webPreferences.preload 路径 |
| 前置状态 | 上一篇的错误已修复,应用能正常启动 |
| 实测设备 | HarmonyOS PC(aarch64) |
1. “按钮报错就是按钮的问题”——这个理解是怎么被推翻的
上一篇修完"无窗口"的错,应用能启动了。我顺手把第二个错误也埋进去:main.js 里 preload 的路径,从
preload: path.join(__dirname, 'preload.js'),
改成
preload: path.join(__dirname, '..', 'preload.js'),
多爬一层目录,解析到 resources/preload.js——那个文件不存在。这个改动的形态像极了真实项目里的重构残留:有人觉得"preload 应该和资源平级",挪了路径,改完启动看了一眼,窗口出来了,以为没事。
然后点登录。界面上弹出一行红字:
请求失败,请重试

我一开始也以为这是登录逻辑的 bug——毕竟报错是登录按钮弹出来的。查了存储层(好的)、查了会话逻辑(好的)、查了密码校验(好的)。折腾了一圈才反应过来:"请求失败"这四个字本身就是误导,这不是网络请求,是进程间调用,失败的原因在调用链上游的桥上,不在按钮下面的代码里。
所以这个题目的边界很清楚:这类故障的特征是"界面正常 + 功能静默失效",排查的第一站不是功能代码,是功能代码脚下的那座桥——preload。
拆下来三件事:
- preload 挂掉时,应用到底处于什么状态;
- 兜底 catch 怎么把故障藏了一层又一层;
- 两种"空"怎么在设计层面就分开。
下面是干完之后的完整记录,包括我踩的每一个坑。
2. 效果展示
按老规矩,先给"效果"再讲排查。

图3 真正的证据,从启动那一刻就打出来了。路径是 resources/preload.js,而不是 resources/app/preload.js——差的正是注入的那一层 '..'。
三张图的顺序就是排查的顺序:先被图 2 误导,最后在图 3 找到答案。图 那条日志从应用启动的第一秒就在喊,喊了整整半天没人听。
3. 原理:preload 挂掉之后,应用处于什么状态
preload 在这套结构里的角色,第三篇讲过:contextIsolation 下渲染进程和 Node 之间唯一的通道。 它挂掉的后果不是"少个功能",是两侧彻底失联。把失联之后每一层的状态列出来:
| 层 | 状态 | 有没有异常表现 |
|---|---|---|
| 主进程 | 正常运行,窗口已创建,IPC handler 全部注册 | 无 |
| preload | 加载失败 | 主进程日志一条:Unable to load preload script |
window.authApi | undefined | 无——访问 undefined 的属性要到用时才炸 |
| renderer 启动逻辑 | catch 兜底,走"未登录"分支 | 无,登录界面正常显示 |
| renderer 登录提交 | catch 兜底,显示"请求失败" | 红字四个字 |
看这张表就能理解为什么这类故障耗时间:五层里只有两层有异常表现,而那两层的表现都太温和——一条启动日志没人看,一句 UI 提示指向错误方向。
preload 的加载者是主进程,Electron 加载失败时会打一条日志:
Unable to load preload script: Error: Cannot find module
'.../resfile/resources/preload.js'
这条日志不中断启动、不带醒目标记、不弹任何东西。它是整场故障里最早的目击者证词,也是被忽略得最彻底的一条。
4. 排查:从一句误导到一条铁证
整个排查走了一个弯路,弯路本身值得记录。
第一步,顺着按钮查。报错从登录按钮弹出来,先查了 auth.login 的调用链:参数对、存储层好、校验逻辑好。全对。此路不通。
第二步,怀疑 IPC 通道名。第三篇踩过通道名差字符的坑,本能反应去对通道名。auth:login 两端一致。还是不通。
第三步,在渲染层 console 摸桥。打开控制台敲:
window.authApi
// undefined
undefined。桥根本不存在。这一步是分水岭——之前所有排查都在功能层,从这一秒起换了层。
第四步,追"谁负责建桥"。authApi 定义在 preload.js,preload 由主进程的 webPreferences.preload 加载。回看 main.js:
preload: path.join(__dirname, '..', 'preload.js'),
__dirname 是 resources/app,加一层 .. 是 resources——preload.js 在 resources/app 里,路径多爬了一层。
第五步,回看主进程日志。真相一直在那儿:
Unable to load preload script: Error: Cannot find module
'.../resfile/resources/preload.js'
从启动第一秒就在。之前没看它,是因为 Run 面板全绿、界面正常,没有任何理由去翻日志。
修复一行:
preload: path.join(__dirname, 'preload.js'),
5. 把代码讲透
5.1 兜底 catch 是怎么层层保密的
故障能藏这么深,靠的是渲染层两个 catch 的接力。第一处,启动时:
// app/src/renderer.js - 启动(节选)
const session = await auth.session().catch(() => null);

window.authApi 是 undefined,auth.session() 这行直接抛 TypeError: Cannot read properties of undefined (reading 'session')。catch 接住,返回 null。下一行判断 session && session.username 不成立,走 showAuth()——登录界面正常显示,仿佛什么都没发生。
第二处,提交时:
formEl.addEventListener('submit', async (e) => {
…
try {
const result = authMode === 'login'
? await auth.login(username, password) // auth 是 undefined,这里抛
: await auth.register(username, password);
…
} catch (_) {
showError('请求失败,请重试'); // 真故障被压成一句 UI 文案
}
…
});

两处 catch 都是善意的设计:启动不该崩、按钮不该无响应。合在一起,效果是让"桥断了"伪装成"没登录"和"网络不好"。
这里有一个很容易被忽略的点:两个 catch 吞掉的是两种性质完全不同的失败。session() 返回 null 是业务上的正常(没登录),桥断了是系统级故障(功能瘫痪)。一个 () => null 把它们压平,页面从此失去了区分的能力。
5.2 修复不是删掉 catch,是让"空"带上原因
正确的做法不是把 catch 拆了——启动不能崩这个需求是真的——而是让接口把原因带出来:
// 更好的协议设计(示意)
{ ok: true, username: 'alice' } // 已登录
{ ok: false, reason: 'no-session' } // 正常的空:确实没登录
{ ok: false, reason: 'bridge-broken' } // 异常的空:桥没建起来
主进程的 session handler 里,"未登录"和"接口不存在"本来就可以区分。页面拿到 bridge-broken,该做的是在界面上明确告知"通信桥初始化失败,请重启应用",而不是画一张会永远失败的登录卡片。
catch 的正确用法是分类处理,不是统一抹平。 吞掉之前先问一句:我吞掉的这几种失败,页面的应对方式一样吗?不一样就不能用同一个 catch。
5.3 "请求失败"这个文案的教训
回头看那句 UI 文案。auth.login 是 IPC 调用,不是网络请求,"请求失败"四个字是在用错误的模型向用户描述故障。这个文案是我照着网络应用的惯性写的。
文案的问题不只是误导用户——它在排查时误导了我自己。看到"请求失败",我的第一反应是网络/服务/超时,而不是"桥"。文案是排查线索的一部分:UI 说什么,排查者就会先信什么。 写文案的时候,如果拿不准故障到底是什么,宁可写得模糊而不错得具体。
5.4 排查静默失效的第一定律
这次的完整路径可以压缩成一条规律:
功能静默失效时,先怀疑桥,再看功能代码。
理由很硬:桥断了的现象恰好是"功能失效",而桥的检查成本极低——console 里敲一行 window.authApi 三秒钟。功能代码的检查成本按小时算,桥的检查按秒算。便宜的检查先做,这是排查的基本纪律。
把桥的检查点固化下来,三处:
// 渲染层 console,三秒钟确认桥的状态
window.authApi // 应该是 {register, login, session}
window.notesApi // 应该是 {load, save, path}
undefined 就是桥断了,去查 preload 的加载——主进程日志里找 Unable to load preload script,以及 preload 路径的解析结果。
6. 我踩过的坑(每一条都有真实触发链)
坑一:preload 路径错一层,应用"看起来"完全正常。 全文主线。preload 加载失败在 Electron 里是非致命错误——打一条日志继续跑。致命和非致命是框架的判断,不是你应用的判断:对你的应用来说,桥断了和主进程崩了后果一样严重。
坑二:Unable to load preload script 喊了半天没人听。 这条日志出现在启动期,不伴随任何可见异常。启动期日志的价值不在当时,在故障发生后的回溯——所以"每次启动扫一眼 hilog"不是洁癖,是给自己留证词。
坑三:被自己的 UI 文案带偏方向。 "请求失败"让我先查了网络模型下的所有东西。文案说什么,排查者先信什么——写提示文案的时候要想清楚它未来会被怎么读。
坑四:兜底 catch 把两种故障压成一种。 .catch(() => null) 让"没登录"和"桥断了"走同一个分支。兜底的正确姿势是分类,不是抹平。
坑五:路径拼对了却忘了 __dirname 的基准。 '..' 在语法上毫无问题,错的是我对目录结构的假设。path.join(__dirname, '..', 'preload.js') 这种写法要先在心里把解析结果完整走一遍,而不是"大概在这个位置"。一条 console.log 的事。
坑六:排查走了功能层的全流程才上桥。 存储层、会话、校验挨个看了一遍,全对——因为它们真的全对。故障不在你正在查的那一层,这本身就是一个信息:功能层排除完,下一个该查的就是脚下。
7. 复现与接入建议
复现步骤(写教程、培训用):
main.js里 preload 路径改成path.join(__dirname, '..', 'preload.js');- 构建装机,点 Run——窗口正常、登录卡片正常;
- 点登录,观察"请求失败";
- 渲染层 console 敲
window.authApi,undefined; - 主进程日志里找
Unable to load preload script,看路径末尾。
全程五分钟,比任何口头讲解都直观。
接入建议:给应用加一个桥健康检查,启动时跑一次:
// app/src/renderer.js - 启动(示意)
const bridgesOk = window.authApi && window.notesApi;
if (!bridgesOk) {
// 界面明确告知"应用初始化失败,请重启",不要画登录卡片
}
硬限制,免得读者踩到同一堵墙:
- preload 加载失败是非致命错误,应用会继续跑——所以"能启动"证明不了"桥活着";
- 渲染层 console 敲
window.authApi是最快的桥体检,三秒钟,任何静默失效先做这个; Unable to load preload script只进主进程日志,Run 面板上看不到;- 兜底 catch 必须区分正常的空和异常的空,做不到分类就不要抹平;
- UI 错误文案别借别的模型——IPC 不是网络请求,"请求失败"四个字会把排查者(包括三个月后的你自己)带进沟里。
更多推荐




所有评论(0)