当前位置:首页>鸿蒙APP>Electron 鸿蒙开发踩坑实录:从白屏到成功部署的血泪经验

Electron 鸿蒙开发踩坑实录:从白屏到成功部署的血泪经验

  • 2026-11-10 06:26:05
Electron 鸿蒙开发踩坑实录:从白屏到成功部署的血泪经验

Electron 鸿蒙开发踩坑实录:从白屏到成功部署的血泪经验

没错,我就是那个在鸿蒙模拟器前盯着白屏看了两个小时的人。这篇文章记录了我从零开始搭建 Electron 鸿蒙环境、踩坑填坑的全过程,希望能帮你少走弯路。

前言:为什么会写这篇文章?

说实话,第一次听说 Electron 能跑在鸿蒙上的时候,我挺兴奋的。毕竟 VS Code、Slack 这些应用都是 Electron 做的,如果能把这些应用移植到鸿蒙平台,那鸿蒙的桌面应用生态不就丰富了吗?

但现实给了我一记响亮的耳光。

折腾了一周,我遇到了各种奇葩问题:编译失败、白屏、API 不兼容……最崩溃的是,网上能找到的资料少得可怜,大部分都是官方文档的翻译版,实战经验几乎没有。

所以我把这一周的踩坑经历整理成了这篇文章。如果你是鸿蒙开发者,想尝试 Electron 但没有经验,这篇文章应该能帮你省下不少时间。

第一部分:环境搭建(先别急着编译,看这一步)

1.1 系统要求:别拿笔记本硬扛

先说个血泪教训:我一开始用的是 16GB 内存的 MacBook Pro,结果编译到一半直接卡死,系统提示"内存不足"。

重要提示:Electron 鸿蒙开发有两种方式:

方式一:从源码编译
(需要 32GB 内存 + 200GB 磁盘,耗时 1-2 小时)
方式二:使用预编译包
(推荐,16GB 内存即可,5 分钟搞定)

如果你只是想快速上手,强烈建议使用预编译包。如果你需要修改 Electron 源码,才需要从源码编译。

方式一:从源码编译(需要 32GB 内存)

请务必满足以下要求:

要求项
规格
为什么需要
操作系统
Ubuntu 22.04(推荐)
官方测试环境,兼容性最好
磁盘空间
≥ 200 GB
Chromium 源码 + 编译产物,真的很占空间
内存
≥ 32 GB
编译 Chromium 需要大量内存,少了会卡死
CPU 架构
x86_64
目前只支持 x86_64 架构

提示:如果你只有 macOS 或 Windows,可以通过虚拟机(如 VMware、VirtualBox)运行 Ubuntu 22.04,但性能会差不少。我试过 VirtualBox,编译时间比原生 Ubuntu 慢了 3 倍。

重要:从源码编译需要大量资源,如果你只是想快速上手,强烈建议使用预编译包(见方式二)。

方式二:使用预编译包(推荐,16GB 内存即可)

如果你只是想快速上手,强烈建议使用预编译包,省时省力。

重要:预编译包已经包含了 app.disableHardwareAcceleration() 配置,直接运行即可,无需额外配置。

要求项
规格
为什么需要
操作系统
macOS 11+、Windows 10/11、Ubuntu 22.04
支持主流操作系统
磁盘空间
≥ 10 GB
预编译包体积小,占用空间少
内存
≥ 16 GB
运行预编译包,16GB 足够
DevEco Studio
5.0+(需匹配 Compatible SDK 5.0.5)
官方 IDE,必须版本匹配
Node.js
v20.18.1(推荐)
Electron 开发需要 Node.js 环境
终端设备
HarmonyOS NEXT(API 20+)平板/PC 或模拟器
运行环境

提示:macOS 需要使用 arm 系列的芯片才能支持运行鸿蒙模拟器。如果你用的是 Intel 芯片的 Mac,建议使用 Windows 或 Ubuntu 虚拟机。

1.2 安装基础工具:这些工具是干嘛的?

