把 Electron 桌面应用搬上鸿蒙 PC:OCS 桌面版 3.9.1 移植全记录
把 Electron 桌面应用搬上鸿蒙 PC:OCS 桌面版 3.9.1 移植全记录
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
适配开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_ocsdesktop
一个真实项目的移植手记:如何在不重写业务代码的前提下,让一个基于 Electron + Vue 的桌面工具在 HarmonyOS PC 上装起来、跑起来、用起来,以及这一路上撞到的 16 个坑。

0. 先说结论
如果只看结果,这次移植可以用四个数字概括:
| 指标 | 数值 |
|---|---|
| 业务代码改动 | 0 行(上游 ocs-desktop-src/ 的 .ts / .vue 源码一行未改) |
| 适配层代码 | 约 600 行(5 个 stub + 1 个引导层 + 6 个构建脚本 + 1 份打包配置) |
| 产物体积 | 223.9 MB(其中运行时库 187.8 MB) |
| 真机状态 | 安装成功、启动无崩溃、主界面完整渲染、本地服务正常监听 |

图 1:一模一样的界面,一模一样的文案。除了标题栏按钮变成鸿蒙样式,用户几乎察觉不到底下换了一套操作系统。
但"结论先行"往往会掩盖过程里的狼狈。真实情况是:这个项目里最贵的一次踩坑,把我整整两天时间烧在一个只有一行的崩溃日志上——Reason: SIGTRAP。而最后的修复方式,是把壳工程整个换掉重来。
所以这篇文章不打算写成"五步上手指南"。我想完整还原一套可复用的判断方法:面对一个既有桌面应用,怎样决定走哪条路、怎样划分改造层、怎样让每一步都可验证。
1. 先看清上游:它到底是个什么东西
1.1 上游画像
OCS 桌面版是一个面向在线课程平台的辅助工具,上游仓库 ocsjs/ocs-desktop,版本 3.9.1,MIT 协议。技术栈很典型:
- 主进程:TypeScript + Electron 43.8.0,负责窗口管理、本地 HTTP 服务、数据持久化、任务调度;
- 渲染进程:Vue 3 + Arco Design,多窗口路由;
- 构建:
electron-vite(Vite 包装了 Electron 的 main / preload / renderer 三入口约定); - 能力依赖:
keytar(系统密钥链)、electron-updater(自动更新)、auto-launch(开机自启)、系统托盘、内置 Chromium 下载解压、Playwright 驱动的浏览器自动化。
功能主干三块:浏览器多开(每个窗口独立 user-data-dir,实现同一网站多账号)、脚本注入(向浏览器页面注入自动化脚本)、脚本与配置管理(题库、答题策略、同步到各浏览器实例)。
前两块都重度依赖"能启动一个真正的 Chromium 进程并控制它"。
1.2 为什么这是移植里最难的一类应用
桌面应用移植的难度,不取决于代码行数,而取决于它对外部环境的假设有多深。按这个标准可以分三档:
| 档位 | 判定标准 | 典型例子 |
|---|---|---|
| T0 | 只依赖标准 UI 与文件 API,改编译目标即可跑 | 计算器、文本编辑器 |
| T1 | 依赖一套完整运行时(Qt / Electron / Python 解释器),需原生宿主承载 | 本文的 OCS、基于 Qt 的编辑器 |
| T2 | 依赖平台没有等价物的系统能力(进程创建、系统级钩子、特定驱动) | 需要 execv 起子进程、需要注入其他进程的工具 |
OCS 恰好卡在 T1 与 T2 的边界上:
- 界面、配置管理、本地服务是纯 T1 能力,只要 Electron 运行时能跑就能用;
- 浏览器多开与脚本注入需要
child_process.spawn起独立 Chromium 进程,而鸿蒙应用沙箱禁止exec——这一块是硬 T2。
这个判断决定了后面所有取舍:把 T1 部分做到完整可用,把 T2 部分明确降级并告知用户,而不是硬啃。
1.3 三条路线,为什么选了"最重"的那条
| 路线 | 做法 | 工作量 | 风险 |
|---|---|---|---|
| A. Electron 全量承载 | 用官方鸿蒙 Electron 运行时,原样加载业务产物 | 中 | 运行时版本受限,T2 能力无解 |
| B. ArkTS 重写 | 用 ArkUI 重写全部界面,能力用系统 API 重实现 | 极高 | 业务逻辑(题库、脚本引擎)几乎要重写 |
| C. 混合 | ArkUI 做壳,Web 组件承载部分页面 | 高 | 两套 UI 风格割裂,状态同步复杂 |
路线 B 看似"最鸿蒙",但对这个项目是灾难:业务逻辑大量依赖 Node 的 fs、http、crypto,ArkTS 侧没有等价物,重写等于重做一个产品,而且上游后续更新完全无法跟进。
路线 A 的代价是"承认一部分功能做不到",收益是"剩下的部分几乎零成本"。对一个 MIT 开源工具的社区移植来说,这个交换划算。
最终架构是一条清晰的三层结构:

