鸿蒙electron框架适配PC：从桌面番茄钟到鸿蒙可用应用：Pomotroid 适配全过程复盘

前言欢迎加入鸿蒙PC开发者社区共同打造开发者工具生态鸿蒙PC开发者社区 https://harmonypc.csdn.net/这篇文章记录的是一次比较完整的 Electron 项目鸿蒙适配过程。项目本体是Pomotroid一个界面不复杂、功能也很聚焦的番茄钟工具。桌面端体验其实很干净启动应用、开始计时、切换工作和休息轮次、打开设置页、查看统计页整个交互链路都很顺。但把这样一个 Electron 项目迁到 OpenHarmony / HarmonyOS 环境里之后问题并不会因为“它只是个番茄钟”就变少。真正动手后会发现桌面端默认成立的很多前提到鸿蒙里都要重新确认一遍主进程入口能不能正常拉起来前端资源是否能被正确打包和加载preload桥接脚本能不能执行多窗口逻辑在鸿蒙里是不是仍然成立GPU 进程是否稳定页面按钮点下去到底有没有事件还是事件到了但目标窗口根本不存在这次适配不是“把窗口点亮”就结束而是一路从能编译 - 能安装 - 能启动 - 能加载页面 - 能初始化计时器 - 能打开设置和统计 - 基本可用这样一步一步走过来的。如果你手里也有一个 Electron 小工具正准备迁到鸿蒙环境这篇文章应该能给你一个比较真实的参考。该项目适配的鸿蒙版本已经开源到https://atomgit.com/lqjmac/pomotroid-ohos一、这次适配的目标不只是“跑起来”一开始给自己定的目标其实很明确不做那种“勉强能截图交差”的适配。至少要做到下面几件事能稳定打包成鸿蒙应用安装后可以正常启动主页面能完成初始化而不是黑屏或白屏计时器逻辑能工作设置页和统计页可以打开页面交互不是摆设用户点了按钮要有真实反馈从结果看这些目标最后都达到了但中间踩过的坑也挺典型尤其适合拿出来单独讲讲。二、项目起点能构建但真正运行时问题一串刚接手这个项目时代码层面并不是从零开始。项目里已经有一套面向鸿蒙的承载工程也有基础脚本可以把 Web 资源和 Electron 资源同步进ohos_hap目录。当时比较关键的几个脚本已经具备雏形npm run buildnpm run ohos:syncnpm run ohos:build这意味着“构建通道”不是完全断的能减少很多纯工程初始化时间。但真正把应用装到设备上以后问题马上就出来了。最早看到的并不是页面内容而是一串运行日志里面最关键的几类报错包括页面虽然试图加载本地index.html但渲染器没有正常起来preload脚本报语法错误window.pomotroidDesktop为空前端桥接能力直接失效GPU 进程不断重启设置页和统计页点击后没有反应也就是说当时的状态不是“差一点就好了”而是链路上有好几个断点只不过它们是前后叠在一起的。三、第一关先把前端资源真正装进鸿蒙包里Electron 项目迁鸿蒙时最容易低估的一件事就是资源打包路径。桌面端很多情况下前端页面和运行时资源默认就在 Electron 应用目录附近路径组织也相对固定。但到了鸿蒙侧最后真正跑起来的资源位置已经变成了打包产物内部结构的一部分比如/data/storage/el1/bundle/.../resources/resfile/resources/app/...如果前端还按桌面习惯去假设资源路径很容易出现下面这种情况index.html是能找到的但/_app/...这些静态资源还是按根路径请求最终页面壳子打开了JS 和 CSS 实际上没正确加载这一步的处理重点有两个用构建脚本把build、electron、static和运行所需依赖统一同步到鸿蒙资源目录对build/index.html做一次改写把原本依赖根路径的/_app/...改成相对路径./_app/...这类修改不算复杂但很关键。因为如果静态资源路径不对后面看到的一切白屏、黑屏、空页面都不一定是真的业务逻辑问题。四、第二关preload不是小问题它直接决定前端桥接是否存在真正把页面跑起来的过程中最关键的一个断点其实是preload。当时设备日志里有两句信息非常致命Unable to load preload scriptSyntaxError: Cannot use import statement outside a module这两句一出来问题就很清楚了。桌面 Electron 项目里preload用 ESM 写法并不奇怪比如直接import{contextBridge,ipcRenderer}fromelectron;但在这套鸿蒙 Electron 壳里preload运行方式和桌面环境并不完全一致。这里它期待的是一个经典 CommonJS preload而不是 ESM 模块。结果就是preload没执行成功contextBridge.exposeInMainWorld(...)没跑window.pomotroidDesktop为空前端调用桥接 API 时直接报错主页面初始化流程中断所以这一步真正做的修复是把preload.js改成 CommonJS 版本新增preload.cjs主窗口webPreferences.preload明确改为指向preload.cjs修完这一步以后前端桥终于回来了后面日志里也开始出现真正有价值的渲染器初始化信息。五、第三关页面终于开始初始化了但 GPU 进程又开始掉链子preload修完以后事情明显往前走了一大步。日志里终于能看到这些信息[renderer] timer init:start[renderer] timer initial state ...[renderer] timer init:complete[renderer] main page settings loaded[renderer] main page themes loaded[renderer] main page init:complete看到这几行的时候基本就可以确认页面资源已经加载了前端桥可用了主页面初始化逻辑也跑完了但这时候又出现了另一个问题GPU 进程开始疯狂重启。日志里会不断刷类似的内容GPU state invalid after WaitForGetOffsetInRangeGPU process start times: 1, 2, 3, 4...这类问题在桌面 Electron 上不一定常见但在鸿蒙壳里并不少见。它的危险之处在于页面看起来可能勉强能显示但底层渲染进程会非常不稳定日志也会被 GPU 重启刷满。这一步做的处理主要是两层在应用启动尽可能早的阶段禁用硬件加速不要把软件回退路径一起禁掉后来做了两项调整在真正引导 Electron 主入口之前就在main.cjs里提前执行app.disableHardwareAcceleration()和disable-gpu相关开关去掉disable-software-rasterizer避免把软件渲染回退也一并堵死这一步不是为了“完全没有 GPU 日志”而是为了让应用先稳定地活下来。六、第四关主页面可用了但“设置”和“统计”依旧点不开这一步很有代表性因为它看上去像是“按钮没响应”但实际上根因完全不是点击事件本身。当时的现象是主页面能显示鼠标事件能进来光标状态会变化但点击“设置”和“统计”以后界面没有切换继续看日志关键线索就出来了AppWindowAdapter#showWindow(4)AbilityManager -- getProxy failed, proxyId: browser4 not foundAppWindowAdapter#showWindow(3)AbilityManager -- getProxy failed, proxyId: browser3 not found看到这里就知道了问题不在“点没点到”而在“点到了之后走错了路线”。原项目的顶部按钮逻辑本来沿用的是桌面版多窗口方案设置页单独开一个窗口统计页单独开一个窗口这在桌面 Electron 里很正常但鸿蒙这边当前实际只有主窗口browser1并没有对应的browser3、browser4代理存在。所以按钮点下去以后不是没触发而是在请求打开一个鸿蒙壳根本不存在的子窗口。七、这一步的真正修法OHOS 下不要硬搬桌面多窗口改成单窗口路由既然鸿蒙侧没有稳定可用的多窗口代理那就不要硬顶着桌面交互模型往前撞了。这一步最后采取的策略很直接桌面平台继续保留原来的多窗口行为OpenHarmony / HarmonyOS 下改成单窗口路由切换也就是说点击“设置”时OHOS 下不再window_create(settings)而是直接在主窗口切到/settings点击“统计”时同理切到/stats设置页和统计页自己的关闭按钮也不再尝试close()一个独立窗口而是直接返回主页/这样做的好处很明显不需要依赖额外的browser3/browser4主窗口内完成页面切换行为更可控对鸿蒙现阶段运行环境更友好这一步做完之后设置页和统计页终于真正可用了。八、构建流程也顺手补齐了不然每修一次都很难验证适配这类项目时如果没有稳定的构建脚本后面的调试会非常痛苦。这次过程中最终比较稳定的一套命令是npmrun buildnpmrun ohos:syncnpmrun ohos:build它们各自承担的职责也比较明确build生成前端静态资源ohos:sync把前端和 Electron 运行资源同步进鸿蒙工程ohos:build触发完整 HAP 构建中间还有一个实际踩到的工程问题是hvigor守护进程的锁文件。当时如果直接在受限环境里跑 HAP 构建会因为~/.hvigor/...下的 daemon lock 导致构建失败。后面把这个问题理顺以后assembleHap才真正稳定下来。这类问题不算业务逻辑但如果构建通道不稳定前面每做一次修复都很难确认是不是已经真正进包了。九、这次适配里最值得记住的几个判断节点回头看这个项目虽然不算大型应用但它把 Electron 迁鸿蒙时最常见的几个坑几乎都碰了一遍。如果把整个过程压缩成几个最重要的判断节点我觉得有这几条1. 白屏不一定是前端逻辑错了先看资源路径很多时候页面出不来不是框架问题而是静态资源根路径假设错了。2. 前端报桥接为空时先查preload只要window.xxx这种桥接对象没出现就不要急着查业务页面先确认preload是否真的执行了。3. 日志里出现初始化完成不代表整体就没问题了Pomotroid 这次就是典型例子前端初始化完成后GPU 进程仍然在后台疯狂崩。4. “按钮没反应”不等于“点击事件没触发”设置和统计页这个问题表面像前端按钮失灵实际上是后面的窗口目标根本不存在。5. 不要强行把桌面交互模型一比一搬到鸿蒙桌面上多窗口很自然但鸿蒙适配里有时候更务实的方案是先改成单窗口路由把功能做通。十、最终结果Pomotroid 已经具备鸿蒙侧基本可用性经过这一轮处理之后Pomotroid 在鸿蒙上的状态已经和最开始完全不是一个阶段了。目前已经完成的部分包括前端资源可正确打包并加载preload桥恢复正常主页面初始化完成计时器状态可读取和展示设置页可进入统计页可进入设置页和统计页在 OHOS 下采用单窗口路由切换HAP 可以稳定构建输出十一、最后一点感受这次做下来我对 Electron 迁鸿蒙这件事有一个更明确的感受真正难的地方往往不是改 UI也不是把某个命令跑通而是持续判断“当前这个问题到底断在链路哪一层”。你如果把问题层次看错了调试会非常绕。比如明明是preload没起来却一直在前端页面里找状态问题明明是 GPU 进程崩却以为是主题切换导致界面卡死明明是多窗口代理不存在却误判成按钮点击丢失反过来说只要每一步都能把“断点到底在哪”这件事判断清楚哪怕项目不是特别小适配也还是能稳步往前推。Pomotroid 这次就是一个挺典型的例子。它不是一上来就顺的但也不是那种完全没法做的项目。真正把链路一段一段接上以后最后呈现出来的结果其实很扎实。