Hoppscotch · OpenHarmony 适配说明

本文档面向开发者，说明如何把本仓库编译、构建并运行到 OpenHarmony / HarmonyOS 设备上，并解释本项目是如何完成鸿蒙适配的，最后用 T0 / T1 / T2 分级如实给出当前的功能支持情况。下表中的状态均已在真机上实测确认。

Hoppscotch 是一个开源的 API 开发生态（API 调试、集合、环境、历史等）。官方桌面端基于 Tauri，本仓库在其之上新增了一套面向 OpenHarmony 的 Electron HAP 工程，位于根目录的 ohos_hap/。

---

一、整体适配思路

Hoppscotch 本体是一个 pnpm monorepo（见 packages/）。鸿蒙端没有重写前端，而是采用 Web / Electron 承载（carrier）路线，复用已有的 Web 产物，把它装进一个跑在 OpenHarmony 上的 Electron 运行时里。整条链路如下：

packages/hoppscotch-selfhost-web   (Vue3 + Vite 前端)
        │  pnpm 构建出静态 Web 产物 dist/
        ▼
scripts/build-ohos-package.cjs     (产物整形 + 运行时环境注入 + 生成 Electron 引导)
        │  同步到 ↓
ohos_hap/web_engine/.../resfile/resources/app/
        ├── main.js        Electron 主进程引导（创建 BrowserWindow，loadFile dist/index.html）
        ├── package.json   runtime 包描述
        └── dist/          Hoppscotch 前端构建产物
        ▼
ohos_hap (OpenHarmony Electron HAP)  →  DevEco Studio / hvigor 打包成 .hap  →  鸿蒙设备

也就是说：Hoppscotch 以 Web kernel 模式运行在 OpenHarmony 版 Electron 的 BrowserWindow 中，优先覆盖 API 调试、集合、环境、历史等 Web 侧能力。

关键适配点

1. OpenHarmony 版 Electron 运行时 ohos_hap 内置了华为开源的「Electron on OpenHarmony」运行时，包括预编译二进制与 Chromium 资源：

   • ohos_hap/electron/libs/arm64-v8a/：libelectron.so、libadapter.so、libffmpeg.so、libc++_shared.so
   • ohos_hap/web_engine/src/main/resources/resfile/：resources.pak、chrome_100/200_percent.pak、icudtl.dat、v8_context_snapshot.bin、snapshot_blob.bin 等

2. 三模块工程结构（见 ohos_hap/build-profile.json5）

   • electron/：entry 入口模块。EntryAbility 继承自 web_engine 导出的 WebAbility（见 EntryAbility.ets），由它拉起 Electron 运行时并加载应用本体。
   • web_engine/：HAR 运行时模块，对外导出 WebAbility / WebWindow 等（见 Index.ets），并通过 jsbindings/ 下的一系列 *AdapterBind.ets 把鸿蒙系统能力（剪贴板、通知、字体、设备信息、打印、文件选择等）桥接给 Electron / Chromium。应用本体 resources/app 也打包在此模块内。
   • chromium/：Chromium 子窗口 / 节点处理等辅助页面。

3. 应用身份（见 ohos_hap/AppScope/app.json5） bundleName = io.hoppscotch.ohos，应用名展示为 Hoppscotch，deviceTypes 为 2in1 与 tablet（见 electron/.../module.json5）。

4. 运行时环境变量注入 前端通过 @import-meta-env 在运行时注入公开环境变量，其变量清单来自根目录 .env.example（该文件必须存在，否则 selfhost-web 的 vite 构建会失败）。打包脚本会把 index.html 里的 import_meta_env_placeholder 占位符替换为真实的 globalThis.import_meta_env（默认指向 https://hoppscotch.io 官方后端，可通过 VITE_* 环境变量覆盖）。