第一步:安装 git-lfs 和 ccache

# 更新软件源sudo apt update# 安装 git-lfs 和 ccachesudo apt install -y git-lfs ccache

为什么要装这两个工具?

git-lfs
:Git Large File Storage,用于管理大文件。Chromium 源码里有很多大文件(比如预编译的二进制文件),用 git-lfs 可以避免仓库体积爆炸。
ccache
:编译缓存工具。第二次编译时,如果代码没变,直接从缓存里拿结果,能节省 50% 以上的编译时间。

第二步:配置 repo 工具

repo 是 Google 开发的多仓库管理工具,用于管理 OpenHarmony 的代码仓库。Chromium 项目太大,被拆成了几百个 git 仓库,用 repo 可以一次性管理所有仓库。

# 创建 bin 目录mkdir -p ~/bin# 下载 repo 工具(使用码云镜像,国内访问更快)curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > ~/bin/repo# 赋予执行权限chmod a+x ~/bin/repo# 添加到 PATHecho 'export PATH=~/bin/:PATH' >> ~/.bashrcsource ~/.bashrc# 验证安装node -vnpm -v

建议:安装 LTS 版本(长期支持版),确保稳定性。我一开始图新鲜装了最新版,结果各种兼容性问题,最后还是换回了 LTS。

1.3 获取 Chromium-Electron 源码:最关键的一步

这是整个过程中最耗时的一步,也是最容易出错的一步。请务必耐心操作。

第一步:克隆仓库

# 克隆 chromium-electron 仓库git clone -b master https://gitcode.com/openharmony-sig/electron.git# 进入目录cd electron# 获取大文件(这一步可能需要半小时,取决于网络)git lfs pull

第二步:初始化 repo 并同步代码

# 初始化 repo(获取 OpenHarmony Chromium 代码)repo init -u https://gitcode.com/openharmony-tpc/manifest.git \  -b pc_chromium_132 \  -m chromium.xml \  --no-repo-verify# 同步代码(这一步会下载数十 GB 的代码,可能需要几个小时)repo sync -c# 获取大文件(可能需要执行多次,确保所有大文件都下载完成)repo forall -c 'git lfs pull'

注意:这一步会下载数十 GB 的代码,请确保网络稳定。如果中途中断,可以重新执行 repo sync -c 继续。我第一次同步时网络断了三次,折腾了一整天。

第三步:应用 Electron 补丁

OpenHarmony Electron 项目对 Chromium 做了一些修改,需要应用这些补丁。这些补丁包含了鸿蒙平台适配的关键代码。

# 进入 src 目录cd src# 清理 git 配置(避免补丁应用失败)find -name "*.git*" -exec rm -rf "{}" \;# 返回上级目录cd ..# 赋予脚本执行权限chmod +x override_files.sh# 应用补丁(这一步可能需要几分钟)./override_files.sh

第四步:安装编译依赖

# 进入 src 目录cd src# 运行依赖安装脚本(这一步可能需要半小时)# 注意:该步骤仅在首次获取代码时需要执行sudo ./build/install-build-deps.sh --no-chromeos-fonts# 返回上级目录cd ..

1.4 编译 Electron:喝杯咖啡,等一两个小时

所有准备工作完成后,执行编译脚本:

# 开始编译(这一步可能需要 1-2 小时,取决于你的硬件配置)./electron_build.sh

编译过程可能需要 1-2 小时,取决于你的硬件配置。编译完成后,产物会输出到 src/out/musl_64 目录。

常见编译错误处理

错误:cannot access 'rust-toolchain.tar.gz' : No such file or directory

原因:网络不稳定导致 Rust 工具链下载失败。

解决方案:重新执行 ./override_files.sh,然后重新编译。

# 重新应用补丁./override_files.sh# 清理编译缓存rm -rf src/out# 重新编译./electron_build.sh

1.5 使用预编译包:5 分钟搞定(推荐)

如果你只是想快速上手,强烈建议使用预编译包,省时省力。

