Eclipse Theia 鸿蒙 PC 适配全记录：在 HarmonyOS PC 上运行完整 IDE 工作台

颜颜yan_

15人浏览 · 2026-09-13 17:03:53

颜颜yan_ · 2026-09-13 17:03:53 发布

文章目录

一、为什么要适配 Eclipse Theia

Eclipse Theia 是一套面向云端和桌面的开源 IDE 框架。它并不是一个只负责显示代码的编辑器，而是把工作区管理、Monaco 编辑器、全局搜索、偏好设置、Git、调试、终端和 VS Code 扩展兼容能力组织成可定制的平台。很多团队基于 Theia 构建行业 IDE、设备开发工具、云端研发环境和内部工程平台，因此它对操作系统的要求也远高于普通网页应用。

把 Theia 带到 HarmonyOS PC，价值不只在于增加一个代码编辑器。更重要的是，它可以检验鸿蒙桌面应用对大型 Electron 工程的承载能力：前端要运行 Monaco 与 Lumino，Node 后端要提供文件系统和工作区服务，主进程要维护窗口及 IPC，搜索、终端和插件体系还会触发本地二进制与子进程。只有这些链路在真机上连续工作，才具备继续建设鸿蒙本地开发工具的基础。

本次适配基于 Eclipse Theia 1.74.0。上游桌面示例由 74 个 @theia 包组成，要求 Node.js 22 及 Electron 42.8.1；鸿蒙真机提供的宿主则是 Electron 37.2.0、Node.js 22.17.0、Node ABI 136，运行平台为 openharmony/arm64。适配没有把 Theia 重写为 ArkUI，也没有改造上游 packages/，而是在仓库内新增 ohos-pc/ 工作区，将原版工作台注入 HarmonyOS Electron HAP，并把平台差异收敛到入口、IPC 兼容层、原生模块回退和组包脚本中。

二、先确定适配路线：保留工作台，替换桌面运行底座

Theia 的渲染层本身适合继续复用。Monaco、Lumino 和各功能视图最终运行在 Chromium 中，如果为了平台迁移把它们全部改写为 ArkUI，不仅工作量巨大，还会失去 Theia 生态现有的命令、贡献点和扩展接口。真正需要处理的是 Electron 主进程、Node 后端及桌面原生依赖。

层次	上游实现	HarmonyOS PC 侧处理
应用入口	Electron 42 `electron-main`	HAP `EntryAbility` + Electron 37 宿主 + `ohos-main.js`
工作台前端	Monaco、Lumino、Theia 前端包	保留 production bundle，由鸿蒙 Electron 的 Chromium 渲染
Node 后端	Express、WebSocket、文件与工作区服务	以 `--no-cluster` 在宿主进程启动，前端继续通过本机端口连接
桌面 IPC	新版 Electron 窗口和标题栏接口	在主进程补齐宿主缺少的 IPC 与窗口选项
原生扩展	`node-pty`、`native-keymap`、`@parcel/watcher`、`keytar` 等	删除 Darwin 产物，按能力提供 OHOS 模块或安全回退
全局搜索	随桌面包携带 ripgrep	用 `ohos-rg.js` 实现 `rg --json` / `--files` 兼容子集
交付形态	桌面 Electron 安装包	`arm64-v8a` 签名 HAP，Bundle Name 为 `com.theia.ohos.pc`

适配后的启动链路如下：

EntryAbility
    └── HarmonyOS Electron 37 Runtime
          └── ohos-main.js
                ├── 安装 Electron IPC 与窗口兼容逻辑
                ├── 拦截不兼容的 Native Addon
                ├── 启动 Theia Node Backend（--no-cluster）
                └── 创建 BrowserWindow
                      └── file://.../index.html?port=<backend-port>
                            └── Monaco + Lumino + Theia Workbench

这条路线保留了原项目的 IDE 观感和前后端协议，也明确接受平台边界：没有 OHOS PTY 时不提供假终端，Plugin Host 无法创建时不把扩展安装写成已经完成，桌面专属的 Keychain、磁盘枚举和原生键盘布局则采用可预期的降级行为。

三、适配工程的目录组织

鸿蒙相关代码集中在 ohos-pc/，原有 packages/、dev-packages/ 和 examples/electron/ 继续作为 Theia 的构建源。这样做可以降低后续同步上游版本的成本，也便于单独审计进入 HAP 的文件和二进制架构。