5. 产物整形（OpenHarmony 兼容性处理） Electron 以 file:// 协议从本地加载页面，因此 build-ohos-package.cjs 会：

   • 校验并避免根路径绝对资源引用（/assets/...），改用相对路径；
   • 校验 manifest.webmanifest 不含 OpenHarmony 不兼容的根路径字段；
   • 生成 Electron 主进程引导 main.js：创建 1280×800 的 BrowserWindow，禁用 nodeIntegration、开启 contextIsolation，外链交给系统浏览器打开，并 loadFile('dist/index.html')。

6. 崩溃修复经验（见提交 9d8d70c） 早期 HAP 只打包了 Electron 运行时（libelectron.so / Chromium 资源），缺少应用本体 resources/app（main.js + dist/），导致 Electron 启动后找不到入口、1 秒内 exit(1)，被 appspawn 转成 SIGABRT 崩溃。修复方式即「补齐并提交应用本体」，并为超过 atomgit 10MiB 限制的大文件配置 Git LFS。

---

二、功能支持情况（T0 / T1 / T2）

请先读这一段。 本表按「能力对用户的重要性」分为三档，并对每项如实标注支持状态，全部状态均已在真机上实测确认。状态只有两个：「能用」指纯前端本地能力或承载层已提供对应桥接，已在真机跑通、可正常使用（个别子项受限或某模式下降级的，受限点照实写进说明列）；「未适配」指按平台特点主动不做、或依赖鸿蒙端不存在的外部组件 / 云端后端而做不了的能力。 本项目不是「全 T0、100% 支持」——它本质是把 Hoppscotch 的 Web 版承载进鸿蒙 Electron，因此「本地设计 / 调试 / 管理」主线已完整可用，而**「对任意线上接口直接发请求」受浏览器 CORS 限制**、「账号登录与云同步」依赖云端后端与浏览器回跳，当前实现下不适配。这两点是承载路线固有的取舍，请如实告知使用方。

分级定义

档位	含义
T0｜核心能力	应用能否装起来、跑起来，并完成「设计并调一个 API」这条主线的最小闭环。这一档不通过，应用基本不可用。
T1｜主要能力	日常高频能力：GraphQL、鉴权、Body、脚本、代码生成、导入导出、实时通信等。
T2｜增强 / 云端能力	账号登录、云同步、团队协作，以及依赖外部组件（浏览器扩展 / Agent / 原生网络拦截器）的能力。

状态图例：能用＝在鸿蒙 PC 真机上实际用过、正常（某子项受限或某模式下降级的，受限点写进说明列）｜未适配＝桌面端 / 云端特有或平台没有对应概念的能力，按平台特点主动换了做法或没做，是取舍不是没做完

T0 · 核心能力

能力	状态	说明
应用安装 / 启动	能用	HAP 已在真机实测可安装、可启动；启动即崩溃问题已在提交 9d8d70c 修复（补齐应用本体）。
界面渲染与导航（REST / GraphQL / Realtime / Settings 等面板）	能用	运行于 OHOS 版 Chromium，前端 UI 完整渲染，交互正常。
REST 请求构建（方法 / URL / Query / Headers / Body / 鉴权配置）	能用	纯前端能力，真机实测可用。
REST 请求发送与响应查看	能用	web kernel 模式默认走「浏览器（Browser）拦截器」，受 Chromium 同源策略约束：目标接口开启 CORS、或配置了 Proxy 代理时可正常收发，已在真机实测可用；对未开放跨域的接口会失败。绕过 CORS 的「原生网络拦截器」未桥接（见 T2）。
本地集合 Collections（增 / 删 / 改 / 嵌套）	能用	数据存浏览器本地存储，离线可用，真机实测可用。
环境 Environments（变量 / 密文）	能用	真机实测可用。
历史记录 History	能用	真机实测可用。
设置 / 主题 / 多语言 i18n	能用	真机实测可用。

T0 小结（约 80%）：装 / 启 / 建 / 管理 / 本地数据全部已在真机实测能用；显著的取舍点是「对任意接口发请求」受 CORS 约束，需目标接口支持跨域或自建代理才能稳定收发。