2. 第一课:运行时与壳工程是配套件,不是可自由组合的零件
这一段是整个项目最贵的一课,值得单独成章。
2.1 症状:启动两秒,SIGTRAP
最早的方案很"合理":拿一份现成的鸿蒙 Electron 壳模板(entry 模块 + web_engine HAR),把官方 Release 里的 v40 运行时库丢进 libs/arm64-v8a/,再把业务产物部署进 resfile/resources/app/。
编译全绿,安装成功,aa start 之后进程起来——然后 2 秒内进程消失。
cppcrash 日志里只有一行有效信息:
Reason: SIGTRAP
没有 JS 异常,没有 ArkTS 报错,没有堆栈。SIGTRAP 在 Native 层通常意味着 CHECK / assert 失败,或 __builtin_trap()。
2.2 定位:用 addr2line 把栈挖出来
好在官方 Release 的 libelectron.so 未完全剥离符号。用 SDK 自带 llvm-addr2line 翻译崩溃栈,落在:
SetVulkanIcdAddress(...)
→ PathService::Get(501, &path) 失败
→ CHECK 失败
→ brk # 即 SIGTRAP
反汇编确认:它要取"运行时资源根目录",取不到就直接 brk——纯 Native 的硬失败,JS 层没有任何机会捕获。
再看工程里的 resfile/vulkan/icd.d/vk_swiftshader_icd.json:
{
"file_format_version": "1.0.0",
"ICD": {
"library_path": "/data/storage/el1/bundle/libs/arm64/libvk_swiftshader.so"
}
}
这个 .so 在 HAP 里根本不存在。旧模板约定的资源布局,与 v40 运行时对资源布局的期望已经不一致。
第二个证据更直接。用 llvm-strings 扫 v40 的 libadapter.so,发现 CommandLineAdapter.AppendSwitch 这类 NAPI 绑定已经消失——v40 改成命令行参数注入。而旧模板的 ArkTS 代码还在调它:
TypeError: e[t] is not a function
2.3 结论:先定运行时,再选模板
修复方式没有取巧空间:整份切换到官方 v40 模板。
- 模块从
entry重命名为electron(跟随官方模板命名); web_engine、account_quick_login保持 HAR 依赖关系不动;- Ability 体系(
EntryAbility/BrowserAbility/StatelessAbility/TaskManagerAbility/HideKeeperAbility/StatusBarEntryAbility)与运行时一一对应。
换完之后,同一批 .so 直接启动成功,代码一行没动。
这条经验对后续所有 Electron 应用迁移都成立:壳模板与运行时
.so是配套发布的产物,就像内核模块必须匹配内核版本。看到SIGTRAP且栈落在 Native 层CHECK,第一反应应该是"版本不配套",而不是去查业务代码。
3. 打包层:externalizeDepsPlugin 是 HAP 的头号杀手
运行时跑通之后,下一个问题立刻出现:应用起来了,但报 Cannot find module。
3.1 桌面端正确、HAP 内致命
上游 electron.vite.config.ts 用了 externalizeDepsPlugin:
import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
export default defineConfig({
main: {
plugins: [externalizeDepsPlugin()] // 所有 dependencies 全部外链
}
})
这在桌面端是最优解:node_modules 就在旁边,全部外链让产物只有 93 KB,构建飞快。
但在 HAP 里,应用目录是只读的打包资源,没有 node_modules。于是启动即崩:
Error: Cannot find module 'axios'
3.2 改法:只外链 electron
适配版配置(patches/electron.vite.ohos.config.ts)把策略整个反过来——除 electron 外全部内联:
import { defineConfig } from 'electron-vite';
import path from 'path';
const APP = __dirname; // packages/app
const WEB = path.resolve(APP, '../web');
const COMMON = path.resolve(APP, '../common');
const SHIM = path.resolve(APP, '../../../ohos-shim');
export default defineConfig({
main: {
resolve: { alias: commonAlias },
build: {
outDir: 'out/main',
lib: {
entry: {
index: path.resolve(APP, 'index.ts'),
script: path.resolve(APP, 'src/worker/entry.ts')
},
formats: ['cjs']
},
rollupOptions: {
external: ['electron'], // 只留 electron
output: {
entryFileNames: '[name].js',
banner: "process.env.OCS_OPENHARMONY = '1';" // 注入环境标记
}
},
minify: 'esbuild',
target: 'node18'
},
esbuild: { keepNames: true } // 保留类名,脚本引擎依赖
},
renderer: {
root: WEB,
build: {
outDir: path.resolve(APP, 'out/renderer'),
rollupOptions: { input: path.resolve(WEB, 'index.html') }
},
base: './' // 相对路径,HAP 内没有 http 根
}
});
三处改动,每处对应一个具体的 HAP 约束:
external只留electron:其余依赖全部打进 bundle。代价是体积从 93 KB 涨到 2.1 MB——对这个 223 MB 的包体是噪声。banner注入环境标记:业务层用process.env.OCS_OPENHARMONY判断平台,决定是否隐藏 T2 功能入口。base: './':渲染产物若带绝对路径/assets/xxx.js,在file://协议下直接 404,页面白屏。
3.3 把"体积"变成自检信号
体积变化是判断"依赖到底有没有打进去"最可靠的手段,比读日志快得多:
| 文件 | 上游基线 | OHOS 适配后 |
|---|---|---|
out/main/index.js | 93 KB | 2.1 MB(2172 KB) |
out/main/script.js | — | 3.5 MB(3591 KB) |
out/renderer/index.html | — | 6.5 KB |
于是 check.mjs 里写了这么一条断言:
console.log('=== 4. 依赖内联(体积信号)===');
const kb = Math.round(statSync(path.join(APP, 'out/main/index.js')).size / 1024);
kb > 500
? ok(`主进程 ${kb}KB(依赖已内联)`)
: no(`主进程仅 ${kb}KB(依赖可能未打包)`);
经验:用"可以量化的物理事实"做断言,比用"日志里没有报错"做断言可靠得多。日志会骗人,文件大小不会。
4. 降级层:五个 stub,不碰业务代码一行
T2 能力不能用,但业务代码里到处 import 它们。直接删代码,上游就再也合不上了。
做法是构建期别名替换——import 语法完全不变,打包时指向 no-op 实现:
const commonAlias = [
{ find: '@ocs-desktop/common/node', replacement: path.resolve(COMMON, 'node.ts') },
{ find: '@ocs-desktop/common/web', replacement: path.resolve(COMMON, 'web.ts') },
{ find: '@ocs-desktop/common', replacement: path.resolve(COMMON, 'index.ts') },
{ find: /^.*\/tasks\/updater$/, replacement: path.resolve(SHIM, 'updater.stub.ts') },
{ find: /^.*\/tasks\/auto\.launch$/,replacement: path.resolve(SHIM, 'auto-launch.stub.ts') },
{ find: /^.*\/tasks\/init\.chrome$/,replacement: path.resolve(SHIM, 'init-chrome.stub.ts') },
{ find: /^.*\/tray$/, replacement: path.resolve(SHIM, 'tray.stub.ts') },
{ find: /^keytar$/, replacement: path.resolve(SHIM, 'keytar.stub.ts') }
];
五个 stub 的语义,全部是让调用方走已有的降级分支,而不是简单返回空:
| stub | 替代能力 | 为什么这样实现 |
|---|---|---|
keytar.stub.ts | 系统密钥链(原生 .node) | getPassword 恒返回 null,业务侧本就写了「拿不到就全新生成主密钥」 |
tray.stub.ts | 系统托盘 | no-op,窗口关闭即退出(PC 形态下可接受) |
updater.stub.ts | electron-updater 自动更新 | no-op,更新交给应用市场 |
auto-launch.stub.ts | 开机自启 | no-op,鸿蒙侧需系统权限,普通应用无此能力 |
init-chrome.stub.ts | 内置 Chrome 下载解压 | no-op,鸿蒙侧不能解压可执行文件并 exec |
keytar 的 stub 最典型:
/**
* OHOS 适配:keytar 原生 addon(.node)不可在 HAP 内加载。
* crypto.ts 仅在「存量密钥升格」时动态 import 并 try/catch,
* 此处返回 null 让其走「跳过升格 → 全新生成主密钥」降级路径。
*/
export async function getPassword(_service: string, _account: string): Promise<null> {
return null;
}
export async function setPassword(_service: string, _account: string, _password: string): Promise<void> {}
export async function deletePassword(_service: string, _account: string): Promise<boolean> {
return false;
}
这段只有 10 行,但它是读了业务源码才写出来的:先确认上游对 keytar 只有一处动态 import 且包在 try/catch 里,再确认 null 会触发"生成新主密钥"分支,最后才敢返回 null。若上游是"必须读到密钥否则拒绝启动",这个 stub 就得换成"用系统密钥库重实现"。
方法论:stub 的返回值必须由调用方的降级路径决定,不能凭直觉。 判断依据是实际调用的符号与分支,不是
import语句长什么样。
5. 壳工程层:身份化、权限、PC 形态
5.1 身份化:一个容易漏的字段
应用身份集中在 AppScope/app.json5:
{
"app": {
"bundleName": "com.ocs.desktop",
"vendor": "ocs",
"versionCode": 3900100,
"versionName": "3.9.1",
"icon": "$media:app_icon",
"label": "$string:app_name",
"multiAppMode": {
"multiAppModeType": "multiInstance",
"maxCount": 1
}
}
}
versionCode 用固定编码,方便与上游语义化版本对齐:
versionCode = major × 1,000,000 + minor × 10,000 + patch × 100
3.9.1 → 3×1e6 + 9×1e4 + 1×1e2 = 3,900,100
身份化最容易漏的不是这里,而是快捷方式配置。 resources/base/profile/shortcuts_config.json 里有一套独立的 bundleName 字段,与 app.json5 完全不联动。只改主配置,桌面快捷方式会继续指向旧包名,表现为"点图标没反应"。
解法是把"残留检查"写进脚本,对所有 json / json5 / ets / ts 做一次文本扫描:
const hits = walk(HAP).filter((f) =>
/zettlr|Zettlr|com\.zettlr|墨匣/.test(readFileSync(f, 'utf-8'))
);
hits.length === 0
? ok('无身份残留')
: no(`身份残留 ${hits.length} 处: ${hits[0]}`);
这个检查在本次移植中真的抓到过残留——不在 app.json5,而在某个 string.json 的旧描述里。
5.2 权限:删掉的比加上的更关键
官方 v40 模板自带一长串受限权限(需 ACL 授权)。调试签名 profile 里没有这些授权,安装直接失败:
Install Failed: error: failed to install bundle.
code:9568289
error: install failed due to grant request permissions failed.
PermissionName: ohos.permission.READ_WRITE_DESKTOP_DIRECTORY
最终只保留 6 项:
| 模块 | 权限 | 必要性 |
|---|---|---|
web_engine | INTERNET、GET_NETWORK_INFO | 网课页面与接口服务 |
web_engine | MICROPHONE、CAMERA | 页面内媒体能力(用户授权制) |
electron | KEEP_BACKGROUND_RUNNING | 后台常驻任务流 |
electron | kernel.ALLOW_WRITABLE_CODE_MEMORY | V8 JIT 必需 |
被移除的十项都是 ACL 敏感项:READ_WRITE_DESKTOP_DIRECTORY、READ_WRITE_DOCUMENTS_DIRECTORY、READ_WRITE_DOWNLOAD_DIRECTORY、SYSTEM_FLOAT_WINDOW、PRIVACY_WINDOW、SET_WINDOW_TRANSPARENT、LOCK_WINDOW_CURSOR、PREPARE_APP_TERMINATE、FILE_ACCESS_PERSIST、DISTRIBUTED_DATASYNC。
两个细节必须说清楚。
第一,ALLOW_WRITABLE_CODE_MEMORY 千万不能顺手删。 它看起来是个"高危权限",但 V8 的 JIT 编译必须有可写可执行内存。删掉之后应用不会报权限错误,而是启动瞬间 SIGTRAP——和 §2 那个崩溃长得一模一样,极容易误判成版本问题。
第二,删权限不能靠"删报错那一行"。 正确姿势是从最小集合开始(INTERNET + GET_NETWORK_INFO),按功能逐个加回,每次装机验证。反过来"报一个删一个"会陷入反复装机的循环,因为一次安装只会报第一个失败的权限。
如果业务后续确实需要文件目录访问,正确做法是改用 picker 让用户显式选择,而不是把受限权限加回来。
5.3 PC 形态:把 PC 语义交给运行时
应用是给 PC 用的,但不需要在业务里写任何 PC 适配代码——这部分由运行时适配层承担。壳侧只需声明清楚:
{
"module": {
"name": "electron",
"type": "entry",
"deviceTypes": ["2in1", "tablet"],
"metadata": [
{
"name": "electron_exec_path_ohos",
"value": "/data/storage/el1/bundle/libs/arm64/electron"
}
],
"abilities": [{
"name": "EntryAbility",
"launchType": "specified",
"removeMissionAfterTerminate": true,
"continuable": true,
"skills": [{
"entities": ["entity.system.home", "entity.system.browsable"],
"actions": ["action.system.home", "ohos.want.action.viewData"],
"uris": [
{ "type": "application/pdf", "scheme": "file", "linkFeature": "FileOpen" },
{ "type": "text/html", "scheme": "file", "linkFeature": "FileOpen" }
]
}]
}]
}
}
三个声明各有含义:
deviceTypes: ["2in1", "tablet"]:2in1 即 PC 形态,决定系统按桌面窗口规则管理它;launchType: "specified"+removeMissionAfterTerminate:符合 PC 多窗口语义,重复启动复用同一实例,关窗即销毁任务;skills里的filescheme:让.pdf/.html双击时能出现在"打开方式"里,这是桌面应用的基本素养。
真机日志可以验证这些声明确实生效了:
A00000/WebEngine: LogMethodCall --> AppWindowAdapter#setUseNativeFrame(1,false)
A00000/WebEngine: LogMethodCall --> AppWindowAdapter#setWindowShadow(1,true)
A00000/WebEngine: LogMethodCall --> AppWindowAdapter#updateStyleData(1,"{\"colorMode\":0,...}")
A00000/WebEngine: LogMethodCall --> AppWindowAdapter#setTitle("OCS桌面版 - 首页",1)
原生边框、窗口阴影、跟随系统的深浅色、标题同步——全部由运行时逐条下发给系统窗口,业务层零参与。
6. 兼容层:白屏的真正原因是 safeStorage
6.1 症状:窗口起来了,内容是白的
壳工程换好之后,应用能启动了。进程树完整,标题栏也更新了,但内容区一片白。
日志给了两条关键线索:
[错误] 主密钥初始化失败 TypeError: wt.safeStorage.isAsyncEncryptionAvailable is not a function
[错误] 渲染进程数据解密失败(第 1 层),按空数据处理 Error: Unsupported state or unable to authenticate data
6.2 取证:运行时到底实现了哪些 API
用 llvm-strings 扫运行时 libelectron.so,确认 safeStorage 只导出了三个同步方法:
isEncryptionAvailable
encryptString
decryptString
没有 isAsyncEncryptionAvailable。上游按 Electron 43 写代码,这里跑的是 Electron 40.1.0 / Chromium 144,API 缺失导致:主密钥初始化失败 → 本地 store 全是空 → 渲染层拿不到任何数据 → 白屏。
这里有个容易被忽略的因果链:白屏不是渲染进程的问题。渲染进程只是忠实渲染了它拿到的空数据。如果去调渲染层(查 DOM、查 CSS、查路由),会一无所获。
6.3 修复:boot.js 引导层
修复原则是"不改业务 bundle"。在业务入口前加一层引导,补齐缺失的 API:
// 兼容层:ohos Electron 运行时的 safeStorage 未实现异步接口,业务侧需要补齐后再进入主流程
try {
const electron = require('electron');
const ss = electron && electron.safeStorage;
if (ss && typeof ss.isAsyncEncryptionAvailable !== 'function') {
const patch = (name, fn) => {
try {
Object.defineProperty(ss, name, { value: fn, configurable: true, writable: true, enumerable: false });
} catch (e) {
try {
ss[name] = fn;
} catch (_) {}
}
};
patch('isAsyncEncryptionAvailable', () => false);
patch('encryptStringAsync', async (s) => ss.encryptString(s));
patch('decryptStringAsync', async (b) => ss.decryptString(b));
}
} catch (e) {}
require('./out/main/index.js');
配套把运行时 package.json 的 main 指向它:
{
"name": "ocs-desktop-ohos",
"version": "3.9.1",
"main": "boot.js",
"dependencies": {}
}
这段代码有三个设计考虑:
typeof判断在前:运行时哪天补上异步接口,这段逻辑自动跳过,不需要回滚。Object.defineProperty优先:safeStorage是 Native 注入的对象,属性可能是只读的,直接赋值会静默失败;defineProperty失败才降级为赋值。isAsyncEncryptionAvailable返回false:这是关键决策——不是"假装异步可用",而是明确引导业务走同步分支。同步三件套运行时是完整实现的,返回false之后业务立刻回落到encryptString/decryptString,行为完全正确。
修复后的日志:
[信息] 生成新主密钥并存入 ocs.key
[信息] 初始化加密密钥 耗时: 80
[信息] OCS服务启动成功 => 15319
[信息] OCS启动程序 耗时: 826
界面完整渲染。
还有一个细节值得说明:修复后仍会看到一条
渲染进程数据解密失败(第 1 层),按空数据处理
这是旧密钥加密的历史数据解不开(新主密钥与旧运行时版本不匹配),业务按空数据处理后重新生成,属预期行为,不影响启动。如果不去区分"历史数据"和"新数据",会误以为修复失败。
另外这个引导层还暴露了一个流水线隐患,我在写这篇文章时顺手修了:部署脚本原本会 rm -rf 整个应用目录再重新拷产物,boot.js 是手写文件、不由构建产出,会被一起删掉,然后 main 被写回 out/main/index.js——白屏当场回归。修复方式是把清理范围收窄到 out/:
// 注意:只清理 out/ 产物目录。APP 根下的 boot.js 是 safeStorage 兼容引导层,
// 手写维护、不由构建产出,整目录删除会把它一起抹掉并导致白屏回归。
if (!existsSync(path.join(APP, 'boot.js'))) fail('兼容引导层 boot.js 缺失(应由仓库提供,勿删)');
rmSync(path.join(APP, 'out'), { recursive: true, force: true });
mkdirSync(path.join(APP, 'out', 'main'), { recursive: true });
mkdirSync(path.join(APP, 'out', 'renderer'), { recursive: true });
这类 bug 的可怕之处在于:它不在编译期、不在运行期,只在"某天有人重新跑了一次部署脚本"时爆发,而那时所有人都已经忘了
boot.js是手写的。
7. 流水线:四条命令,从源码到 HAP
整个工程的可复现性建立在四个脚本上,package.json 里串成一条链:
{
"scripts": {
"build": "node scripts/build.mjs",
"deploy": "node scripts/deploy.mjs",
"identity": "node scripts/identity.mjs",
"check": "node scripts/check.mjs",
"hap": "node scripts/build-hap.mjs"
}
}
7.1 build:打出 OHOS 版业务产物
把适配版 electron.vite.config.ts 覆盖到上游 packages/app,再执行 electron-vite 构建。关键点是不污染上游源码树——配置文件来自 patches/,每次构建前覆盖,构建后可还原。
7.2 deploy:产物 + 静态资源 + 环境标记
部署不只是 cp -r。除了把 out/ 拷进 resfile/resources/app/,还要补两类东西:
// 静态资源兜底:windowIconPath() 指向 ./public/...,HAP 内需存在
// 图标在 packages/app/public/;渲染期静态文件(hljs/js/loading)在 packages/web/public/
for (const base of [
path.join(ROOT, 'ocs-desktop-src/packages/app/public'),
path.join(ROOT, 'ocs-desktop-src/packages/web/public')
]) {
if (existsSync(base)) {
for (const item of readdirSync(base)) {
cpSync(path.join(base, item), path.join(APP, 'public', item), { recursive: true });
}
}
}
漏了 public/ 的表现是"界面能开,但图标 404、代码高亮样式丢失"——看起来像小毛病,排起来很费劲。
同时注入降级提示横幅,让用户知道哪些能力不可用(不改业务源码,部署后处理 HTML):
const inject = `<script>window.__OCS_OPENHARMONY__=true;window.OCS_OPENHARMONY=true;
(function(){var d=document;var b=d.createElement('div');
b.textContent='鸿蒙 PC 版:浏览器多开/自动化脚本执行暂不可用,脚本与配置管理可用';
b.style.cssText='position:fixed;top:0;left:0;right:0;z-index:99998;padding:8px 16px;font:14px system-ui;background:#ffd166;color:#332b00;text-align:center;';
function mount(){if(d.body){d.body.appendChild(b);}else{setTimeout(mount,50);}}mount();})();</script>`;
html = html.replace('</head>', inject + '</head>');
降级必须可见。一个功能不可用但界面假装可用,比直接报错更伤用户信任。
7.3 check:13 项自检,把"我以为"变成"已验证"
check.mjs 是最有价值的脚本,它把部署完整性、路径契约、依赖内联、身份残留、运行时库全部变成可执行断言:
console.log('=== 1. 部署文件齐全 ===');
for (const f of ['package.json', 'boot.js', 'out/main/index.js', 'out/main/script.js', 'out/renderer/index.html']) {
existsSync(path.join(APP, f)) ? ok(f) : no(f);
}
console.log('=== 2. 运行时 package.json ===');
const pkg = JSON.parse(readFileSync(path.join(APP, 'package.json'), 'utf-8'));
pkg.main === 'boot.js' ? ok('main = boot.js(safeStorage 兼容引导层)') : no('main 错误: ' + pkg.main);
Object.keys(pkg.dependencies || {}).length === 0 ? ok('dependencies = {}') : no('dependencies 非空');
console.log('=== 7. 运行时库 .so ===');
const soFiles = existsSync(libs) ? readdirSync(libs).filter((f) => f.endsWith('.so')) : [];
soFiles.length >= 3
? ok(`运行时 .so ${soFiles.length} 个(${soFiles.join(', ')})`)
: no('运行时 .so 缺失 — 需从官方 Release 拷贝到 electron/libs/arm64-v8a/');
最后跑出来:
=== 结果: 13 PASS / 0 FAIL
两个断言背后的真实教训:
dependencies必须为空:运行时看到非空依赖会尝试npm install,而 HAP 内既没有网络也没有写权限,直接卡死;.so必须 ≥ 3:这条断言在仓库刚克隆、还没放运行时库时会 FAIL,这是正确行为——它提醒你"现在这个工程打不出能跑的应用"。
7.4 hap:绕开 Windows 路径里的空格
最后一步是调 DevEco 的 hvigorw。这里有个纯 Windows 的问题:C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat 含空格,shell: true 时被拆词成两段,报"找不到命令"。
解法是绕开 .bat,直接用 DevEco 内置 Node 跑 hvigorw.js,并显式传环境变量:
const nodeBin = ['tools/node/node.exe', 'tools/node/bin/node'].map((p) => path.join(deveco, p)).find(existsSync);
const hvigorW = path.join(deveco, 'tools/hvigor/bin/hvigorw.js');
const sdk = path.join(deveco, 'sdk');
function run(args) {
console.log('[build-hap]', path.basename(nodeBin), 'hvigorw.js', args.join(' '));
const r = spawnSync(nodeBin, [hvigorW, ...args], {
cwd: HAP,
shell: false, // 关键:不经 shell,避免拆词
encoding: 'utf-8',
env: { ...process.env, DEVECO_SDK_HOME: sdk, JAVA_HOME: path.join(deveco, 'jbr') }
});
if (r.stdout) console.log(r.stdout.slice(-6000));
if (r.stderr) console.error(r.stderr.slice(-3000));
return r.status === 0;
}
run(['--stop-daemon']); // 先停守护进程,避免旧产物缓存
const ok = run([
'assembleHap', '--mode', 'module',
'-p', 'product=default',
'-p', 'module=electron@default',
'-p', 'buildMode=debug',
'--no-daemon'
]);
JAVA_HOME 指向 DevEco 自带的 jbr,是因为签名环节的 app_packing_tool.jar 需要 Java——系统没装 JDK 时,报错是 spawn java ENOENT,而它会被淹没在几百行构建日志里。
7.5 完整链路
cd ohos_ocsdesktop
node scripts/build.mjs # 1. electron-vite 构建 OHOS 版产物
node scripts/deploy.mjs # 2. 产物 + public/ + 环境标记 → resfile
node scripts/check.mjs # 3. 13 项自检,必须 0 FAIL
node scripts/build-hap.mjs # 4. hvigor assembleHap → signed HAP
产物:ohos_hap/electron/build/default/outputs/default/electron-default-signed.hap,223.9 MB。
体积构成值得单独看一眼,它解释了为什么"Electron 应用上鸿蒙"包体一定小不了:
| 组成 | 体积 |
|---|---|
libelectron.so | 178.3 MB |
libadapter.so | 7.4 MB |
libffmpeg.so | 2.1 MB |
业务产物 + 渲染资源 + 运行时资源(icudtl.dat、resources.pak、snapshot_blob.bin 等) | 约 36 MB |
8. 真机验证:怎么确认"真的活了"
编译通过不等于跑得起来,跑起来不等于能用。我按四层递进验证。
8.1 第一层:进程树
hdc shell aa force-stop com.ocs.desktop
hdc shell aa start -a EntryAbility -b com.ocs.desktop -m electron
hdc shell "ps -ef | grep ocs.desktop | grep -v grep"
四类进程齐全,说明 Chromium 多进程架构真正成型了:
com.ocs.desktop # 主进程(Node + Electron)
com.ocs.desktop:GPU # GPU 进程
com.ocs.desktop:Renderer # 渲染进程
com.ocs.desktop:NetworkService # 网络进程
这一步的判据非常明确:只有主进程 = 壳起来了但引擎没起来;四类齐全 = 引擎启动完成。如果只有主进程,问题一定在 resfile 资源布局或运行时库,不在业务代码。
8.2 第二层:业务日志
hdc shell "hilog -x | grep 'ocs.desktop/Electron' | tail -40"
[信息] 初始化加密密钥 耗时: 80
[信息] 生成新主密钥并存入 ocs.key
[信息] OCS服务启动成功 => 15319
[信息] OCS启动程序 耗时: 826
15319 这个端口号很关键——它说明应用内的 HTTP 服务真的把监听建起来了,不是"界面画出来就完事"。
8.3 第三层:界面与路径