第一步:下载预编译包

从官方仓库下载预编译包:

下载地址
:Electron 预编译包
版本
:electron34-release(基于 Chromium 132)

第二步:解压预编译包

# 解压预编译包unzip v34.6.3-20260105.1-release.zip# 进入目录cd libelectron

第三步:通过 DevEco Studio 打开项目

# 打开 ohos_hap 目录# 在 DevEco Studio 中选择 File → Open → 选择 ohos_hap 目录

第四步:运行项目

打开 DevEco Studio
通过设备管理器打开 2in1 模拟器
点击工具栏的运行按钮即可把 Electron 应用运行到模拟器

提示:使用预编译包不需要编译,直接运行即可,5 分钟就能看到效果。

第二部分:项目创建与配置

2.1 准备编译产物:把编译好的东西复制出来

编译完成后,需要将产物复制到项目目录。创建以下脚本 copy.sh:

注意:如果你使用的是预编译包,这一步可以跳过,因为预编译包已经包含了完整的目录结构。

#!/bin/sh# 定义源路径和目标路径source_path=./electron/src/out/musl_64destination_path=./electron# 如果目标目录存在,先删除if [ -d {destination_path}fi# 创建目标目录mkdir {source_path}/libelectron.so {source_path}/libffmpeg.so {source_path}/libadapter.so {source_path}/electron {source_path}/icudtl.dat {source_path}/v8_context_snapshot.bin {source_path}/chrome_100_percent.pak {source_path}/chrome_200_percent.pak {source_path}/resources.pak {destination_path}/localescp {destination_path}/localescp {destination_path}/locales

执行脚本:

# 赋予执行权限chmod +x copy.sh# 执行复制./copy.sh

2.2 创建 HAP 工程:用 DevEco Studio 创建项目

HAP(Harmony Ability Package)是鸿蒙应用的打包格式。使用 DevEco Studio 打开项目:

打开 DevEco Studio
选择File → Open
选择 libelectron/ohos_hap 目录

提示:预编译包已经包含了完整的 HAP 项目结构,直接用 DevEco Studio 打开即可。如果你没用过 DevEco Studio,建议先去官方文档看看入门教程。

2.3 配置项目结构:把 Electron 产物放进去

在 HAP 工程中创建以下目录结构:

libelectron/├── lib.unstripped/              # 未剥离符号的库文件│   ├── libadapter.so             # 鸿蒙适配层│   └── libelectron.so            # Electron 核心库├── ohos_hap/                  # 鸿蒙 HAP 项目│   ├── AppScope/                # 应用范围配置│   │   └── resources/│   │       ├── base/│   │       │   ├── element/│   │       │   └── media/│   │       └── profile/│   ├── docs/                    # 文档目录│   │   ├── electron-example.zip│   │   ├── electron调用ets指导文档0411.pdf│   │   └── ...│   ├── electron/                 # Electron 模块│   │   └── src/│   │       └── main/│   │           ├── ets/│   │           │   ├── Application/│   │           │   ├── entryability/│   │           │   ├── pages/│   │           │   └── ...│   │           ├── resources/│   │           └── module.json5│   ├── web_engine/               # Web 引擎模块│   │   └── src/│   │       └── main/│   │           ├── cpp/│   │           ├── ets/│   │           │   ├── adapter/│   │           │   │   ├── ElectronAppAdapter.ets    # Electron 应用适配器│   │           │   │   ├── WebWindow.ets          # Web 窗口组件│   │           │   │   └── ...│   │           │   ├── components/│   │           │   └── ...│   │           ├── resources/│   │           │   └── resfile/│   │           │       └── resources/│   │           │           └── app/            # 放置应用代码│   │           │               ├── main.js       # 主进程代码│   │           │               ├── index.html    # 入口 HTML│   │           │               └── ...│   │           └── module.json5│   └── ...│   ├── hvigor/                  # 构建工具配置│   ├── build-profile.json5│   ├── oh-package.json5│   └── ...└── ...