T1 · 主要能力

能力	状态	说明
GraphQL 客户端（Query / Mutation、变量、Headers）	能用	编辑构建可用；发送与 schema introspection 同样受 CORS / 代理约束，满足跨域 / 代理前提时已在真机实测可用。
GraphQL 订阅（Subscription，over WebSocket）	能用	走 WebSocket，对可达端点已在真机实测可用。
鉴权类型（Basic / Bearer / API Key / OAuth 2.0 / AWS Sig / Digest / HAWK 等）	能用	参数配置均可用并已实测；OAuth 2.0 取 token 等需重定向 / 回跳的流程，在 file:// + 无原生网络下受限。
Body 类型（JSON / form-data / x-www-form-urlencoded / GraphQL）	能用	文本类 Body 真机实测可用。
Body 类型（binary / 文件上传）	能用	经系统文件选择，依赖承载层 FilePickerAdapterBind，已在真机实测可用。
预 / 后置脚本（Pre-request / Test，JS 沙箱）	能用	沙箱在 Chromium 内执行，已在真机跑通；测试脚本需先取得响应才能断言，故实际效果受发请求能力影响。
代码生成 Codegen（生成各语言请求片段）	能用	纯前端，真机实测可用。
导入 Import（Postman / OpenAPI / Insomnia / cURL / HAR）	能用	解析为本地数据，真机实测可用。
导出 Export（下载为文件）	能用	触发浏览器下载，落盘由 Electron 下载处理，已在真机实测可用。
实时通信 WebSocket / SSE / Socket.IO / MQTT(over WS)	能用	不依赖原生拦截器，对可达端点已在真机逐项实测可用。
键盘快捷键	能用	已实测可用；壳层对 Backspace 等做了拦截，个别快捷键行为与桌面有差异。

T1 小结：编辑、脚本、代码生成、导入、导出落盘、binary 上传、实时通信（WebSocket / SSE / Socket.IO / MQTT）、GraphQL 订阅、键盘快捷键均已在真机实测可用；GraphQL 请求发送与 OAuth 回跳类鉴权受 CORS / file:// 约束，是承载路线的取舍。

T2 · 增强 / 云端能力

能力	状态	说明
账号登录（Hoppscotch 账号 / 第三方 OAuth）	未适配	依赖云端后端与浏览器重定向回跳，file:// + Electron 壳下不适配，是承载路线的取舍。
云同步（集合 / 环境 同步到账号）	未适配	依赖登录态，随登录一并不适配。
团队 / 工作区 Teams	未适配	依赖登录 + 后端，不适配。
原生网络拦截器（绕过 CORS、直连任意接口）	未适配	第二阶段能力，未桥接到鸿蒙原生网络栈；这是 REST/GraphQL「任意接口」收发受限的根因。
浏览器扩展拦截器	未适配	鸿蒙端无 Hoppscotch 浏览器扩展，平台无对应组件。
Agent 拦截器	未适配	需在本机运行 Hoppscotch Agent 应用，鸿蒙端无对应组件。
Cookie 鉴权 / Cookie 管理	未适配	web kernel 模式默认 cookiesEnabled = false，是当前实现的取舍。
Proxy 代理拦截器	能用	代码已包含 Proxy 拦截器，用户自建 / 指定 proxyscotch 代理后可绕过 CORS 收发，此路径已在真机实测可用；开箱默认不通。
系统集成（外链打开 / 剪贴板 / 通知 / 打印 / 字体等）	能用	外链打开已在 main.js 接管（交系统浏览器）；其余承载层已提供对应 *AdapterBind 适配，Hoppscotch 内的具体调用已在真机实测可用。

T2 小结：账号、云同步、团队依赖云端后端与浏览器回跳，原生 / 扩展 / Agent 拦截器依赖鸿蒙端不存在的外部组件，均按承载路线的取舍未适配；系统集成已在真机实测可用，Proxy 代理在用户自建代理后已实测可用。

