把 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:OCS 桌面版在鸿蒙 PC 上首次启动

图 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 约束:

  1. external 只留 electron:其余依赖全部打进 bundle。代价是体积从 93 KB 涨到 2.1 MB——对这个 223 MB 的包体是噪声。
  2. banner 注入环境标记:业务层用 process.env.OCS_OPENHARMONY 判断平台,决定是否隐藏 T2 功能入口。
  3. base: './':渲染产物若带绝对路径 /assets/xxx.js,在 file:// 协议下直接 404,页面白屏。

3.3 把"体积"变成自检信号

体积变化是判断"依赖到底有没有打进去"最可靠的手段,比读日志快得多:

文件上游基线OHOS 适配后
out/main/index.js93 KB2.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.tselectron-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_engineINTERNET、GET_NETWORK_INFO网课页面与接口服务
web_engineMICROPHONE、CAMERA页面内媒体能力(用户授权制)
electronKEEP_BACKGROUND_RUNNING后台常驻任务流
electronkernel.ALLOW_WRITABLE_CODE_MEMORYV8 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 里的 file scheme:让 .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": {}
}

这段代码有三个设计考虑:

  1. typeof 判断在前:运行时哪天补上异步接口,这段逻辑自动跳过,不需要回滚。
  2. Object.defineProperty 优先:safeStorage 是 Native 注入的对象,属性可能是只读的,直接赋值会静默失败;defineProperty 失败才降级为赋值。
  3. 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.so178.3 MB
libadapter.so7.4 MB
libffmpeg.so2.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:浏览器列表页与使用教程弹窗,Vue 组件与 Arco Design 样式完整

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

图 3:OCS 脚本配置页,题库配置与全局设置

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

图 4:脚本列表与网络脚本搜索弹窗

图 4:脚本列表与搜索弹窗。Tab 切换、输入框、空态占位都正常。

这三张图证明的是同一件事:渲染层的资源加载与交互事件链在沙箱内是完整可用的。 Electron 应用白屏的常见原因(绝对路径、缺 public/、preload 未加载)在这里都不存在。

8.4 第四层:数据落盘

图 5:软件设置 - 开发者页,本地服务端口 15319 与真实沙箱路径

图 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通过
2OHOS 全量 bundleout/main/index.js 2172 KB通过
3部署自检check.mjs 13 PASS / 0 FAIL通过
4身份残留全工程 grep 为 0通过
5HAP 构建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 为 noexecinit-chrome stub,界面明示不可用
脚本注入到外部浏览器依赖上一条同上
系统密钥链无 keytar 等价原生 addonstub 返回 null,走新主密钥分支
系统托盘PC 形态下无托盘区no-op,关窗退出
开机自启需系统级权限no-op
自动更新无 electron-updater 通道no-op,更新交市场
Playwright 自动化依赖起子进程 + 下载浏览器不可用

9.2 界面文案尚未跟上降级事实

图 6:通用设置页,部分上游选项在鸿蒙侧已降级为 no-op

图 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 二期方向

  1. 应用内 WebContentsView + executeJavaScript 替代 Playwright,把"脚本执行"能力救回一部分;
  2. 运行时升级到与上游同 major(Electron 43),回归本套兼容层;
  3. 把 T2 降级项做进设置页开关,让用户自主选择;
  4. 给 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:白屏一般先查什么?

按这个顺序,命中率最高:

  1. 主进程日志里第一条 [错误](主进程初始化中断导致的"空数据白屏"最常见);
  2. 渲染层 index.html 里的资源路径是不是绝对路径(file:// 下 404);
  3. resfile/resources/app/package.json 的 main 指向的文件是否存在;
  4. 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,决定"做"还是"降级";
  • 判断一个报错属于壳、运行时还是业务,决定去翻哪一层日志;
  • 判断一次"验证通过"是真的通过,还是日志恰好没输出。

如果只让我留三条经验:

  1. 版本对齐优先于一切。壳模板和运行时 .so 是配套件,SIGTRAP 先怀疑版本,别怀疑业务。
  2. 让每个判断都有可执行的验证。依赖有没有内联看体积,路径对不对看 app.getPath() 的返回值,资源全不全看进程树。能被量化的东西不要靠感觉。
  3. 降级要显式、要可见、要诚实。做不到的功能宁可置灰加说明,也不要留一个"点了没反应"的按钮。

业务代码零改动、适配层约 600 行、223.9 MB 包体、13 项自检全绿——这就是把 Electron 应用搬上鸿蒙 PC 的全部成本。

Logo

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

更多推荐