图 2:浏览器列表页。布局、卡片、Tab、弹窗、滚动条全部正常,说明渲染层资源加载完整。

图 3:脚本配置页。多级折叠面板、下拉框、开关、按钮——Vue 交互链路是通的。

图 4:脚本列表与搜索弹窗。Tab 切换、输入框、空态占位都正常。
这三张图证明的是同一件事:渲染层的资源加载与交互事件链在沙箱内是完整可用的。 Electron 应用白屏的常见原因(绝对路径、缺 public/、preload 未加载)在这里都不存在。
8.4 第四层:数据落盘

图 5:开发者设置页。注意「软件路径」三行——它们不是硬编码,而是运行时 app.getPath() 在鸿蒙沙箱内的真实返回值。
浏览器缓存 /data/storage/el2/base/files/UserDataDirs
文件下载 /data/storage/el2/base/files/downloads
软件存储 /data/storage/el2/base/files
这张图是整个适配最有力的证据:Electron 的 app.getPath() 契约在鸿蒙侧被完整映射到了应用沙箱。业务代码调 getPath('userData')、getPath('downloads') 拿到的都是合法可写路径,一行都不用改。
反过来,如果这里显示的是 Windows 风格的 C:\Users\...,说明运行时没有正确注入路径适配,必然伴随写盘失败。
8.5 验收清单
| # | 检查项 | 判据 | 结果 |
|---|---|---|---|
| 1 | 上游基线构建 | out/main/index.js ≈ 93 KB | 通过 |
| 2 | OHOS 全量 bundle | out/main/index.js 2172 KB | 通过 |
| 3 | 部署自检 | check.mjs 13 PASS / 0 FAIL | 通过 |
| 4 | 身份残留 | 全工程 grep 为 0 | 通过 |
| 5 | HAP 构建 | assembleHap 全绿,223.9 MB | 通过 |
| 6 | 安装 | hdc install -r 成功,无 9568289 | 通过 |
| 7 | 启动 | 进程树四类齐全,无 cppcrash | 通过 |
| 8 | 主界面渲染 | 无白屏,弹窗/导航/卡片完整 | 通过 |
| 9 | 本地服务 | 日志 OCS服务启动成功 => 15319 | 通过 |
| 10 | 加密与持久化 | 日志 生成新主密钥并存入 ocs.key | 通过 |
| 11 | 窗口标题 | setTitle("OCS桌面版 - 首页") | 通过 |
| 12 | 沙箱路径 | app.getPath() 返回 el2 路径 | 通过 |
9. 边界:哪些做不到,以及为什么
移植文章最容易失真的一节,是把做不到的东西含糊过去。这里逐条讲清楚。
9.1 T2 能力清单
| 能力 | 鸿蒙侧约束 | 处理方式 |
|---|---|---|
| 浏览器多开(起独立 Chromium) | 沙箱禁止 exec,filesDir 为 noexec | init-chrome stub,界面明示不可用 |
| 脚本注入到外部浏览器 | 依赖上一条 | 同上 |
| 系统密钥链 | 无 keytar 等价原生 addon | stub 返回 null,走新主密钥分支 |
| 系统托盘 | PC 形态下无托盘区 | no-op,关窗退出 |
| 开机自启 | 需系统级权限 | no-op |
| 自动更新 | 无 electron-updater 通道 | no-op,更新交市场 |
| Playwright 自动化 | 依赖起子进程 + 下载浏览器 | 不可用 |
9.2 界面文案尚未跟上降级事实