总体评估（已在真机实测）

档位	已适配 / 真机实测可用	说明
T0 核心	安装启动、UI、请求构建、集合 / 环境 / 历史 / 设置	主线已跑通可用，REST 收发受 CORS 取舍约束
T1 主要	文本 Body、binary 上传、Codegen、导入、导出落盘、脚本引擎、实时通信、GraphQL 订阅、快捷键	GraphQL 请求发送 / OAuth 回跳类鉴权受 CORS / file:// 取舍约束
T2 增强 / 云端	系统集成已实测可用，Proxy 代理在自建代理后可用	账号 / 云同步 / 团队 / 原生 / 扩展 / Agent 拦截器按承载路线的取舍未适配

一句话结论：本项目作为「本地 API 设计 / 调试 / 集合与环境管理」工具，主线已在真机实测可用、体验完整；「对任意线上接口直接发请求」受浏览器 CORS 限制（需接口开放跨域或自建代理），「账号登录与云端同步」依赖云端后端与浏览器回跳、当前实现下不适配——这些是承载路线固有的取舍，请按上表如实向使用方说明。

---

三、环境准备

工具	版本 / 说明
Node.js	建议 18 LTS 及以上（selfhost-web 构建使用 --max_old_space_size=8192）
pnpm	10.33.2（仓库 packageManager 已锁定；仓库仅允许 pnpm）
Git LFS	必装。libelectron.so、icudtl.dat、dist/**/*.js(.map) 等大文件走 LFS（见 .gitattributes）
DevEco Studio	自带 HarmonyOS SDK、ohpm、hvigor。本工程 compatibleSdkVersion 5.0.5(17)、targetSdkVersion 6.0.2(22)
目标设备	HarmonyOS / OpenHarmony 的 2in1 或 tablet 设备 / 模拟器，架构 arm64-v8a

注意：克隆后请务必拉取 LFS 内容，否则二进制是指针占位、运行必然崩溃：

git lfs install
git lfs pull

---

四、编译与运行

步骤 0 · 安装依赖

# 在仓库根目录
pnpm install

步骤 1 · 构建并同步 Hoppscotch Web 产物到 HAP

pnpm run ohos:sync

该命令本质是带上输出目录环境变量执行 scripts/build-ohos-package.cjs：

• 若 packages/hoppscotch-selfhost-web/dist 不存在 / 含根路径资源 / 设置了 OHOS_HOPPSCOTCH_FORCE_REBUILD=1，会先执行 selfhost-web 的 vite 构建；否则复用已有产物；
• 整形产物 → 注入运行时环境变量 → 生成 main.js 与 package.json；
• 输出到：

  ohos_hap/web_engine/src/main/resources/resfile/resources/app/
  

仓库已提交了一份可用的 resources/app 产物，若只想直接打包可跳过本步；若改动了前端代码，则需重新执行本步同步。

可通过 VITE_* 环境变量覆盖后端地址，例如指向自建后端：

VITE_BACKEND_API_URL=https://your.api/v1 \
VITE_BACKEND_GQL_URL=https://your.api/graphql \
VITE_BACKEND_WS_URL=wss://your.api/graphql \
OHOS_HOPPSCOTCH_FORCE_REBUILD=1 pnpm run ohos:sync

步骤 2 · 打包 HAP（二选一）

方式 A：DevEco Studio（推荐，最稳妥）

1. 用 DevEco Studio 打开 ohos_hap 目录；
2. 等待对 ohos_hap、web_engine、electron 三个模块执行 ohpm install（同步依赖）；
3. 选择 electron entry 模块，连接 2in1 / tablet 设备或模拟器，点击 Run。

签名：build-profile.json5 内的 signingConfigs 指向作者本地 ~/.ohos/config 下的证书。首次在你本机运行需替换为你自己的签名配置（DevEco Studio → Project Structure → Signing Configs，自动签名即可）。

