Electron 鸿蒙开发踩坑实录：从白屏到成功部署的血泪经验
没错，我就是那个在鸿蒙模拟器前盯着白屏看了两个小时的人。这篇文章记录了我从零开始搭建 Electron 鸿蒙环境、踩坑填坑的全过程，希望能帮你少走弯路。
前言：为什么会写这篇文章？
说实话，第一次听说 Electron 能跑在鸿蒙上的时候，我挺兴奋的。毕竟 VS Code、Slack 这些应用都是 Electron 做的，如果能把这些应用移植到鸿蒙平台，那鸿蒙的桌面应用生态不就丰富了吗？
但现实给了我一记响亮的耳光。
折腾了一周，我遇到了各种奇葩问题：编译失败、白屏、API 不兼容……最崩溃的是，网上能找到的资料少得可怜，大部分都是官方文档的翻译版，实战经验几乎没有。
所以我把这一周的踩坑经历整理成了这篇文章。如果你是鸿蒙开发者，想尝试 Electron 但没有经验，这篇文章应该能帮你省下不少时间。
第一部分：环境搭建（先别急着编译，看这一步）
1.1 系统要求：别拿笔记本硬扛
先说个血泪教训：我一开始用的是 16GB 内存的 MacBook Pro，结果编译到一半直接卡死，系统提示"内存不足"。
重要提示：Electron 鸿蒙开发有两种方式：
（需要 32GB 内存 + 200GB 磁盘，耗时 1-2 小时）如果你只是想快速上手，强烈建议使用预编译包。如果你需要修改 Electron 源码，才需要从源码编译。
方式一：从源码编译（需要 32GB 内存）
请务必满足以下要求：
| | |
|---|
| | |
| | Chromium 源码 + 编译产物，真的很占空间 |
| | |
| | |
提示：如果你只有 macOS 或 Windows，可以通过虚拟机（如 VMware、VirtualBox）运行 Ubuntu 22.04，但性能会差不少。我试过 VirtualBox，编译时间比原生 Ubuntu 慢了 3 倍。
重要：从源码编译需要大量资源，如果你只是想快速上手，强烈建议使用预编译包（见方式二）。
方式二：使用预编译包（推荐，16GB 内存即可）
如果你只是想快速上手，强烈建议使用预编译包，省时省力。
重要：预编译包已经包含了 app.disableHardwareAcceleration() 配置，直接运行即可，无需额外配置。
| | |
|---|
| macOS 11+、Windows 10/11、Ubuntu 22.04 | |
| | |
| | |
| 5.0+（需匹配 Compatible SDK 5.0.5） | |
| | |
| 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 Large File Storage，用于管理大文件。Chromium 源码里有很多大文件（比如预编译的二进制文件），用 git-lfs 可以避免仓库体积爆炸。：编译缓存工具。第二次编译时，如果代码没变，直接从缓存里拿结果，能节省 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 分钟搞定（推荐）
如果你只是想快速上手，强烈建议使用预编译包，省时省力。
第一步：下载预编译包
从官方仓库下载预编译包：
：electron34-release（基于 Chromium 132）第二步：解压预编译包
# 解压预编译包unzip v34.6.3-20260105.1-release.zip# 进入目录cd libelectron
第三步：通过 DevEco Studio 打开项目
# 打开 ohos_hap 目录# 在 DevEco Studio 中选择 File → Open → 选择 ohos_hap 目录
第四步：运行项目
点击工具栏的运行按钮即可把 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 打开项目：
选择 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 的窗口，显示欢迎信息
第三步：运行项目
确保 libelectron/ohos_hap 项目已打开如果一切正常，你应该能在模拟器中看到欢迎信息：“欢迎使用 Electron on HarmonyOS!”
第三部分：常见问题与解决方案（重点来了）
3.1 模拟器白屏问题（GPU 加速渲染）
问题描述
运行到模拟器后，应用启动但显示白屏，无法正常渲染界面。这是鸿蒙模拟器的一个已知问题。
我当时盯着白屏看了两个小时，差点把电脑砸了。
根本原因
鸿蒙模拟器在某些配置下无法正确使用 GPU 加速渲染，导致 Chromium 的渲染引擎无法输出画面。这通常发生在：
虚拟机环境中运行模拟器（我在 VirtualBox 里跑 Ubuntu，然后跑鸿蒙模拟器，套娃了）方案一：禁用硬件加速（推荐用于开发调试）
重要提示：如果你使用的是预编译包，这个配置已经包含在内，无需额外操作。
如果你是从源码编译，需要在 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
问题：应用在模拟器上运行缓慢
解决方案：
第四部分：最佳实践
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)：使用 DevTools 调试渲染进程，使用 Chrome DevTools 调试主进程：申请开发者证书，在 DevEco Studio 中配置签名，生成签名的 HAP 包4.2 性能优化建议
1. 减少内存占用：
使用轻量级的 UI 框架（如 Preact 而不是 React）及时释放不需要的资源（比如关闭不用的窗口、清理缓存）2. 加快启动速度：
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 开发者社区相关工具
总结
Electron 鸿蒙开发虽然还处于探索阶段，但已经具备了基本的可行性。通过这篇文章，你应该能够：
✅ 快速搭建开发环境（至少不会像我一样踩那么多坑）关键要点回顾：
：需要 200GB+ 磁盘空间和 32GB+ 内存（别拿笔记本硬扛）：禁用 GPU 加速或在真机上测试（加 --disable-gpu 参数）：注释相关代码，等待官方适配（鸿蒙 SDK 里根本没有这个 API）希望这篇文章能帮你少走弯路。如果在搭建过程中遇到问题，欢迎在评论区反馈，我们一起解决。
10个月宝宝每天需要喝多少奶粉？