图 6:通用设置页。「开机自启」「浏览器路径:内置谷歌浏览器(Chrome For Test v137)」等选项沿用了上游默认文案,在鸿蒙侧对应的能力已被 stub 为 no-op。
这是一个诚实但未完成的状态:功能上已经正确降级(不会崩、不会卡、不会误报成功),但 UI 文案仍是上游原文。用户看到"内置谷歌浏览器 v137"会以为真的能用。
正确的做法是把这些选项在鸿蒙侧置灰并加一句说明,这属于纯 UI 工作,已列入待办。之所以不急着做,是因为先让核心链路可用,再逐步打磨提示文案,比反过来更有效率。
9.3 一个已知的 API 缺口
真机日志里偶发:
remote 模块错误 TypeError: e[t] is not a function
渲染端调用了某个主进程未暴露的 API。因为被 try/catch 包住,不影响主界面使用,但对应功能点击时会无响应。
定位方法是在调用点打 console.trace() 抓调用名,再逐条补齐——这是运行时 API 覆盖度问题,不是移植方案问题。
9.4 二期方向
- 应用内
WebContentsView+executeJavaScript替代 Playwright,把"脚本执行"能力救回一部分; - 运行时升级到与上游同 major(Electron 43),回归本套兼容层;
- 把 T2 降级项做进设置页开关,让用户自主选择;
- 给
ohos_hap补单元测试,把check.mjs与 hvigor 串成 CI 流水线。
10. QA:十二个被问得最多的问题
Q1:为什么不直接把 Electron 源码在鸿蒙上重新编译一份?
因为 Electron 不是"一个应用",而是"Chromium + Node + 一整套平台适配层"。官方已经为鸿蒙维护了运行时(含 libadapter.so 这类窗口/输入法/文件系统桥接),自己编一遍等于重做一个平台移植项目,工作量以人年计。正确做法是用官方运行时,只做壳与业务的对接。
Q2:运行时 .so 从哪里取?为什么必须版本对齐?
从 OpenHarmony Electron 官方 Release 取(本项目用的 v40.0.1.20261028.2,解压后 libelectron.so 178.3 MB / libadapter.so 7.4 MB / libffmpeg.so 2.1 MB)。必须对齐的原因见 §2:壳模板里调用的 NAPI 名字、资源目录约定都会随版本变,混用表现为 SIGTRAP 或 xxx is not a function。任何声称"补齐运行时库"的第三方包,务必核对它声明的 Electron 版本与文件体积——我核对过一个 npm 包,整包 66 MB,而官方单个 .so 就 177 MB,直接弃用。
Q3:为什么 Electron 能跑,但我用 child_process.spawn 起子进程就不行?
Electron 运行时是原生宿主内的进程内引擎,它不需要 exec;而 spawn 需要内核允许创建进程并执行可执行文件,鸿蒙应用沙箱禁止这条路径(应用私有目录也是 noexec)。所以"运行时能跑"和"能起子进程"是两件独立的事,别混为一谈。
Q4:白屏一般先查什么?
按这个顺序,命中率最高:
- 主进程日志里第一条
[错误](主进程初始化中断导致的"空数据白屏"最常见); - 渲染层
index.html里的资源路径是不是绝对路径(file://下 404); resfile/resources/app/package.json的main指向的文件是否存在;public/静态资源是否部署(图标、样式 404 不致命,但preload缺失致命)。
Q5:externalizeDepsPlugin 一定要关吗?关了有什么代价?
HAP 内没有 node_modules,必须关。代价只有体积(93 KB → 2.1 MB)和构建时间(本机从约 8 秒到约 25 秒)。对一个 223 MB 的包体,这两项都可忽略。唯一需要注意的是原生模块——.node 文件不能 bundle,必须 stub 掉(见 §4)。
Q6:权限删多了会不会功能异常?
会,而且症状往往不像权限问题。典型是删掉 kernel.ALLOW_WRITABLE_CODE_MEMORY 后启动瞬间 SIGTRAP,日志里没有任何"权限"字样。判断方法:把权限表临时恢复成模板原样,如果应用能起来,就是权限问题——但会装不上,所以更实际的做法是先查该权限是否被 ACL 保护、运行时是否对它硬依赖。
Q7:223.9 MB 的包体有办法减吗?
有,但空间有限:业务产物 + 渲染资源约 36 MB,剩下的 188 MB 全是运行时。能做的只有:裁掉用不到的 locale/ICU 数据(有风险)、按需分发(resources.pak 与 icudtl.dat 是运行时必需)。在这个架构下,200 MB 级别是合理预期,不要承诺"轻量"。
Q8:换包名之后签名总是失败怎么办?
签名 profile 与 bundleName 绑定,换名必须重新签名。DevEco 里 File > Project Structure > Signing Configs 勾选自动签名,选目标模块后让它重新生成一次即可。另外注意:自动签名只写 app.signingConfigs,不会自动往 app.products[0] 里加 "signingConfig": "default"——漏这一行,SignHap 不执行,产物仍是 unsigned.hap,安装报 9568320 no signature file。
Q9:脚本注入能力还能救吗?
部分可以。路线是放弃"起外部 Chromium",改为应用内 WebContentsView 加载目标页面 + executeJavaScript 注入。代价是:无法用真实的浏览器扩展环境、无法多账号隔离(除非每账号一个 View + 独立 session),且目标站点可能检测自动化特征。属于"能跑通一部分脚本"而不是"完全等价"。
Q10:这套方案能上应用市场吗?
技术上满足(无受限权限、无 exec、包体 200 MB 级在 PC 应用里可接受),但要注意两点:一是 T2 能力缺失必须在商店描述里写清楚,否则容易被判"功能异常";二是 READ_WRITE_*_DIRECTORY 这类权限一律不能用,文件访问必须走 picker。
Q11:怎么判断问题出在壳、运行时还是业务?
按这个分层法,几分钟就能定位:
应用装不上 → 壳:签名 / 权限 / bundleName
装上但起不来 → 运行时:.so 版本 / 签名材料 / JIT 权限
起来了只有主进程 → 运行时:resfile 资源布局
四类进程齐全但白屏 → 业务:入口文件 / 路径 / API 兼容层
界面正常但功能报错 → 业务:具体 API 缺失,看日志逐条补
Q12:这套方法能复用到别的 Electron 应用吗?
能,而且大部分可以照抄。可直接复用的部分:四层改造结构(打包层 / 降级层 / 壳工程层 / 兼容层)、五个通用 stub、check.mjs 的自检思路、build-hap.mjs 的绕空格写法。需要按项目重写的只有:业务特有的 API 兼容层、stub 的返回值语义、身份化配置。
11. 写在最后
回头看,这次移植真正花时间的不是写代码,而是建立判断力:
- 判断这个功能属于 T1 还是 T2,决定"做"还是"降级";
- 判断一个报错属于壳、运行时还是业务,决定去翻哪一层日志;
- 判断一次"验证通过"是真的通过,还是日志恰好没输出。
如果只让我留三条经验:
- 版本对齐优先于一切。壳模板和运行时
.so是配套件,SIGTRAP先怀疑版本,别怀疑业务。 - 让每个判断都有可执行的验证。依赖有没有内联看体积,路径对不对看
app.getPath()的返回值,资源全不全看进程树。能被量化的东西不要靠感觉。 - 降级要显式、要可见、要诚实。做不到的功能宁可置灰加说明,也不要留一个"点了没反应"的按钮。
业务代码零改动、适配层约 600 行、223.9 MB 包体、13 项自检全绿——这就是把 Electron 应用搬上鸿蒙 PC 的全部成本。
更多推荐



所有评论(0)