ohos_theia/
├── packages/                              # 上游 @theia/* 运行时包
├── dev-packages/                          # CLI 与 application-manager 等构建工具
├── examples/electron/                     # 原版 Electron 工作台装配入口
├── README.OpenHarmony_CN.md               # 仓库内鸿蒙适配说明
└── ohos-pc/
    ├── theia-app/
    │   ├── ohos-main.js                   # 鸿蒙 Electron 主进程入口
    │   ├── ohos-native-stubs.js           # Native Addon 兼容与回退
    │   ├── ohos-rg.js                     # 进程内搜索兼容实现
    │   └── package.json                   # 60 个 @theia 包的装配清单
    ├── scripts/
    │   ├── check-env.sh                   # SDK、设备和宿主预检
    │   ├── inject-host.sh                 # 生成 Electron HAP 宿主工程
    │   ├── build-theia.sh                 # 编译并打包工作台
    │   ├── inject-theia.sh                # 注入产物并清理桌面二进制
    │   ├── assemble.sh                    # Hvigor 构建与签名边界处理
    │   └── audit-node.sh / audit-hap.sh   # AArch64 与 HAP 内容审计
    ├── ohos_hap/                          # DevEco/Hvigor 工程及构建产物
    ├── feature-coverage.md                # 工作台能力覆盖清单
    ├── capability-matrix.md               # 宿主版本与真机能力记录
    └── evidence/                          # 真机日志与过程截图

theia-app/package.json 当前选择 60 个 @theia 包进入鸿蒙装配，覆盖工作台、编辑器、工作区、搜索、设置、SCM、调试、终端、扩展市场和 AI 框架等模块。这里的“进入装配”只代表代码被纳入 HAP；是否能够在鸿蒙上完整使用，仍要以真机能力和后文边界为准。

四、HarmonyOS PC 真机核心功能

以下 5 张截图均在 2026 年 8 月 25 日对当前签名 HAP 执行覆盖安装后重新采集。测试设备为 HUAWEI MateBook Pro（HAD-W32），系统版本为 HAD-W24 6.1.0.117，屏幕分辨率为 3120×2080。安装和启动分别返回 install bundle successfully 与 start ability successfully，随后在应用窗口内完成工作台切换、文件打开、搜索和网络查询。

1. 原版 Theia 工作台在鸿蒙桌面启动

启动后进入 Theia Welcome，窗口标题、活动栏、资源管理器、编辑标签和底部状态栏均来自原版工作台。Welcome 页面显示版本 1.74.0，并能识别最近打开的 Desktop 工作区。

在这里插入图片描述

这张界面说明应用已经越过了 HAP Ability、Electron 宿主、Node 后端和前端 WebSocket 连接几个关键阶段。启动页并不是为适配临时制作的探测页面，后续编辑、搜索和设置都在同一个工作台实例中完成。

2. Monaco 打开并编辑沙箱中的真实文件

在工作区中打开 hello.md 后，Monaco 正常显示文件内容、行号、光标和 Minimap。底部状态栏同步给出行列、换行符、UTF-8、缩进和语言模式，标签标题与窗口标题也跟随当前文件变化。

在这里插入图片描述

截图中的文件路径为 /data/storage/el2/base/files/workspace/hello.md，内容由设备沙箱实际读取，并非写在网页中的演示文本。当前版本已经验证文本和 Markdown 文件的打开与编辑；覆盖保存尚未完成独立真机对照，因此不将“编辑器可输入”扩大为“完整保存链路已经适配”。

3. 不依赖桌面 ripgrep 的工作区搜索

上游 Theia 会启动随桌面包分发的 rg 二进制，但 macOS 构建机上的 ripgrep 无法进入 arm64-v8a HAP。适配层在主进程拦截对应的 child_process.spawn，使用 ohos-rg.js 输出 Theia 所需的 JSON 搜索事件。

在这里插入图片描述

本次在真机输入 ohos-search-token-74，搜索面板返回 1 result in 1 file，并在 Monaco 中定位和高亮同一行。这个结果验证了搜索输入、进程兼容层、文件遍历、结果解析和编辑器定位之间的完整链路。

4. 偏好设置页能够读取工作台配置

Settings 页面按 User 与 Workspace 两个作用域组织配置，常用项中可以看到 Auto Save、Font Size、Font Family、Tab Size 和 Render Whitespace。页面左侧仍保留完整的 Text Editor、Workbench、Window、Features、Application、Security、AI Features 和 Extensions 分类。

在这里插入图片描述

偏好设置由 Theia 的 preference service 提供，并非鸿蒙侧额外拼出的静态表单。它能够在当前工作台中打开和检索，为后续按设备保存编辑器、窗口及扩展配置提供了统一入口。

5. Open VSX 扩展市场能够返回在线结果

扩展视图连接 Open VSX Registry 后，以 Python 为关键词发起查询，真机返回 Python Language、Python Debugger 等扩展条目，下载量、评分和安装入口均正常渲染。这同时验证了 HAP 网络权限、Registry 请求和扩展列表组件。

在这里插入图片描述