提示:这是预编译包的实际目录结构。如果你是从源码编译,需要将编译产物复制到相应位置。

2.4 配置 module.json5:告诉鸿蒙系统这是什么应用

编辑 electron/src/main/module.json5,配置应用的基本信息:

{  "module": {    "name": "pc_entry",    "type": "entry",    "srcEntry": "./ets/Application/AbilityStage.ets",    "description": "profile:main_pages",    "abilities": [      {        "name": "EntryAbility",        "srcEntry": "./ets/entryability/EntryAbility.ets",        "description": "media:app_icon",        "label": "media:app_icon",        "startWindowBackground": "$color:start_window_background",        "launchType": "specified",        "removeMissionAfterTerminate": true,        "exported": true,        "skills": [          {            "entities": ["entity.system.home", "entity.system.browsable"],            "actions": ["action.system.home", "ohos.want.action.viewData"],            "uris": []          }        ]      }    ]  }}

提示:这个配置文件是鸿蒙应用的"身份证",告诉系统这个应用叫什么、图标是什么、能做什么。具体每个字段的含义,可以参考鸿蒙官方文档。

2.5 编写应用代码:创建你的第一个 Electron 鸿蒙应用

现在让我们创建一个简单的示例应用,验证环境是否配置正确。

第一步:创建 index.html

在 libelectron/ohos_hap/web_engine/src/main/resources/resfile/resources/app/ 目录下创建 index.html:

<!DOCTYPE html><html><head>    <metacharset="UTF-8">    <title>Hello HarmonyOS!</title></head><body>    <h1>欢迎使用 Electron on HarmonyOS!</h1>    <p>这是运行在鸿蒙系统上的 Electron 应用</p></body></html>

第二步:创建 main.js

在 libelectron/ohos_hap/web_engine/src/main/resources/resfile/resources/app/ 目录下创建 main.js:

const { app, BrowserWindow } = require('electron');const path = require('path');// 禁用硬件加速(解决白屏问题)app.disableHardwareAcceleration();functioncreateWindow() {    const win = new BrowserWindow({        width: 800,        height: 600,        webPreferences: {            nodeIntegration: true,            contextIsolation: false        }    });    win.loadFile('index.html');}app.whenReady().then(createWindow);app.on('window-all-closed', () => {    if(process.platform !== 'darwin') {        app.quit();    }});

重要说明:

  • app.disableHardwareAcceleration()
     已经添加,解决白屏问题
  • nodeIntegration: true
     和 contextIsolation: false 是为了简化示例,实际项目中建议使用更安全的配置
  • 这个示例应用会创建一个 800x600 的窗口,显示欢迎信息

第三步:运行项目

打开 DevEco Studio
确保 libelectron/ohos_hap 项目已打开
通过设备管理器打开 2in1 模拟器
点击工具栏的运行按钮

如果一切正常,你应该能在模拟器中看到欢迎信息:“欢迎使用 Electron on HarmonyOS!”

第三部分:常见问题与解决方案(重点来了)

3.1 模拟器白屏问题(GPU 加速渲染)

问题描述

运行到模拟器后,应用启动但显示白屏,无法正常渲染界面。这是鸿蒙模拟器的一个已知问题。

我当时盯着白屏看了两个小时,差点把电脑砸了。

根本原因

鸿蒙模拟器在某些配置下无法正确使用 GPU 加速渲染,导致 Chromium 的渲染引擎无法输出画面。这通常发生在:

虚拟机环境中运行模拟器(我在 VirtualBox 里跑 Ubuntu,然后跑鸿蒙模拟器,套娃了)
GPU 驱动不兼容
模拟器配置不正确

方案一:禁用硬件加速(推荐用于开发调试)

重要提示:如果你使用的是预编译包,这个配置已经包含在内,无需额外操作。

如果你是从源码编译,需要在 main.js 中添加代码:

// web_engine/src/main/resources/resfile/resources/app/main.jsconst { app } = require('electron');// 禁用硬件加速(关键!)app.disableHardwareAcceleration();

