electron-ohos-hotreload 1.0.0

package/docs/user-manual.md

@@ -0,0 +1,766 @@
+# Electron OHOS Hot-Reload 用户使用手册
+
+> **版本**: 1.4.0
+> **工具名称**: `eohr`
+> **用途**: 在鸿蒙版 Electron 工程中热加载你的 JS/TS 应用代码，无需重建 HAP
+
+---
+
+## 1. 这是什么
+
+`eohr` 是一个命令行工具。你修改 Electron 应用代码后，按一个组合键就能把代码打包推送到设备并重载，**不用重建 HAP**。
+
+### 没用 eohr vs 用了 eohr
+
+| | 没用 eohr | 用了 eohr |
+|---|-----------|-----------|
+| 流程 | 改代码 → 重建 HAP → 卸载 → 安装 → 启动 | 改代码 → 保存 → 按 Ctrl+Shift+X → 看结果 |
+| 耗时 | 3~4 分钟 | 1~15 秒 |
+| 操作 | 全程手动 | 改完按一下键 |
+
+### 对开发者文件的影响
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `hot-reload-agent.js` | **新增** | 设备侧 agent，工具自动管理，`eohr clean` 时自动删除 |
+| `package.json` | **改一行** | `main` 字段指向 agent，`eohr clean` 时自动改回原始值 |
+| `main.js` | **不碰** | 你的代码原封不动，从头到尾不会被修改 |
+
+调试结束后执行 `eohr clean`，新增的文件自动删除，`package.json` 自动还原，工程恢复到 `eohr init` 之前的状态，不留任何痕迹。
+
+### 适用范围
+
+| 改了什么 | 能热加载？ |
+|---------|-----------|
+| 你的 JS/TS 应用代码 (main.js、业务逻辑、UI) | ✅ |
+| TypeScript 代码 | ✅ (esbuild 原生支持) |
+| ETS Adapter 代码 (*.ets) | ❌ 需重建 HAP |
+| `module.json5` / `build-profile.json5` | ❌ 需重建 HAP |
+| `libelectron.so` / `libadapter.so` | ❌ 需重建 HAP |
+
+---
+
+## 2. 环境准备
+
+### 2.1 前置条件
+
+- Node.js >= 16
+- hdc 已安装（DevEco Studio 自带，需设置 `DEVECO_SDK_HOME` 或加入 PATH）
+- HarmonyOS 2in1 / tablet 设备已连接
+
+### 2.2 确认 hdc
+
+```bash
+hdc list targets
+```
+
+如果报错，设置 `DEVECO_SDK_HOME` 环境变量并把 hdc 加入 PATH：
+
+**Windows (PowerShell)**：
+```powershell
+$env:DEVECO_SDK_HOME = "D:\Program Files\Huawei\DevEco Studio\sdk"
+```
+
+**macOS**：
+
+打开配置文件：
+```bash
+nano ~/.zshrc
+```
+
+在文件末尾加入：
+```bash
+export PATH=$PATH:/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains
+```
+
+保存退出（`Ctrl+O` 回车，`Ctrl+X`），然后执行：
+```bash
+source ~/.zshrc
+```
+
+### 2.3 安装 eohr
+
+**第一步：安装依赖**
+
+```bash
+cd <eohr工具所在路径>/electron-ohos-hotreload
+npm install
+```
+
+**第二步：配置快捷命令**
+
+```bash
+node <eohr工具所在路径>/electron-ohos-hotreload/bin/eohr.js setup
+```
+
+这一步会自动检测你的终端类型（PowerShell / cmd / bash / zsh），自动写入配置：
+
+| 平台 | 终端 | 自动做的事 |
+|------|------|-----------|
+| Windows | PowerShell | 在 `$PROFILE` 写入 `function eohr`，设置执行策略为 RemoteSigned |
+| Windows | cmd | 创建 `eohr.bat` 到用户目录，自动加入 PATH |
+| macOS | zsh/bash | 在 `~/.zshrc` 或 `~/.bash_profile` 写入 `alias eohr` |
+| Linux | bash | 在 `~/.bashrc` 写入 `alias eohr` |
+
+**第三步：重新打开终端，验证**
+
+```bash
+eohr --version
+```
+
+输出：
+```
+1.0.0
+```
+
+> 如果不想配置快捷命令，后续所有命令把 `eohr` 替换为 `node <eohr路径>/bin/eohr.js` 即可。
+
+---
+
+## 3. 快速开始
+
+### 3.1 初始化（一次性）
+
+```bash
+cd <你的工作区路径>/ohos_hap
+eohr init
+```
+
+输出：
+```
+  Electron OHOS Hot-Reload  v1.0.0
+  ──────────────────────────────────────
+  Bundle:   com.huawei.ohos_electron
+  Entry:    web_engine/src/main/resources/resfile/resources/app/main.js
+  Strategy: hard
+  HAP:      D:\code\...\ohos_hap
+
+  [info] 已新增 hot-reload-agent.js
+  [info] package.json main: "main.js" → "hot-reload-agent.js"
+  [info] 已生成 .eohr.config.json
+
+  ✓ init 完成
+
+  改动清单:
+  + hot-reload-agent.js  (新增)
+  ~ package.json       (main → hot-reload-agent.js)
+  main.js             (未改动)
+
+  下一步:
+  1. 重建 HAP 并安装 (仅此一次):
+     hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+     hdc install <hap-path>
+
+  2. 启动热加载:
+     eohr watch
+```
+
+**这一步只做了两件事**：
+1. 在 app 目录新增了 `hot-reload-agent.js`
+2. 把 `package.json` 的 `main` 从 `"main.js"` 改成 `"hot-reload-agent.js"`
+
+**你的 `main.js` 没有被改动。**
+
+### 3.2 重建 HAP（仅此一次）
+
+因为 `package.json` 改了，需要重新打包 HAP。用 DevEco Studio 打开工程，签名后构建：
+
+**方式一：DevEco Studio 构建（推荐）**
+
+1. DevEco Studio 打开 `ohos_hap` 工程
+2. `File → Project Structure → Signing Configs` 勾选自动签名
+3. `Build → Build HAP(s) → Build HAP(s)`
+4. 构建完成后得到签名 HAP
+
+**方式二：命令行构建**
+
+**Windows (PowerShell)**：
+```powershell
+# 设置环境变量
+$env:DEVECO_SDK_HOME = "D:\Program Files\Huawei\DevEco Studio\sdk"
+$env:PATH = "D:\Program Files\Huawei\DevEco Studio\tools\node;D:\Program Files\Huawei\DevEco Studio\jbr\bin;" + $env:PATH
+
+# 清缓存
+Remove-Item ".hvigor\cache" -Recurse -Force -ErrorAction SilentlyContinue
+Remove-Item "electron\build" -Recurse -Force -ErrorAction SilentlyContinue
+
+# 构建
+& "D:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat" assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+
+# 安装
+hdc install electron\build\default\outputs\default\electron-default-signed.hap
+```
+
+**macOS**：
+```bash
+# 设置环境变量
+export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
+export PATH="/Applications/DevEco-Studio.app/Contents/tools/node:/Applications/DevEco-Studio.app/Contents/jbr/Contents/bin:$PATH"
+
+# 清缓存
+rm -rf .hvigor/cache electron/build
+
+# 构建
+/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+
+# 安装
+hdc install electron/build/default/outputs/default/electron-default-signed.hap
+```
+
+> 之后只要不改 ETS/原生库，再也不需要重建 HAP。
+
+### 3.3 启动热加载
+
+```bash
+eohr watch
+```
+
+输出：
+```
+  Electron OHOS Hot-Reload  v1.0.0
+  ──────────────────────────────────────
+  Bundle:   com.huawei.ohos_electron
+  Entry:    web_engine/.../app/main.js
+  Strategy: hard
+  HAP:      D:\code\...\ohos_hap
+
+  [info] hdc: D:\Program Files\...\hd
+  c.exe
+  [info] 模式: manual (按 Ctrl+Shift+X 推送)
+  [info] 首次推送...
+  [bundle] esbuild... (120ms)
+  [send] hdc file send... ok
+  [reload] hard (restart)
+  ● agent-ready
+  ● loaded
+  [ready] manual 模式
+  ──────────────────────────────────────
+  Ctrl+Shift+X  推送并重载
+  q / Ctrl+C    退出
+```
+
+### 3.4 修改代码，按 Ctrl+Shift+X 重载
+
+在编辑器里改你的 `main.js`，保存。终端会显示待推送的文件：
+
+```
+  [pending] main.js (按 Ctrl+Shift+X 推送)
+```
+
+改完后切到终端，按 `Ctrl+Shift+X`：
+
+```
+  [info] 推送 1 个文件变更: main.js
+  [bundle] esbuild... (85ms)
+  [send] ok
+  [info] 重启应用...
+  [reload] hard (restart)
+```
+
+**日常循环：改代码 → 保存 → 按 Ctrl+Shift+X → 看结果。**
+
+---
+
+## 4. 命令参考
+
+> 以下命令均假设已按 2.3 设置了 `eohr` 快捷命令。未设置的，将 `eohr` 替换为 `node <eohr路径>/bin/eohr.js`。
+
+### eohr setup
+
+自动配置快捷命令。
+
+```bash
+node <eohr路径>/bin/eohr.js setup
+```
+
+自动检测终端类型（PowerShell / cmd / bash / zsh），自动写入配置，重新打开终端即可用 `eohr` 命令。
+
+---
+
+### eohr init
+
+一次性初始化。新增 agent 文件 + 改 `package.json` 一行。
+
+```bash
+eohr init [--hap-root <path>] [--entry <path>]
+```
+
+| 选项 | 说明 | 默认 |
+|------|------|------|
+| `--hap-root` | HAP 工程根目录 | 自动探测 |
+| `--bundle-name` | 应用包名 | 从 app.json5 读取 |
+| `--app-dir` | app 目录 | 自动探测 |
+| `--entry` | 入口文件 | 自动探测 |
+
+---
+
+### eohr watch
+
+启动热加载循环（日常最常用）。
+
+**默认手动模式**：文件监听只记录变更，不自动推送。你改完代码后按 **Ctrl+Shift+X** 触发推送+重载。
+
+```bash
+eohr watch
+```
+
+输出：
+```
+  [ready] manual 模式
+  ──────────────────────────────────────
+  Ctrl+Shift+X  推送并重载
+  q / Ctrl+C    退出
+
+  [pending] main.js (按 Ctrl+Shift+X 推送)
+  [pending] window.ts (按 Ctrl+Shift+X 推送)
+```
+
+按 Ctrl+Shift+X：
+```
+  [info] 推送 2 个文件变更: main.js, window.ts
+  [bundle] esbuild... (85ms)
+  [send] ok
+  [info] 重启应用...
+  [reload] hard (restart)
+```
+
+### 自定义触发键
+
+编辑 `.eohr.config.json`：
+
+```json
+{
+  "triggerKey": "ctrl+r"
+}
+```
+
+格式：修饰键用 `+` 连接，最后是主键。
+
+| 值 | 按键 |
+|------|------|
+| `"ctrl+shift+x"` | Ctrl+Shift+X（默认） |
+| `"ctrl+r"` | Ctrl+R |
+| `"ctrl+alt+t"` | Ctrl+Alt+T |
+| `"f5"` | F5 功能键 |
+| `"space"` | 空格键 |
+| `"enter"` | 回车键 |
+
+也可以命令行指定：
+
+```bash
+eohr watch --trigger-key ctrl+r
+```
+
+**auto 模式**（保存即推送，无需按键）：
+
+```bash
+eohr watch --auto
+```
+
+| 选项 | 说明 | 默认 |
+|------|------|------|
+| `--strategy` | 重载策略 | hard |
+| `--entry` | 入口文件 | 从配置读取 |
+| `--trigger-key` | 触发键 | ctrl+shift+x |
+| `--auto` | 保存即自动推送 | 手动模式 |
+
+---
+
+### eohr push
+
+单次打包推送，不启动持续监听。
+
+```bash
+eohr push [--file <f>] [--no-trigger] [--entry <path>]
+```
+
+输出：
+```
+  [push] bundleName=com.huawei.ohos_electron
+  [bundle] esbuild...
+  entry: web_engine/src/main/resources/resfile/resources/app/main.js
+  [ok] bundled (508ms)
+  [send] hdc file send...
+  [ok] entry.js pushed
+  重启应用...
+  [reload] app restarted
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--file <path>` | 推送单个文件（而非打包入口） |
+| `--no-trigger` | 推送但不触发重载 |
+
+---
+
+### eohr status
+
+查询设备 agent 状态。
+
+```bash
+eohr status
+```
+
+输出：
+```
+  [status] bundleName=com.huawei.ohos_electron
+  ──────────────────────────────────────
+  Device:    connected
+  Status:    loaded
+  PID:       61525
+  Strategy:  hard
+  Entry.js:  exists
+```
+
+---
+
+### eohr strategy
+
+查看或切换重载策略。
+
+```bash
+eohr strategy              # 查看当前策略
+eohr strategy hard         # 硬重载（默认）
+eohr strategy soft         # 软重载
+```
+
+输出：
+```
+  [strategy] 当前: hard
+
+  可选值:
+    soft        仅软重载 (require.cache 失效, ~1-3s)
+    hard        仅硬重载 (app.quit + restart, ~15s, 默认)
+    hard-first  软重载优先, 失败回退硬重载
+```
+
+| 策略 | 耗时 | 说明 |
+|------|------|------|
+| `hard` | ~15s | 杀进程重启，完全干净（默认，推荐） |
+| `soft` | 1~3s | require.cache 失效，不重启应用（有副作用残留） |
+| `hard-first` | 1~3s / 15s | 先 soft，失败回退 hard |
+
+---
+
+### eohr log
+
+查看设备运行日志。
+
+```bash
+eohr log       # 最近 50 行
+eohr log 100   # 最近 100 行
+```
+
+输出：
+```
+  [log] 最近 50 行
+  ──────────────────────────────────────
+  2026-09-10T09:34:50.204Z [agent] config loaded: {"strategy":"hard","softTimeout":5000}
+  2026-09-10T09:34:50.205Z [agent] agent started, strategy=hard
+  2026-09-10T09:34:50.205Z [agent] loading entry.js from override
+  2026-09-10T09:34:50.206Z [agent] first load done
+  2026-09-10T09:34:50.206Z [agent] fs.watch active on /data/storage/el2/base/files/hot
+  2026-09-10T09:36:19.046Z [agent] watch event: change entry.js
+  2026-09-10T09:36:19.047Z [agent] hard reload: waiting for host to restart
+  2026-09-10T09:36:19.925Z [agent] config loaded: {"strategy":"hard","softTimeout":5000}
+  2026-09-10T09:36:19.925Z [agent] agent started, strategy=hard
+  2026-09-10T09:36:19.925Z [agent] loading entry.js from override
+  2026-09-10T09:36:19.926Z [agent] first load done
+```
+
+---
+
+### eohr clean
+
+恢复工程到 `eohr init` 之前的状态 + 清空设备。
+
+```bash
+eohr clean
+```
+
+输出：
+```
+  [info] 开始恢复工程
+  [ok] hot-reload-agent.js 已删除
+  [ok] package.json main → "main.js"
+  [ok] .eohr.config.json 已删除
+  清空设备...
+  [ok] 设备已清空
+
+  ✓ clean 完成
+
+  工程已恢复到 eohr init 之前的状态。
+  请重建 HAP 让恢复生效:
+  hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+  hdc install <hap>
+```
+
+做了什么：
+1. 删除 `hot-reload-agent.js`
+2. `package.json` 的 `main` 改回 `"main.js"`
+3. 删除 `.eohr.config.json`
+4. 清空设备 override 目录
+
+跑完后工程干干净净，重建 HAP 即可恢复原始状态。
+
+---
+
+## 5. 配置文件
+
+### .eohr.config.json
+
+`eohr init` 自动生成，可手动编辑：
+
+```json
+{
+  "bundleName": "com.huawei.ohos_electron",
+  "hapRoot": "<你的工作区路径>/ohos_hap",
+  "appDir": "<你的工作区路径>/ohos_hap/web_engine/src/main/resources/resfile/resources/app",
+  "entry": "web_engine/src/main/resources/resfile/resources/app/main.js",
+  "strategy": "hard",
+  "triggerKey": "ctrl+shift+x",
+  "watch": [
+    "web_engine/src/main/resources/resfile/resources/app/**/*.ts",
+    "web_engine/src/main/resources/resfile/resources/app/**/*.js",
+    "src/**/*.ts",
+    "src/**/*.js"
+  ],
+  "ignore": ["node_modules/**", "dist/**", ".git/**"],
+  "userId": 100
+}
+```
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `entry` | 你的应用入口文件 | 自动探测 |
+| `strategy` | 重载策略 | hard |
+| `triggerKey` | 触发键（手动模式） | ctrl+shift+x |
+| `watch` | 监听的文件模式 | 自动探测（含 app 目录 + src 目录） |
+| `userId` | OHOS 用户 ID | 100 |
+
+### 指定入口文件
+
+默认自动探测你的 `main.js`。也可以指定其他文件：
+
+```bash
+eohr init --entry src/index.ts
+eohr watch --entry app/main.js
+```
+
+或编辑 `.eohr.config.json`:
+```json
+{
+  "entry": "src/index.ts"
+}
+```
+
+---
+
+## 6. 重载策略详解
+
+### hard（默认，推荐）
+
+杀进程重启应用。完全干净，无副作用残留。
+
+这是 Electron 主进程热加载的业界标准做法。`electron-reload`、`electronmon` 等工具均采用杀进程重启方式，因为主进程的窗口、IPC、定时器等副作用无法通过清缓存完全回收。
+
+耗时 ~15 秒。
+
+### soft
+
+清除 `require.cache`，重新加载。快（1~3s），应用不重启。
+
+**限制**：不会自动关闭上一轮创建的 BrowserWindow、已注册的 protocol/ipcMain、定时器等。会出现重复窗口、重复监听等问题。仅适用于无副作用的纯逻辑模块。
+
+### 何时切换
+
+```bash
+eohr strategy soft        # 代码无副作用（纯逻辑），追求速度
+eohr strategy hard        # 切回默认
+```
+
+---
+
+## 7. 日常开发工作流
+
+### 标准流程
+
+```
+1. eohr watch （保持运行）
+2. 编辑器里改代码（就是改你自己的 main.js 或其他文件）
+3. 保存 (Ctrl+S)  ← 终端显示 [pending]
+4. 切到终端按 Ctrl+Shift+X  ← 推送并重载
+5. 看终端状态
+6. 回到 2
+```
+
+> 如果你更喜欢保存即推送（不需要按键），用 `eohr watch --auto`。
+
+### 示例
+
+你的 `main.js`：
+
+```javascript
+const { app, BrowserWindow } = require('electron');
+
+app.whenReady().then(() => {
+  const win = new BrowserWindow({ width: 800, height: 600 });
+  win.loadURL('https://cn.bing.com');
+});
+```
+
+改成：
+
+```javascript
+app.whenReady().then(() => {
+  const win = new BrowserWindow({ width: 1024, height: 768 });
+  win.loadURL('https://www.baidu.com');
+});
+```
+
+保存 → 切到终端按 Ctrl+Shift+X → 十几秒后设备上的窗口尺寸和 URL 自动更新。
+
+### 多文件修改
+
+同时改多个文件时，变更会攒在 `pendingChanges` 里，一次 Ctrl+Shift+X 全部推送。
+
+---
+
+## 8. 故障排查
+
+### 设备未连接
+
+```bash
+hdc list targets
+hdc kill
+hdc start
+```
+
+### 找不到 hdc
+
+**Windows (PowerShell)**：
+```powershell
+$env:DEVECO_SDK_HOME = "D:\Program Files\Huawei\DevEco Studio\sdk"
+```
+
+**macOS**：
+
+在 `~/.zshrc` 中添加：
+```bash
+export PATH=$PATH:/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains
+```
+
+然后执行 `source ~/.zshrc`。
+
+### HAP 安装失败（无签名）
+
+需要通过 DevEco Studio 配置签名：
+1. DevEco Studio 打开工程
+2. `File → Project Structure → Signing Configs` 勾选自动签名
+3. 重新构建 HAP
+
+### soft 重载总是失败
+
+```bash
+eohr strategy hard
+eohr push
+```
+
+### 查看设备日志
+
+```bash
+eohr log
+```
+
+### 恢复原始状态（取消热加载）
+
+```bash
+eohr clean
+# 然后重建 HAP（用 DevEco Studio 或命令行，见 3.2 节）
+```
+
+`eohr clean` 会自动删除 agent 文件、还原 `package.json`、删除配置。你的 `main.js` 从头到尾没被动过。
+
+---
+
+## 9. 命令速查
+
+| 命令 | 说明 |
+|------|------|
+| `eohr setup` | 自动配置快捷命令（PowerShell/cmd/bash/zsh） |
+| `eohr init` | 一次性初始化（新增 agent + 改 package.json 一行） |
+| `eohr watch` | 启动热加载（日常用这个，按 Ctrl+Shift+X 推送） |
+| `eohr watch --auto` | 保存即自动推送 |
+| `eohr push` | 单次推送 |
+| `eohr status` | 查询设备状态 |
+| `eohr strategy` | 查看/切换策略 |
+| `eohr log` | 查看设备日志 |
+| `eohr clean` | 恢复工程 + 清空设备 |
+
+---
+
+## 10. FAQ
+
+**Q: eohr init 改了我的 main.js 吗？**
+
+没有。`eohr init` 只做了两件事：新增 `hot-reload-agent.js`，把 `package.json` 的 `main` 字段指向它。你的 `main.js` 原封不动。
+
+**Q: eohr 命令找不到怎么办？**
+
+运行 `node <eohr路径>/bin/eohr.js setup` 自动配置快捷命令，然后重新打开终端。或者把所有 `eohr` 替换为 `node <eohr路径>/bin/eohr.js`。
+
+**Q: npm install 报权限错误怎么办？**
+
+不要用 `npm install -g`（全局安装），在 eohr 工具目录下用 `npm install`（本地安装）即可。
+
+**Q: 入口文件怎么指定？**
+
+`eohr init` 自动探测你的 `main.js`。也可以 `--entry src/index.ts` 或编辑 `.eohr.config.json`。
+
+**Q: 可以用 TypeScript 吗？**
+
+可以，esbuild 原生支持，无需预编译。
+
+**Q: 我的代码依赖 npm 包怎么办？**
+
+esbuild 会把 `node_modules` 中的依赖打进 `entry.js` 单文件。确保工程根目录有 `node_modules`。
+
+**Q: 改了 ETS 代码怎么办？**
+
+必须重建 HAP：
+```bash
+hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+hdc install <hap>
+eohr watch
+```
+
+**Q: 生产 HAP 会受影响吗？**
+
+不会。如果 override 目录没有 `entry.js`，agent 直接加载你的 `main.js`，行为与未安装 eohr 完全一致。
+
+**Q: 触发键可以改吗？**
+
+可以，编辑 `.eohr.config.json` 的 `triggerKey` 字段，或 `eohr watch --trigger-key ctrl+r`。
+
+**Q: 不想每次按键，想保存就推送？**
+
+用 `eohr watch --auto`。
+
+**Q: 如何查看设备日志？**
+
+```bash
+eohr log
+```
+
+**Q: userId 不是 100？**
+
+编辑 `.eohr.config.json` 的 `userId` 字段。
+
+**Q: 不想用热加载了怎么恢复？**
+
+```bash
+eohr clean
+# 重建 HAP（见 3.2 节）
+```
+
+`eohr clean` 会删除 agent、还原 `package.json`、删除配置。你的代码从头到尾没被动过。