需要区分“市场浏览”和“扩展安装运行”。当前截图证明在线检索和列表浏览可用，但安装后启动扩展仍依赖 Plugin Host；由于鸿蒙应用沙箱中的 child_process.fork 会落到 appspawn EACCES，完整扩展安装与语言服务不能据此认定为已经跑通。

五、适配过程中遇到的主要困难

难点一：上游 Electron 版本高于鸿蒙宿主

上游 examples/electron 面向 Electron 42.8.1，真机宿主却是 Electron 37.2.0。直接使用构建出的 electron-main.js 会在窗口初始化阶段触发 SIGSEGV，一些标题栏、窗口材质和 IPC 接口也不存在。适配没有尝试在 HAP 内再携带一套 Electron，而是以真机宿主为准新增 ohos-main.js，过滤不支持的窗口选项，补齐 Theia 启动所需的 IPC，再按 file://index.html?port= 约定连接后端。

难点二：Theia 不只是一个前端页面

如果只把 index.html 和 bundle.js 放进 HAP，Welcome 页面背后的文件、工作区和搜索服务都无法工作。Theia 前端依赖 Node 后端提供的 WebSocket 服务，后端又会根据桌面环境选择集群与子进程模式。当前入口显式加入 --no-cluster，在宿主进程中启动 lib/backend/main.js，等端口就绪后再创建工作台窗口，避免前端先启动却一直等待后台服务。

难点三：桌面 Native Addon 不能直接复用

node-pty、native-keymap、@parcel/watcher、keytar 和 drivelist 都依赖平台二进制。Darwin 的 .node 文件即使被 npm 安装，也不可能由鸿蒙 AArch64 进程加载。注入脚本会删除 .node、prebuilds、macos-trash、桌面 rg 等文件，并通过 audit-node.sh 检查 HAP 原生库必须是 ELF64 AArch64。没有稳定 OHOS 实现的能力由 ohos-native-stubs.js 接管，避免启动阶段因动态加载失败而退出。

难点四：全局搜索必须保持 Theia 原有协议

搜索功能不能简单改成“读取一个文件再查字符串”。search-in-workspace 期待 ripgrep 的 --json 输出，并需要文件列表、匹配位置、上下文和取消行为。ohos-rg.js 实现了当前工作台实际使用的 rg --json 与 --files 子集，使上层服务无需理解鸿蒙平台差异。真机命中结果证明这一兼容层已经进入真实调用路径。

难点五：Plugin Host 与终端受应用沙箱限制

VS Code 扩展通常由独立 Plugin Host 运行，Theia 通过 child_process.fork 拉起它；终端则需要能够创建伪终端并管理子进程。当前真机中，Plugin Host 创建会因 appspawn EACCES 失败，OHOS pty.node 虽然能够被加载，但继续进入 PTY 流程会导致进程退出。因此适配版本保留扩展市场浏览和终端相关装配，却没有提供会误导用户的空终端，也没有把扩展列表能显示等同于语言扩展可运行。

难点六：HAP 组包需要同时控制体积与二进制来源

Theia 前端 bundle 约 22 MB，完整签名 HAP 约 294 MB。构建脚本必须跳过开发机 Electron 42 下载，只注入 lib/frontend、lib/backend 与必要资源，同时删除 source map 和桌面专属二进制。audit-hap.sh 在组包后再次检查工作台入口、bundle 和原生库，防止“本机可以构建”掩盖“设备无法加载”的问题。

六、关键适配改动

1. 新增独立的鸿蒙主进程入口

ohos-main.js 负责设置 THEIA_OHOS 环境、修正用户数据目录、安装进程异常日志、创建兼容版 BrowserWindow，并补齐 GetTitleStyleAtStartup 等 Theia Electron 前端需要的 IPC。窗口仍加载上游生成的 Theia 页面，不维护第二套鸿蒙 UI。

2. 把平台依赖集中到 Native Stub

主进程对 Module._load 和 process.dlopen 做受控拦截，只处理明确的原生模块请求。键盘布局、文件监听、钥匙串和磁盘枚举根据平台能力返回降级实现，避免把 OpenHarmony 分支散落到 74 个上游包中。

3. 为工作区搜索提供进程内兼容实现

ohos-main.js 识别 Theia 发起的 ripgrep 子进程参数后，将调用转交 ohos-rg.js。它输出与 ripgrep JSON 模式兼容的事件，前端搜索视图和结果跳转因此可以继续复用原有代码。

4. 构建阶段只注入可运行产物

build-theia.sh 先执行 TypeScript 编译，再调用 application-manager 生成 production bundle；theia-build-workbench.js 覆盖 Electron 下载阶段，避免产生与 HAP 无关的桌面运行时。inject-theia.sh 将工作台复制进宿主资源目录，并把应用入口和标签改为 Theia。