加了这行代码后,白屏问题立马解决了。虽然性能会差一些,但至少能正常开发了。

方案二:在 WebWindow.ets 中添加命令行参数(备选方案)

如果方案一不行,可以尝试在 WebWindow.ets 中添加命令行参数:

// ohos_hap/web_engine/src/main/ets/components/WebWindow.etslet vec_args = [  '--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',  '--bundle-installation-dir=' + getContext().resourceDir,  '--disable-gpu',  // 禁用 GPU 加速  '--disable-gpu-compositing'  // 禁用 GPU 合成];

方案三:在真机上测试

白屏问题通常只在模拟器中出现。在真实鸿蒙设备上运行应用,通常不会遇到此问题。如果你有真机,直接上真机测试,省心。

3.2 autoStartupManager 错误(API 不兼容)

问题描述

初次启动项目时,控制台报错:

> hvigor ERROR: ArkTS Compiler Error1 ERROR: 10505001 ArkTS Compiler ErrorError Message: '"@kit.AbilityKit"' has no exported member named 'autoStartupManager'. Did you mean 'startupManager'?At File: /Users/xxxxxx/Desktop/ohos_hap/web_engine/src/main/ets/adapter/ElectronAppAdapter.ets:10:102 ERROR: ArkTS:ERROR File: /Users/xxxxxx/Desktop/ohos_hap/web_engine/src/main/ets/adapter/ElectronAppAdapter.ets:10:10ERROR Code: 10311006 ArkTS: ERRORError Message: 'autoStartupManager' is not exported from Kit '@kit.AbilityKit'.* Try following:  > Please make sure that Kit apis are consistent with SDK and there's no local modification on Kit apis.  > For more details on Kit apis, please refer to `https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/development-intro-api-V5`COMPILE RESULT:FAIL {ERROR:3 WARN:323}

根本原因

这个错误的原因很简单:鸿蒙 SDK 里根本没有autoStartupManager这个 API。

Electron 鸿蒙版本在适配时,尝试使用了 @kit.AbilityKit 的 autoStartupManager API,但这个 API 在鸿蒙 SDK 中并不存在。正确的 API 名字应该是 startupManager。

这是一个典型的 API 不兼容问题。Electron 鸿蒙版本还在早期阶段,很多适配工作还不完善,这种 API 不匹配的情况很常见。

解决方案

临时方案:注释相关代码

在 ElectronAppAdapter.ets 文件中,找到使用 autoStartupManager 的代码,暂时注释掉:

// 找到这一行(大概在第 10 行) 注释掉或删除// import { autoStartupManager } from '@kit.AbilityKit';// 找到使用 autoStartupManager 的地方,注释掉// autoStartupManager.enable();

为什么这样做是安全的?

自启动功能在鸿蒙上的意义有限:鸿蒙系统有自己的应用生命周期管理机制,不依赖 Electron 的自启动管理。在鸿蒙上,应用的自启动行为由系统统一管理,应用自己决定是否自启动是不符合鸿蒙的设计理念的。

权限模型差异:鸿蒙采用严格的权限声明制度,应用的启动行为由系统统一管理,而不是由应用自己决定。autoStartupManager 这种让应用自己决定是否自启动的 API,在鸿蒙的权限模型下是不合适的。

临时性:这只是开发阶段的临时方案。随着 Electron 鸿蒙版本的完善,官方会逐步适配这些 API。你可以关注 OpenHarmony Electron 项目 的更新,等待官方修复。

长期方案:等待官方适配

关注 OpenHarmony Electron 项目 的更新,官方会逐步完善这些模块的适配。如果官方修复了这个问题,你可以取消注释,使用正确的 API。

3.3 其他常见问题

问题:编译时出现 rust-toolchain.tar.gz 下载失败

解决方案:

# 重新执行补丁应用./override_files.sh# 清理编译缓存rm -rf src/out# 重新编译./electron_build.sh

