@hmos-library-adapter/fast 0.0.17-beta.1 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/electron/guides/migration-guide.md

@@ -0,0 +1,777 @@
+# Electron 开发与鸿蒙化迁移指南
+
+---
+
+## 一、macOS 平台：Electron 开发全流程
+
+### 1. 项目初始化
+
+```bash
+mkdir my-electron-app && cd my-electron-app
+npm init -y
+npm install --save-dev electron
+```
+
+最小项目结构：
+
+```
+my-electron-app/
+├── package.json          # 项目元信息、入口、脚本、构建配置
+├── main.js               # 主进程入口
+├── preload.js            # 预加载脚本（安全桥接）
+└── index.html            # 渲染进程页面
+```
+
+`package.json` 关键字段：
+
+```json
+{
+  "name": "my-electron-app",
+  "version": "1.0.0",
+  "main": "main.js",
+  "scripts": {
+    "start": "electron .",
+    "build": "electron-builder"
+  },
+  "devDependencies": {
+    "electron": "^39.0.0",
+    "electron-builder": "^26.0.0"
+  }
+}
+```
+
+**`main` 字段是 Electron 的入口标识**——当执行 `electron .` 时，Electron 二进制读取当前目录 `package.json` 的 `main` 字段，将其指定的 JS 文件作为主进程执行。
+
+### 2. 开发调试
+
+#### 2.1 启动原理
+
+```bash
+npm start  →  electron .  →  Electron 二进制启动
+                                ├── 读取 package.json → 找到 main.js
+                                ├── 以 Node.js 运行 main.js（主进程）
+                                └── main.js 中 new BrowserWindow → 加载 index.html（渲染进程）
+```
+
+**多进程模型**：
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        主进程 (Main Process)                  │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  Node.js 环境                                           │  │
+│  │  - app, BrowserWindow, dialog, shell, clipboard 等     │  │
+│  │  - fs, os, path 等 Node.js 内置模块                     │  │
+│  │  - 完整的系统访问权限                                    │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                          ↕ IPC 通信                           │
+├──────────────────────────────────────────────────────────────┤
+│                      渲染进程 (Renderer Process)              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  Chromium 环境                                          │  │
+│  │  - HTML/CSS/JS                                          │  │
+│  │  - DOM API、Web API                                     │  │
+│  │  - 默认无 Node.js 访问权限（安全隔离）                    │  │
+│  └────────────────────────────────────────────────────────┘  │
+├──────────────────────────────────────────────────────────────┤
+│                      GPU 进程                                 │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  Chromium GPU 进程                                      │  │
+│  │  - 硬件加速渲染                                         │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+#### 2.2 DevTools 调试
+
+- **渲染进程**：`BrowserWindow` 中自动支持 Chrome DevTools（`Cmd+Option+I`）
+- **主进程**：`electron --inspect=5858 .` 启动后，用 Chrome 访问 `chrome://inspect` 连接调试
+- **VSCode 调试**：在 `.vscode/launch.json` 中配置：
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Electron Main",
+  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
+  "program": "${workspaceFolder}/main.js"
+}
+```
+
+#### 2.3 热重载
+
+- `electron-reload`：监听文件变化自动重启
+- `webpack-dev-server` + `HMR`：前端页面热更新，主进程仍需手动重启
+
+### 3. 安全架构
+
+#### 3.1 三重隔离防线
+
+```js
+// main.js
+const win = new BrowserWindow({
+  webPreferences: {
+    preload: path.join(__dirname, 'preload.js'),  // 防线1：预加载脚本
+    contextIsolation: true,                        // 防线2：上下文隔离
+    nodeIntegration: false,                        // 防线3：禁用 Node.js
+    sandbox: false,                                // 仅在需要 preload 时可设 false
+  },
+})
+```
+
+**各字段含义**：
+
+| 配置项 | 作用 | 推荐值 |
+|---|---|---|
+| `contextIsolation` | 主进程与渲染进程的 JS 上下文完全隔离，防止渲染进程修改主进程对象 | `true` |
+| `nodeIntegration` | 渲染进程是否可直接使用 `require('fs')` 等 Node.js API | `false` |
+| `sandbox` | 渲染进程是否运行在 OS 沙箱中（限制文件系统、网络等） | `true`（如需 preload 则 `false`） |
+| `preload` | 在渲染进程页面加载前执行的白名单脚本，可安全暴露有限 API | 必须配合 `contextIsolation` |
+
+#### 3.2 preload 脚本模式
+
+```js
+// preload.js（正确方式 —— 最小权限暴露）
+const { contextBridge, ipcRenderer } = require('electron')
+
+contextBridge.exposeInMainWorld('api', {
+  readFile: (path) => ipcRenderer.invoke('fs:readFile', path),
+  writeFile: (path, content) => ipcRenderer.invoke('fs:writeFile', { path, content }),
+})
+
+// ❌ 错误方式 —— 暴露整个 ipcRenderer
+// contextBridge.exposeInMainWorld('ipc', ipcRenderer)
+```
+
+#### 3.3 IPC 通信模式
+
+```
+渲染进程 (index.html)           主进程 (main.js)
+       │                              │
+       │  ipcRenderer.invoke()        │  ipcMain.handle()
+       │ ───────────────────────────> │
+       │          Promise             │
+       │ <─────────────────────────── │
+       │                              │
+       │  ipcRenderer.send()          │  ipcMain.on()
+       │ ───────────────────────────> │  （单向，无返回值）
+       │                              │
+       │  ipcRenderer.on()            │  BrowserWindow.webContents.send()
+       │ <─────────────────────────── │  （主进程主动推送）
+```
+
+#### 3.4 Content Security Policy (CSP)
+
+CSP 是渲染进程的额外安全层，控制页面可加载的资源来源：
+
+```html
+<meta http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
+```
+
+**macOS 注意事项**：
+
+- Electron 用 `loadFile()` 加载页面时使用 `file://` 协议
+- Chromium 对 `file://` 协议下的 CSP `script-src 'self'` 处理有已知 bug，可能阻止所有脚本执行
+- 如果遇到脚本完全不响应的情况，可尝试移除 CSP meta 标签，或添加 `'unsafe-inline'`
+- `contextIsolation` + `nodeIntegration: false` + `contextBridge` 已提供足够的安全隔离
+
+### 4. 打包构建
+
+#### 4.1 electron-builder 配置
+
+```json
+// package.json
+{
+  "build": {
+    "appId": "com.example.myapp",
+    "productName": "MyApp",
+    "directories": {
+      "output": "dist"
+    },
+    "files": [
+      "main.js",
+      "preload.js",
+      "index.html",
+      "node_modules/**/*"
+    ],
+    "mac": {
+      "target": ["dmg", "zip"],
+      "category": "public.app-category.utilities"
+    },
+    "win": {
+      "target": ["nsis"]
+    },
+    "linux": {
+      "target": ["AppImage", "deb"]
+    }
+  }
+}
+```
+
+#### 4.2 asar 打包原理
+
+**默认 `asar: true`**，electron-builder 会将应用代码打包为 `app.asar` 单文件归档：
+
+```
+HelloElectron.app/
+└── Contents/
+    └── Resources/
+        ├── electron.asar          ← Electron 引擎内置资源
+        └── app.asar               ← 你的应用代码（归档文件）
+            ├── /main.js
+            ├── /preload.js
+            ├── /index.html
+            ├── /package.json
+            └── /node_modules/...
+```
+
+**asar 本质**：
+
+- 类似 tar 的归档格式，但支持随机读取（不需要解压整个文件）
+- Node.js 的 `fs.readFileSync()` 能直接从 asar 中读取，Electron 内部做了路径拦截
+- `require()` 也能正常从 asar 中的 `node_modules` 加载模块
+- 不是加密，只是归档——用户可用 `asar extract` 解包查看内容
+
+**何时需要 `asar: false`**：
+
+- 某些 native addon（.node文件）无法从 asar 中直接加载
+- 需要用 `asarUnpack` 指定不解压的文件，或直接关闭 asar
+
+#### 4.3 打包产物
+
+```
+dist/
+├── MyApp-1.0.0-arm64-mac.zip         ← 压缩包分发
+├── MyApp-1.0.0-arm64-mac.zip.blockmap ← 增量更新用
+├── MyApp-1.0.0-arm64.dmg             ← macOS 安装镜像
+├── MyApp-1.0.0-arm64.dmg.blockmap
+└── mac-arm64/
+    └── MyApp.app/                     ← macOS 应用包
+        └── Contents/
+            ├── MacOS/
+            │   └── MyApp              ← 可执行文件（Electron 二进制改名）
+            ├── Frameworks/
+            │   ├── Electron Framework.framework/  ← Chromium + Node.js
+            │   └── Helper (Renderer).app/         ← 渲染进程
+            └── Resources/
+                ├── app.asar           ← 你的应用代码
+                └── electron.icns      ← 应用图标
+```
+
+**包体大小**：约 100MB+，因为包含了完整的 Chromium 和 Node.js 运行时。
+
+---
+
+## 二、鸿蒙平台：Electron 开发全流程
+
+### 1. 背景与原理
+
+鸿蒙版 Electron **不是**用 ArkTS/JS 重写 Electron，而是将 Electron 的 C++ 源码（Chromium + Node.js）编译为鸿蒙的原生动态库（`.so`），通过系统 API 提供渲染表面和平台适配：
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        鸿蒙 Electron 应用                        │
+│                                                                 │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │                   electron (HAP 入口模块)                  │  │
+│  │  ┌─────────────────┐  ┌────────────────────────────────┐  │  │
+│  │  │  EntryAbility   │  │  BrowserAbility                │  │  │
+│  │  │  StatelessAbility│  │  BrowserEmbeddedAbility (Ext)  │  │  │
+│  │  │    ↓ extends     │  │    ↓ extends                   │  │  │
+│  │  │    WebAbility    │  │    WebEmbeddedAbility          │  │  │
+│  │  └─────────────────┘  └────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                          ↓ imports                               │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │                  web_engine (HAR 适配层库)                  │  │
+│  │  ┌──────────────┐  ┌───────────────┐  ┌────────────────┐  │  │
+│  │  │  Components  │  │  Adapters     │  │  JS Bindings   │  │  │
+│  │  │  WebWindow   │  │  AppWindow    │  │  37 个适配器    │  │  │
+│  │  │  WebSubWin   │  │  FileManager  │  │  Bind.bind()   │  │  │
+│  │  │  WebEmbWin   │  │  FilePicker   │  │    ↓           │  │  │
+│  │  │  WebWinNode  │  │  Dialog       │  │  bindFunction  │  │  │
+│  │  │  MessageBox  │  │  Display      │  │    ↓           │  │  │
+│  │  │    ↓         │  │  Notification │  │  NativeContext │  │  │
+│  │  │  XComponent  │  │  DragDrop     │  │  .JSBind       │  │  │
+│  │  │  libraryname │  │  Permission   │  │  .bindFunction │  │  │
+│  │  │  = "adapter" │  │  Process      │  │                │  │  │
+│  │  └──────────────┘  └───────────────┘  └────────────────┘  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                          ↓ N-API / XComponent                    │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │                    Native Libraries (.so)                   │  │
+│  │  ┌─────────────────┐ ┌────────────────┐ ┌──────────────┐  │  │
+│  │  │  libadapter.so  │ │ libelectron.so │ │  libffmpeg.so│  │  │
+│  │  │  getNativeContext│ │  Chromium C++  │ │  媒体编解码  │  │  │
+│  │  │  JSBind         │ │  Node.js C++   │ │              │  │  │
+│  │  │  XComponent CB  │ │  Electron C++  │ │              │  │  │
+│  │  └─────────────────┘ └────────────────┘ └──────────────┘  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### 1.1 核心适配机制
+
+**XComponent 渲染面**：鸿蒙系统中，Electron 的 Chromium 渲染需要图形输出表面。`XComponent` 组件提供 `SURFACE` 类型，通过 `libraryname: "adapter"` 绑定到 `libadapter.so`，后者接收 surface ID 并传递给 Chromium 的 Ozone 后端进行渲染：
+
+```ets
+// WebWindow.ets (简化)
+xComponent.initialize({
+  id: this.config.moduleName,
+  type: XComponentType.SURFACE,
+  controller: this.xComponentController,
+  libraryname: "adapter"  // ← 绑定 libadapter.so
+})
+.onLoad(() => {
+  // 设置窗口初始大小
+  this.setDefaultBounds()
+  // 启动 Electron 浏览器进程
+  let vec_args = CommandLineAdapter.getInstance().getArgs()
+  this.config.nativeContext.runBrowser(vec_args)
+})
+```
+
+**JSBinding 双向桥**：这是 C++ 和 ArkTS 之间的核心通信机制，实现双向调用：
+
+```
+C++ (libelectron.so)                        ArkTS (web_engine HAR)
+      │                                            │
+      │  调用已注册的函数名                          │  JsBindingUtils.bindFunction()
+      │  "AppWindow.CreateWindow"  ──────────>     │    注册 ArkTS 函数
+      │                                            │
+      │  NativeContext                              │
+      │  .runBrowser(vec_args)  <──────────        │    ArkTS → C++ 方向
+      │  .ExecuteCommand()     <──────────        │
+      │  .OnWindowInitSize()   <──────────        │
+```
+
+**适配器模式（Adapter Pattern）**：鸿蒙系统的每个平台 API 都有对应的适配器类，遵循统一的桥接模式：
+
+```
+BaseAdapter (抽象基类，注入 NativeContext)
+    ↓ 继承
+AppWindowAdapter (鸿蒙窗口 API 适配)
+    ↓ 桥接注册
+AppWindowAdapterBind.bind()
+    ↓ 通过 JsBindingUtils
+bindFunction("AppWindow.CreateWindow", createWindow)
+    ↓ C++ 端按名字调用
+创建鸿蒙 UIAbility 窗口
+```
+
+目前已适配的 37 个适配器覆盖：窗口管理、文件系统、对话框、拖放、通知、权限、蓝牙、打印、语音、无障碍、截屏等。
+
+#### 1.2 入口查找机制
+
+鸿蒙版 Electron 引擎启动时，查找应用入口的顺序：
+
+1. 命令行参数 `--entry=xxx`（如果有）
+2. `web_engine/resfile/resources/app/package.json` 中的 `main` 字段
+
+**默认约定**：应用代码放在 `web_engine/src/main/resources/resfile/resources/app/` 目录下，`package.json` 的 `main` 字段指向主进程入口文件。
+
+#### 1.3 多窗口映射
+
+Electron 的每个 `BrowserWindow` 映射为鸿蒙系统的一个 `UIAbility` 实例：
+
+```
+Electron BrowserWindow          鸿蒙 UIAbility
+       │                              │
+  主窗口 (browser1)        →    EntryAbility
+  子窗口 (browser2)        →    StatelessAbility (instanceKey 单例管理)
+  弹出窗口 (browser3)      →    StatelessAbility
+```
+
+多实例通过 `onAcceptWant` 返回不同的 `instanceKey` 实现：
+
+```ets
+// WebAbilityStage.ets
+onAcceptWant(want: Want): string {
+  let instanceKey = want.parameters?.instanceKey;
+  if (instanceKey) return instanceKey.toString();
+  // 默认返回主窗口 ID
+  return ConfigData.DEFAULT_WINDOW_ID;
+}
+```
+
+#### 1.4 多窗口启动校验坑与真机核验义务（形态匹配检查点）
+
+**形态匹配是第一检查点**：先识别应用是否有托盘——grep 主进程 `new Tray(` / `Tray(`。有托盘 → 多窗口保持模板默认；**无托盘 → 多窗口创建必须成对删除 `processMode` 与 `startupVisibility`**（见下文坑 1），这是适配必做项，不是可选优化。
+
+**坑 1：`ATTACH_TO_STATUS_BAR_ITEM` 进程附加模式（无托盘应用实证，OpenHarmony 7.0.0.105）**。模板 `AppWindowAdapter.createWindow` 启动新建窗口的 UIAbility 时 `StartOptions` 默认带 `processMode: ProcessMode.ATTACH_TO_STATUS_BAR_ITEM` + `startupVisibility`。SDK 注释（`@ohos.app.ability.contextConstant.d.ts`）：该模式把目标 **Ability 进程附加到状态栏 item**，**调用方需先向状态栏添加 item**、且与调用方同 bundle；`startupVisibility` 与之**成对校验**。无托盘应用前置不满足 → 系统以 **16000067（ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED）** 拒绝 → 新窗口的 UIAbility 实例永不创建，表现为「应用内新建窗口点击无反应」（Ctrl+N 与鼠标点击同链路失效，**不是系统占用快捷键**）。注意粒度：绑定的是**进程**不是窗口；**只删 processMode 或只删 startupVisibility 都无效**，须成对删除（走默认 ProcessMode 前台显示）。带托盘应用保持默认即可（进程附加托盘 item 生命周期是合法形态，joplin/AFFiNE/yesplaymusic 已验证）。
+
+**真机核验义务（多窗口应用必跑）**：凡主进程存在「应用内第二次及以上 `new BrowserWindow()`」（文件多开/文档多窗口/打开新窗口类功能），阶段 2 名册必须含「应用内新建窗口」交互用例（install→launch→应用内新建→第二窗口存活并加载 webapp→关闭恢复聚焦），仅启动冒烟测不出此缺陷（首窗走桌面启动、不经过 createWindow 的 StartOptions 路径）。
+
+详见 `pc-error-atlas` **L063**（症状→判别→成对解法→无效修法）。
+
+### 2. 版本选择
+
+| Electron 版本 | Chromium 版本 | Node.js 版本 | 说明 |
+|---|---|---|---|
+| Electron 25 | Chromium 114 | 18.18.2 | 早期适配版 |
+| Electron 34 | Chromium 132 | 20.18.1 | 稳定推荐版 |
+| Electron 37 | Chromium 138 | 22.16.0 | 最新版 |
+
+**选择原则**：
+
+- 检查三方 JS 库依赖的浏览器 API 是否被对应 Chromium 版本支持
+- 检查 Node.js 版本是否满足 native addon 编译要求
+- 从其他平台迁移时，优先选择版本号接近的 Electron 版本
+- 新项目推荐使用最新版
+
+### 3. 工程结构
+
+```
+ohos/
+├── AppScope/
+│   ├── app.json5                         # 应用全局配置（bundleName、版本号）
+│   └── resources/
+│       └── base/
+│           ├── element/string.json       # 全局字符串资源
+│           ├── media/app_icon.png        # 应用图标
+│           └── profile/configuration.json
+├── build-profile.json5                   # 构建配置（SDK版本、构建模式）
+├── hvigor/
+│   └── hvigor-config.json5              # Hvigor 构建工具配置
+├── hvigorfile.ts                         # Hvigor 入口
+├── oh-package.json5                      # 依赖管理
+│
+├── web_engine/                           # ★ HAR 适配层库（一般不需改动）
+│   ├── Index.ets                         # 导出 WebAbility, WebWindow 等
+│   ├── childProcess.ets                  # 导出 WebChildProcess
+│   ├── build-profile.json5
+│   ├── oh-package.json5                  # 依赖 inversify + libadapter.so
+│   ├── src/main/
+│   │   ├── cpp/types/libadapter/         # libadapter.so 的 TS 类型声明
+│   │   │   ├── index.d.ts
+│   │   │   └── oh-package.json5
+│   │   ├── ets/
+│   │   │   ├── application/              # WebAbilityStage (初始化 NativeContext、JSBinding)
+│   │   │   ├── ability/                  # WebAbility, WebBaseAbility, WebEmbeddedAbility
+│   │   │   ├── adapter/                  # 37 个平台 API 适配器
+│   │   │   ├── jsbindings/               # 37 个 Bind 类（注册 C++→ArkTS 回调）
+│   │   │   ├── components/               # WebWindow, WebSubWindow, WebEmbeddedWindow 等
+│   │   │   ├── common/                   # DI 容器、常量、工具类
+│   │   │   ├── interface/                # NativeContext、WebProxy 等接口
+│   │   │   ├── process/                  # WebChildProcess（渲染进程）
+│   │   │   └── utils/                    # JsBindingUtils、LogUtil 等工具
+│   │   └── resources/
+│   │       └── resfile/                  # ★ Electron 引擎资源 + 应用代码
+│   │           ├── chrome_100_percent.pak
+│   │           ├── chrome_200_percent.pak
+│   │           ├── icudtl.dat
+│   │           ├── v8_context_snapshot.bin
+│   │           ├── resources.pak
+│   │           ├── locales/              # 国际化资源
+│   │           ├── vulkan/               # Vulkan 渲染 ICD
+│   │           ├── electron              # Electron 引擎二进制资源
+│   │           └── resources/
+│   │               └── app/             # ★★★ 你的应用代码在这里
+│   │                   ├── main.js       # 主进程入口
+│   │                   ├── package.json  # main: "main.js"
+│   │                   ├── preload.js    # 预加载脚本
+│   │                   └── index.html    # 渲染页面
+│   └── test/
+│
+└── electron/                             # ★ HAP 入口模块
+    ├── build-profile.json5
+    ├── oh-package.json5                  # 依赖 web_engine
+    ├── hvigorfile.ts
+    ├── obfuscation-rules.txt
+    ├── libs/arm64-v8a/                   # ★ 原生动态库
+    │   ├── libadapter.so                 # ArkTS ↔ C++ 桥接层
+    │   ├── libelectron.so                # Chromium + Node.js + Electron 引擎
+    │   ├── libc++_shared.so              # C++ 标准库
+    │   └── libffmpeg.so                  # 媒体编解码
+    └── src/main/
+        ├── ets/
+        │   ├── Application/
+        │   │   └── AbilityStage.ets     # 继承 WebAbilityStage
+        │   ├── entryability/
+        │   │   ├── EntryAbility.ets     # 继承 WebAbility（主窗口）
+        │   │   ├── BrowserAbility.ets   # 继承 WebAbility（浏览器窗口）
+        │   │   ├── StatelessAbility.ets # 继承 WebAbility（无状态窗口）
+        │   │   └── StatusBarEntryAbility.ets # 状态栏扩展
+        │   ├── extensionAbility/
+        │   │   └── BrowserEmbeddedAbility.ets # 嵌入式扩展
+        │   ├── pages/                    # ArkUI 页面
+        │   │   ├── Index.ets            # 主页面（承载 XComponent）
+        │   │   ├── SubWindow.ets        # 子窗口页面
+        │   │   ├── WindowNode.ets       # 窗口节点页面
+        │   │   └── ...
+        │   └── process/
+        │       └── CustomChildProcess.ets # 继承 WebChildProcess
+        ├── module.json5                  # 模块配置（Ability声明、权限）
+        └── resources/                    # 图标、字符串等资源
+```
+
+### 4. 迁移步骤
+
+#### 步骤1：分析依赖
+
+```bash
+# 在原始 Electron 工程中检查依赖
+npm ls --all
+```
+
+重点关注：
+
+- **纯 JS 依赖**：可直接在鸿蒙环境运行，无需改动
+- **C/C++ Native Addon**（含 `.node` 文件）：必须用鸿蒙 NDK 工具链重新编译
+- **平台特定 API**：检查是否有 `process.platform === 'darwin'` / `'win32'` 等硬编码判断
+
+#### 步骤2：业务代码适配
+
+**2.1 平台判断**
+
+```js
+// ❌ 原始代码
+if (process.platform !== 'darwin') {
+  app.quit()
+}
+
+// ✅ 适配后
+if (process.platform !== 'darwin' && process.platform !== 'openharmony') {
+  app.quit()
+}
+```
+
+**2.2 沙箱路径**
+
+鸿蒙应用的文件系统是沙箱隔离的，路径前缀不同：
+
+| 用途 | macOS | 鸿蒙 |
+|---|---|---|
+| 应用数据 | `~/Library/Application Support/` | `/data/storage/el2/base/files/` |
+| 临时目录 | `/tmp/` | `/data/storage/el2/base/cache/` |
+| 用户文档 | `~/Documents/` | 沙箱内，需通过 FilePicker 访问 |
+| 可执行文件 | `app.getPath('exe')` | `/data/storage/el1/bundle/` |
+
+在 Electron 代码中，优先使用 `app.getPath()` 获取路径，这样在鸿蒙上会自动映射到正确的沙箱路径：
+
+```js
+// ✅ 正确 —— 自动适配沙箱路径
+const userDataPath = app.getPath('userData')
+const docPath = app.getPath('documents')
+
+// ❌ 错误 —— 硬编码 macOS 路径
+const userDataPath = path.join(os.homedir(), 'Library', 'Application Support')
+```
+
+**2.3 权限声明**
+
+鸿蒙系统对文件访问、通知、网络等有显式权限要求，需在 `module.json5` 中声明：
+
+```json5
+{
+  "module": {
+    "requestPermissions": [
+      { "name": "ohos.permission.INTERNET" },
+      { "name": "ohos.permission.FILE_ACCESS_PERSIST" },
+      { "name": "ohos.permission.NOTIFICATION" }
+    ]
+  }
+}
+```
+
+macOS 没有类似的声明式权限机制（依赖运行时弹窗授权或 Entitlements）。
+
+#### 步骤3：编译产物迁移
+
+**3.1 构建 macOS 产物（无 asar）**
+
+```json
+// package.json
+{
+  "build": {
+    "asar": false
+  }
+}
+```
+
+```bash
+npm run build:dir
+```
+
+**3.2 拷贝到鸿蒙工程**
+
+```bash
+# 从 macOS 构建产物中提取应用代码
+cp -r dist/mac-arm64/MyApp.app/Contents/Resources/app/* \
+      ohos/web_engine/src/main/resources/resfile/resources/app/
+```
+
+**3.3 删除 devDependencies**
+
+```bash
+# 在 resources/app/package.json 中删除 devDependencies 字段
+# 鸿蒙环境不需要开发依赖
+```
+
+**3.4 安装生产依赖**
+
+```bash
+cd ohos/web_engine/src/main/resources/resfile/resources/app/
+npm install --production
+```
+
+**3.5 处理 Native Addon**
+
+如果有 C/C++ 原生模块：
+
+```bash
+# 1. 用鸿蒙 NDK 重新编译，生成 .so 文件
+# 2. 将 .so 放到 ohos/electron/libs/arm64-v8a/ 目录
+# 3. 修改 require 路径
+```
+
+```js
+// 原始代码
+const addon = require('node-sqlite3')
+
+// 鸿蒙适配后
+const addon = require('/data/storage/el1/bundle/libs/arm64/libsqlitenode.so')
+```
+
+#### 步骤4：修改入口文件名
+
+鸿蒙工程约定入口文件名为 `main.js`（由 `resources/app/package.json` 的 `main` 字段指定）。如果原始工程入口文件名不同，需要重命名或修改 `package.json`。
+
+#### 步骤5：构建运行
+
+使用 DevEco Studio 打开 `ohos/` 目录，构建并运行。
+
+### 5. 关键差异点
+
+#### 5.1 process.platform
+
+| 平台 | process.platform 值 |
+|---|---|
+| macOS | `'darwin'` |
+| Windows | `'win32'` |
+| Linux | `'linux'` |
+| 鸿蒙 | `'openharmony'` |
+
+#### 5.2 TypeScript 接口声明
+
+鸿蒙版 Electron 新增了权限等接口，但开源 `electron.d.ts` 不包含这些声明，编译时会报错：
+
+```
+error TS2339: Property 'requestSystemPermission' does not exist on type 'SystemPreferences'.
+```
+
+**解决方案**：用鸿蒙版 Electron 源码中的 `electron.d.ts` 替换业务代码 `node_modules/electron/electron.d.ts`。
+
+同类错误码：TS2345、TS2554、TS2346、TS2339、TS2684、TS2769、TS2564、TS2367。
+
+#### 5.3 Native Addon 加载
+
+| macOS | 鸿蒙 |
+|---|---|
+| `.node` 文件（动态库） | `.so` 文件（动态库） |
+| `require('addon.node')` | `require('libaddon.so')` |
+| 用 node-gyp / cmake 编译 | 用鸿蒙 NDK (llvm) 编译 |
+| 链接(node.lib / libnode) | 链接(libshim.a 提供的 N-API shim) |
+
+### 6. 调试方法
+
+#### 6.1 日志调试
+
+```ets
+import hilog from '@ohos.hilog'
+hilog.info(0x0000, 'MyTag', 'message here')
+```
+
+通过 `hdc hilog | grep MyTag` 查看日志。
+
+#### 6.2 远程调试
+
+DevEco Studio 支持连接鸿蒙设备进行远程调试，可查看 C++ 层日志和 ArkTS 层日志。
+
+#### 6.3 Chromium DevTools
+
+鸿蒙版 Electron 支持 `--remote-debugging-port=9222` 参数，启动后可在同网络的 Chrome 浏览器中访问 `chrome://inspect` 进行渲染进程调试。
+
+---
+
+## 三、两平台工具链对比
+
+### 1. 开发工具
+
+| 维度 | macOS | 鸿蒙 |
+|---|---|---|
+| IDE | VSCode / WebStorm | DevEco Studio |
+| 语言 | JavaScript / TypeScript | JavaScript / TypeScript（应用层）+ ArkTS（壳层） |
+| 包管理 | npm / yarn / pnpm | ohpm（鸿蒙包管理） |
+| 构建工具 | electron-builder | Hvigor（DevEco 内置） |
+| 版本管理 | git | git |
+| 调试 | Chrome DevTools | Chrome DevTools + hilog + DevEco 远程调试 |
+
+### 2. 运行时
+
+| 维度 | macOS | 鸿蒙 |
+|---|---|---|
+| 渲染引擎 | Chromium（独立进程） | Chromium（通过 XComponent 嵌入） |
+| JS 引擎 | V8（主进程使用 Node.js，渲染进程使用 V8） | V8（同 macOS，但通过 libadapter.so 桥接） |
+| GPU 渲染 | 直接访问 GPU（OpenGL/Metal） | Ozone 后端 + EGL（`--use-gl=egl`） |
+| 窗口系统 | 原生 NSWindow | UIAbility + WindowStage |
+| 进程模型 | 多进程（主进程 + 渲染进程 + GPU 进程） | 多进程（主 UIAbility + 子 ChildProcess + GPU 线程） |
+
+### 3. 构建与打包
+
+| 维度 | macOS | 鸿蒙 |
+|---|---|---|
+| 构建命令 | `electron-builder` | `hvigorw assembleHap`（DevEco 图形化也可） |
+| 产物格式 | `.app` / `.dmg` / `.zip` | `.hap` / `.app`（多个 HAP 打包） |
+| 代码归档 | `app.asar`（默认启用） | 直接放入 `resfile/resources/app/`（无 asar） |
+| 签名 | codesign + notarytool（Apple） | 签名工具（华为） |
+| 包体大小 | ~100MB+（含 Chromium + Node.js） | ~100MB+（含 .so 原生库） |
+
+### 4. API 适配层
+
+| 维度 | macOS | 鸿蒙 |
+|---|---|---|
+| 窗口 API | `BrowserWindow` → NSWindow | `BrowserWindow` → UIAbility → XComponent |
+| 文件对话框 | `dialog.showOpenDialog` → NSOpenPanel | `dialog.showOpenDialog` → FilePickerAdapter → 鸿蒙 FilePicker |
+| 剪贴板 | `clipboard.readText` → NSPasteboard | `clipboard.readText` → 无直接绑定，需走 ETS 层 |
+| 通知 | `Notification` → NSUserNotification | `Notification` → NotificationAdapter → 鸿蒙通知 API |
+| 文件系统 | `fs.readFileSync` → POSIX API | `fs.readFileSync` → FileManagerAdapter → 鸿蒙沙箱 API |
+| Shell | `shell.openExternal` → NSWorkspace | `shell.openExternal` → ContextAdapter → 鸿蒙隐式 Want |
+| 系统 UI | `dialog.showMessageBox` → NSAlert | `dialog.showMessageBox` → DialogAdapter → ArkUI CustomDialog |
+| 拖放 | HTML5 DnD → Cocoa DnD | HTML5 DnD → DragDropAdapter → 鸿蒙 UnifiedData |
+
+### 5. 安全与权限
+
+| 维度 | macOS | 鸿蒙 |
+|---|---|---|
+| 沙箱 | App Sandbox（可选） | 强制应用沙箱（无选择） |
+| 权限模型 | Entitlements + 运行时弹窗 | `module.json5` 声明 + 运行时弹窗 |
+| CSP | HTML meta 标签设置 | 同 macOS（Electron 引擎负责） |
+| 代码签名 | 必须（否则被 Gatekeeper 拦截） | 必须（否则无法安装） |
+| 渲染进程隔离 | `contextIsolation` + `sandbox` | 同 macOS + OS 级别沙箱加强 |
+
+### 6. 工程管理方式
+
+| 维度 | macOS | 鸿蒙 |
+|---|---|---|
+| 工程结构 | 单目录（package projektu） | 双目录（原始工程 + 鸿蒙工程分离维护） |
+| 代码同步 | — | 需手动拷贝编译产物到鸿蒙工程 `resources/app/` |
+| 依赖安装 | `npm install`（含 devDependencies） | `npm install --production`（仅生产依赖） |
+| 迭代流程 | 改代码 → `npm start` | 改代码 → 拷贝 → DevEco 重建 |
+| 最佳实践 | — | 原始工程 `asar: false` 打包，拷贝拆包产物到鸿蒙工程 |
+
+---
+
+## 四、迁移速查清单
+
+- [ ] 检查 `process.platform` 判断，添加 `'openharmony'` 分支
+- [ ] 将硬编码路径改为 `app.getPath()` 获取
+- [ ] 检查 C/C++ 原生模块，用鸿蒙 NDK 重新编译
+- [ ] 在 `module.json5` 中声明所需权限
+- [ ] 用原始工程 `asar: false` 构建，提取 `app/` 目录
+- [ ] 拷贝应用代码到 `web_engine/resfile/resources/app/`
+- [ ] 确保 `package.json` 的 `main` 字段指向正确入口文件名
+- [ ] 删除 `package.json` 中的 `devDependencies`
+- [ ] 如有 TS 项目，替换 `electron.d.ts` 为鸿蒙版本
+- [ ] 用 DevEco Studio 构建运行，验证功能