5. 建立 Native 与 HAP 双重审计

注入前后均检查原生文件架构，组包完成后再从 HAP 层确认入口、前端 bundle 和动态库。签名材料与代码仓库分离，未配置签名时脚本会明确停在 unsigned 产物或签名边界，不会把不可安装的包描述为最终交付件。

七、编译、安装与启动

1. 准备项目依赖

项目要求 Node.js 22 或更高版本，并统一使用 npm：

npm install

首次 UI 验证前需要生成浏览器或 Electron bundle。仅执行 npm run compile 只会编译 TypeScript，不会更新前端包：

npm run build:electron

2. 构建 HarmonyOS PC 版本

准备 DevEco Studio、API 22 SDK 与 HarmonyOS Electron 宿主后，在仓库根目录执行：

export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home
export PATH="$JAVA_HOME/bin:$PATH"
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk

bash ohos-pc/scripts/check-env.sh
bash ohos-pc/scripts/inject-host.sh
bash ohos-pc/scripts/build-theia.sh
bash ohos-pc/scripts/inject-theia.sh
bash ohos-pc/scripts/assemble.sh

签名产物位于：

ohos-pc/ohos_hap/electron/build/default/outputs/default/
└── electron-default-signed.hap

当前真机安装包约 294 MB，目标 ABI 为 arm64-v8a。如果本机尚未配置签名，需要先在 DevEco Studio 的 Signing Configs 中生成与设备匹配的调试签名，再重新执行 HAP 构建。

3. 安装并启动

hdc list targets
hdc install -r \
  ohos-pc/ohos_hap/electron/build/default/outputs/default/electron-default-signed.hap
hdc shell aa start -a EntryAbility -b com.theia.ohos.pc

冷启动时需要解析体积较大的前端 bundle。窗口出现后，应看到标题为 Theia 的原版工作台，而不是宿主能力探测页。可使用以下脚本同时执行安装、启动和 TheiaOHOS 日志采集：

bash ohos-pc/scripts/install-and-capture.sh

八、当前可用范围与能力边界

当前版本已经在 HarmonyOS PC 真机确认以下能力：

签名 HAP 可以覆盖安装，EntryAbility 可以启动；
Electron 37 宿主、Node 22 后端和 Theia 前端能够完成启动；
Welcome、活动栏、侧栏、编辑标签和状态栏正常显示；
系统目录选择器、Desktop 工作区和 Workspace Trust 可以进入；
Monaco 可以打开并编辑文本、Markdown 和 Python 文件；
工作区搜索能够通过进程内 rg 兼容层返回结果并定位到编辑器；
Settings、Keyboard Shortcuts、Problems、Output、Outline、SCM 等工作台视图可以打开；
Open VSX Registry 可以联网查询并展示扩展列表；
沙箱用户数据和工作区文件可以读取，HAP 已声明网络权限。

以下能力仍属于未适配或未完成行为级验证：

覆盖保存尚未做独立的磁盘前后内容对照；
node-pty 在当前宿主上不能稳定完成 PTY 创建，终端不可用；
Plugin Host 受 appspawn EACCES 限制，扩展安装、语言服务和扩展运行未闭环；
调试适配器和真实调试会话尚未验证；
AI 功能默认关闭，也没有配置模型服务，不属于本次真机通过项；
Markdown 预览、Timeline、远程开发、WSL、Dev Container 和协作能力尚未适配；
native-keymap、keytar、drivelist 等桌面原生能力当前使用降级实现。

九、总结

Theia 的 HarmonyOS PC 适配已经完成从上游 TypeScript 工程构建、原版工作台注入、Electron HAP 组包签名，到真机安装启动的主链路。更关键的是，本次真机操作不止停留在 Welcome 页面：Monaco 打开了设备沙箱中的真实文件，工作区搜索通过 OHOS 兼容层返回命中结果，偏好设置能够读取工作台配置，Open VSX 也完成了在线扩展查询。

这次适配说明，大型 Electron IDE 迁移到 HarmonyOS PC 时，最有效的方式不是重写全部界面，而是保留稳定的前端与服务协议，把版本差异、Native Addon、进程模型和 HAP 交付约束集中到平台层处理。同时，适配结果必须按用户路径核验：界面出现、模块加载和功能闭环是三个不同层次。当前版本已经具备可继续迭代的鸿蒙 Theia 工作台基础，后续应优先解决 Plugin Host 与 PTY，再完成保存、语言服务、调试和扩展安装等开发闭环。

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_theia

环境搭建文章：https://blog.csdn.net/lbcyllqj/article/details/161286249?sharetype=blogdetail&sharerId=161286249&sharerefer=PC&sharesource=lbcyllqj&spm=1011.2480.3001.8118