Electron 鸿蒙 PC 排错实战:登录按钮永远"请求失败"的那半天

界面好好的、按钮能点、报错只有一句"请求失败"——这篇文章用一次 preload 失效的完整排查,把日志最早喊的为什么最没人听、兜底代码怎么把故障藏起来、一句 catch 吞掉的两种故障怎么区分开——这三个问题一次讲透。

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

环境:HarmonyOS PC(aarch64,API 26)+ Electron-OH v40.0.1
素材来源说明:和上一篇一样,这是我在自己的工程里故意埋的第二个错误,用于把"静默失效"这类最耗时间的故障写成可复现的排查记录。现象、日志、推理全部真实


0. 环境与实测设备

项版本/值
Electron-OHv40.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.authApiundefined无——访问 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. 复现与接入建议

复现步骤(写教程、培训用):

  1. main.js 里 preload 路径改成 path.join(__dirname, '..', 'preload.js');
  2. 构建装机,点 Run——窗口正常、登录卡片正常;
  3. 点登录,观察"请求失败";
  4. 渲染层 console 敲 window.authApi,undefined;
  5. 主进程日志里找 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 不是网络请求,"请求失败"四个字会把排查者(包括三个月后的你自己)带进沟里。
Logo

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

更多推荐