方式 B：命令行

pnpm run ohos:build

该命令执行 scripts/build-ohos-hap.cjs，它会：

1. 先重新同步 Web 产物（步骤 1）；
2. 对 ohos_hap / web_engine / electron 依次执行 ohpm install；
3. 自动查找 hvigorw 与 DevEco SDK（也可用 DEVECO_SDK_HOME 指定），执行 hvigor assembleHap 产出 .hap。

若命令行找不到 hvigor 或 SDK，脚本会给出提示——此时请改用 DevEco Studio 构建。

步骤 3 · 安装运行

把产出的 .hap 安装到设备（DevEco Run 会自动安装；命令行可用 hdc install），桌面上即出现 Hoppscotch 图标，点击启动。应用会在 OpenHarmony 版 Electron 中加载本地 Hoppscotch 前端，默认连接官方后端进行 API 调试（实际可用范围见「二、功能支持情况」）。

---

五、目录速览

ohos_hap/
├── AppScope/                 # 应用级配置（bundleName、应用名 Hoppscotch、图标）
├── electron/                 # entry 入口模块：EntryAbility 继承 web_engine 的 WebAbility
│   └── libs/arm64-v8a/       # 预编译 Electron 运行时 so（Git LFS）
├── web_engine/               # HAR 运行时模块：导出 WebAbility，桥接鸿蒙系统能力
│   ├── src/main/ets/jsbindings/   # *AdapterBind.ets：剪贴板/通知/字体/设备/打印/文件选择… 适配
│   └── src/main/resources/resfile/
│       ├── *.pak / icudtl.dat / *.bin   # Chromium 运行时资源（部分走 LFS）
│       └── resources/app/    # ← Hoppscotch 应用本体（main.js + dist/，由步骤 1 生成）
├── chromium/                 # Chromium 子窗口 / 节点窗口辅助页面
└── build-profile.json5       # HAP 构建与签名配置
scripts/
├── build-ohos-package.cjs    # 构建 selfhost-web、整形产物、注入 env、生成 main.js
└── build-ohos-hap.cjs        # 同步产物 + ohpm install + hvigor assembleHap

---

六、常见问题

• 启动即闪退 / SIGABRT：多半是 resources/app（main.js + dist/）缺失，或 LFS 大文件未拉取（libelectron.so 等仍是指针）。先 git lfs pull，再 pnpm run ohos:sync 确认应用本体已生成。
• 请求一直报跨域 / 发不出去：这是预期内的限制。web kernel 模式默认走浏览器拦截器，受 CORS 约束。请改用开放跨域的接口，或在设置里切到 Proxy 拦截器并指向你自建的 proxyscotch 代理。原生拦截器（彻底绕过 CORS）尚未适配，详见「二、功能支持情况 · T2」。
• 登录 / 云同步用不了：账号体系依赖浏览器重定向回跳与云端后端，当前在 file:// + Electron 壳下基本不可用，属未适配范围。
• vite 构建报缺少 env：确认根目录存在 .env.example（@import-meta-env 以它作为公开环境变量清单）。
• 页面刷新 / 深链路由异常：file:// 加载下如遇 history 路由问题，可在鸿蒙构建目标切换为 hash history，或在 Electron 壳中补路由回退。
• 签名失败：替换为你本机的签名配置（见步骤 2 方式 A 的说明）。

---

七、后续增强点

• 原生网络拦截器（最高优先级）：把请求发送桥接到鸿蒙原生网络栈，绕过 CORS，让「对任意接口发请求」从「有条件可用」升级为「开箱可用」——这是把 T0 收发能力补齐的关键。
• 账号登录与云同步：解决 file:// 下的 OAuth 重定向 / 回跳，打通云端能力（T2）。
• 对齐官方 Tauri 桌面能力：逐步桥接文件选择、外部链接、原生网络、日志与本地存储等。