问题:模拟器无法识别 HAP 包

解决方案:

# 检查 HAP 包是否正确签名hdc app install path/to/app.hap# 如果仍然失败,尝试卸载旧版本hdc shell pm uninstall com.example.app# 重新安装hdc app install path/to/app.hap

问题:应用在模拟器上运行缓慢

解决方案:

增加模拟器分配的内存和 CPU 核心数
关闭不必要的后台应用
在真机上测试

第四部分:最佳实践

4.1 开发工作流

具体步骤:

编写应用代码
:把 HTML、CSS、JavaScript 文件放在 web_engine/src/main/resources/resfile/resources/app/ 目录下
在 DevEco Studio 中编译 HAP 包
:点击Build → Build Hap(s)/APP(s) → Build Hap(s)
在模拟器或真机上运行
:点击右上角的 Run 按钮
调试和测试
:使用 DevTools 调试渲染进程,使用 Chrome DevTools 调试主进程
签名和发布
:申请开发者证书,在 DevEco Studio 中配置签名,生成签名的 HAP 包

4.2 性能优化建议

1. 减少内存占用:

使用轻量级的 UI 框架(如 Preact 而不是 React)
及时释放不需要的资源(比如关闭不用的窗口、清理缓存)

2. 加快启动速度:

预加载关键资源(比如首屏需要的 JS、CSS)
使用代码分割和懒加载(不要一次性加载所有代码)

3. 优化渲染性能:

避免频繁的 DOM 操作(比如不要在循环里频繁修改 DOM)
使用 CSS 动画而不是 JavaScript 动画(CSS 动画性能更好)

4.3 安全建议

1. 启用上下文隔离:

webPreferences: {  contextIsolation: true,  // 启用上下文隔离(安全!)  preload: path.join(__dirname, 'preload.js')}

2. 禁用 Node 集成:

webPreferences: {  nodeIntegration: false  // 禁用 Node 集成(安全!)}

3. 使用预加载脚本暴露 API:

// preload.jsconst { contextBridge, ipcRenderer } = require('electron');// 通过 contextBridge 安全地暴露 APIcontextBridge.exposeInMainWorld('api', {  send: (channel, data) => ipcRenderer.send(channel, data),  receive: (channel, func) => ipcRenderer.on(channel, (event, ...args) => func(...args))});

提示:Electron 的安全机制很重要,特别是当你加载第三方网页时。建议阅读 Electron 官方安全指南。

第五部分:资源与参考

官方文档

OpenHarmony 官方文档 - 鸿蒙系统的官方文档
Electron 官方文档 - Electron 的官方文档
DevEco Studio 使用指南 - DevEco Studio 的使用教程

社区资源

OpenHarmony Electron 项目 - Electron 鸿蒙版本的官方仓库
OpenHarmony 开发者论坛 - OpenHarmony 开发者社区

相关工具

hdc
:鸿蒙设备连接工具(类似 adb)
DevEco Studio
:鸿蒙官方 IDE
Chrome DevTools
:调试工具(Electron 内置)

总结

Electron 鸿蒙开发虽然还处于探索阶段,但已经具备了基本的可行性。通过这篇文章,你应该能够:

✅ 快速搭建开发环境(至少不会像我一样踩那么多坑)
✅ 创建并编译 HAP 应用
✅ 解决常见的坑点问题(白屏、API 不兼容等)
✅ 遵循最佳实践进行开发

关键要点回顾:

环境搭建
:需要 200GB+ 磁盘空间和 32GB+ 内存(别拿笔记本硬扛)
白屏问题
:禁用 GPU 加速或在真机上测试(加 --disable-gpu 参数)
autoStartupManager 错误
:注释相关代码,等待官方适配(鸿蒙 SDK 里根本没有这个 API)
持续学习
:关注官方更新,参与社区讨论

希望这篇文章能帮你少走弯路。如果在搭建过程中遇到问题,欢迎在评论区反馈,我们一起解决。

最新文章

随机文章