欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

开源鸿蒙PC移植实录:在鸿蒙桌面端跑起完整的 NetBeans IDE

项目仓库(AtomGit):https://atomgit.com/OpenHarmonyPCDeveloper/ohos_netbeans_ide

一、为什么挑 NetBeans 来做移植

我在鸿蒙 PC 上写 Java 一直是个空缺。不是没有编辑器,而是没有一个能真正干活的 IDE:能建工程、能编译、能断点、能用 Git、能装插件。市面上有一些方案,要么是网页编辑器套一层壳,要么是远程连到另一台机器。我想要的不是这些,我想验证一件事——鸿蒙 PC 到底能不能直接承载一个重量级的传统桌面软件。

选 Apache NetBeans 29 是因为它足够"难缠"。它是一门老牌 Java IDE,界面全部由 Swing 绘制,而 Swing 的 XAWT 后端必须连接 X11;它的构建系统、调试器、插件容器全都长在 JVM 上。换句话说,只要拆掉其中一环,软件不是"打开就闪退",就是"打开了但什么也干不了"。

所以这个项目从一开始就定了一条验收规矩:**不看界面能不能显示,看能不能创建一个 Java 工程、打断点看到变量、用 Git 提交一次代码。**界面出现只是入场券,业务闭环才算数。

二、整体链路

现在跑在鸿蒙 PC 上的 NetBeans 由三层组成,全部在应用沙箱内,不依赖系统级 X11 服务,也不修改鸿蒙桌面环境:

ArkUI XComponent
      ^
      | RGBA 帧缓冲
      |
Native Presenter <---- XWD / Xvfb ---- NetBeans Swing / AWT
      ^                                  |
      |                                  | X11
ArkUI 键鼠 / IME                        v
      +---- Native input bridge ----> XTest

NetBeans -> 应用私有 OpenJDK Zero 21 -> Java 模块与 AWT
         -> 应用私有 X11 运行时
         -> 内容哈希启动缓存 + 持久工程索引
  • ArkTS 宿主:EntryAbility 加一个 XComponent 表面,负责显示、输入事件、输入法桥和剪贴板桥。
  • 原生层:以 Native Child Process 启动 Xvfb、X11 客户端和 JVM,持有运行时生命周期。
  • Java 层:就是原始的 NetBeans 29,没有用 ArkUI 重写任何界面。

三、真正卡住人的四个问题

1. HotSpot 起不来,只能换 VM

第一次把 JDK 塞进 HAP,java 进程秒退。日志指向 mmap:HarmonyOS 内核不允许申请匿名可执行映射,RX 和 RWX 都返回 EINVAL。HotSpot 的 JIT 代码缓存天生需要可执行内存,这条路直接堵死。

我的处理不是打补丁糊过去,而是换 VM 实现:保留 BellSoft JDK 21 的官方模块和 AWT 本地库,只把 libjvm.so 换成用 OpenHarmony SDK 交叉编译的 OpenJDK Zero VM。Zero 是纯解释执行,不申请可执行内存,代价是慢,换来的是 NetBeans 的 Java 代码一行不改就能跑起来。

这里还有两个不那么显眼的坑:fontmanager 必须用 DT_NEEDED 直接链上 XAWT 库,否则会报 AWTFontMinByte1 查找失败,所有中文都显示成方块;libjava.so 要做 UTF-8 桥接,否则中文文件名和 zh_CN 区域设置会错乱。

2. 没有 X11 服务,那就自带一个

XAWT 必须连 X11,所以我让应用在私有目录里自己跑一个 Xvfb,后备帧缓冲固定 1280×800,用 -nocursor 启动——光标由宿主自己绘制,否则屏幕上会出现两个大小不一的指针。

画面这边,Xvfb 把屏幕写成 XWD 帧文件,原生 Presenter 线程读这个文件,解析头部,按 stride 逐行转成 RGBA,再按 ArkUI 表面的宽高比算视口(保证不拉伸),最后锁 buffer 提交到 Surface。Presenter 只在内容变化时提交,空闲时约 10Hz 轮询,有活动时 33ms 一帧。每个 X11 显示都使用新生成的 MIT-MAGIC-COOKIE-1 认证,不对外暴露。

3. 输入是一条完整的往返链路

XComponent 收到的是 ArkUI 的指针、按键、滚轮事件,NetBeans 要的是 X11 事件,中间隔着两套模型:键码编号不同,滚轮方向不同,触控板给的是高频增量。

实际链路是:ArkTS 侧归一化事件后调 native 接口 → 通过应用私有 Unix datagram socket 送到 x11-input 客户端 → 客户端用 XTest 注入 Xvfb 的显示。滚轮和触控板的增量先在 axis_scroll.h 里累积到 12 个单位再发,否则高频抖动会让编辑器滚动条乱跳。

4. 路径、缓存和索引

桌面版 NetBeans 默认把配置写到 ~/.netbeans,沙箱里没有这个路径;改成应用私有目录后,又出现新问题——HNP 每次重装时间戳都会变,NetBeans 判定模块失效,每次都重建索引,冷启动要几分钟。

解决办法是"内容哈希 + 独立索引":把发行版内容算出的 sha256 写进 .harmonyos-content-sha256,缓存按哈希分目录,内容相同就复用;工程索引单独放在 netbeans-project-index,跨 HNP 版本保留。

四、核心代码

4.1 ArkTS 侧:XComponent 就是那块显示器

XComponent({ id: 'netbeans-x11', type: XComponentType.SURFACE, libraryname: 'netbeans_display' })
  .width('100%')
  .height('100%')
  .focusable(true)
  .focusOnTouch(true)
  .onFocus(() => {
    this.surfaceFocused = true;
    this.updateImeGeometry();
    if (display.inputFocused()) this.inputMethod?.focus(this.getUIContext());
  })
  .onBlur(() => {
    this.surfaceFocused = false;
  })

表面旁边还挂了一个 1×1 的透明 TextArea 和 HarmonyInputMethod.ets,专门接管中文输入法的组合与上屏。原因很直接:X11 客户端拿不到鸿蒙的系统 IME 事件,只能由宿主转一次。

4.2 Presenter:把 XWD 帧搬上 Surface

以下节选自 harmonyos/entry/src/main/cpp/netbeans_display.cpp,省略了 buffer 合法性校验与状态上报:

if (snapshot.capture(frame)) {
    needsPresent = true;                 // 只有 XWD 内容变化才需要重画
}
if (needsPresent) {
    frame = snapshot.frame();
    OHNativeWindowBuffer *buffer = nullptr;
    if (OH_NativeWindow_LockBuffer(window, {}, &buffer) == 0) {
        const BufferHandle *handle = OH_NativeWindow_GetBufferHandleFromNative(buffer);
        copier.copy(frame, static_cast<uint8_t *>(handle->virAddr),
                    handle->width, handle->height, handle->stride, true);
        if (OH_NativeWindow_UnlockAndFlushBuffer(window) == 0) {
            needsPresent = false;        // 提交成功才清标志,失败下轮重试
        }
    }
}

4.3 键码映射:两套编号必须显式对齐

static KeySym keysym(int code) {
    if (code >= 2017 && code <= 2042) return XK_a + code - 2017;   // A-Z
    if (code >= 2000 && code <= 2009) return XK_0 + code - 2000;   // 0-9
    switch (code) {
        case 2054: return XK_Return;
        case 2055: return XK_BackSpace;
        case 2070: return XK_Escape;
        case 2072: return XK_Control_L;
        case 2073: return XK_Control_R;
        case 2047: return XK_Shift_L;
        case 2074: return XK_Caps_Lock;
        default: return NoSymbol;
    }
}

映射完成后用 XTestFakeKeyEvent 注入。这里必须保证按下与抬起成对发送,少发一个抬起事件,Ctrl 就会一直"粘住",整个 IDE 的快捷键都会失灵。

五、构建与运行

构建分为四步,全部在 POSIX shell 下执行(Windows 建议用 WSL2 或 Git Bash):

# 1. 目标架构(x86_64 模拟器为例)
export OHOS_TARGET=x86_64-linux-ohos
export OHOS_ARCH=x86_64
export OHOS_ABI=x86_64

# 2. 交叉编译 X11 与 OpenJDK Zero
python3 harmonyos/x11/build.py
sh harmonyos/java-zero/build.sh

# 3. 交叉编译 JNA 原生资源
python3 harmonyos/jna/build.py

# 4. 打包 HNP 并内嵌进 HAP
sh harmonyos/build-hnp.sh /path/to/x86_64-musl-jdk.tar.gz /path/to/netbeans

安装启动:

hdc install -r harmonyos/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.gouxi.engineering

这里提醒一个很容易踩的坑:看 HAP 体积。x86_64 完整包约 724 MB,arm64-v8a 约 638 MB。如果你打出来的只有 1.7 MB,说明 HNP 根本没嵌进去,装到设备上会以解压失败被拒绝,而不是给你一个明确的报错。

六、跑起来是什么样

以下截图来自 x86_64 的鸿蒙 PC 模拟器(127.0.0.1:5555),不是历史 ARM64 图。

鸿蒙PC上创建 Java Ant 工程

创建 JavaApplication1 后,项目树、源码包、编辑器和导航器全部正常加载,中文菜单完整。

鸿蒙PC上 Ant 构建运行输出 DEBUG_OK=42

Ant 真实调用 javac 编译并运行,输出窗口打印 DEBUG_OK=42。故意写错一行源码,会给出真实的 javac 错误信息,而不是被吞掉。

鸿蒙PC上断点调试 value=41 变为 result=42

断点在 JavaApplication1.java:7 命中,变量面板显示 value = 41;单步之后 result = 42,编辑器行内同步显示变量值——调试器是真的在跑,不是动画。

鸿蒙PC上 Git 双栏 Diff

把 41 改成 40 后,Diff To HEAD 以左右双栏展示提交版本和工作区内容,Git 集成完整可用。

鸿蒙PC上 Gradle 9.9.0 测试通过

用一个 Java 21 + Groovy + JUnit 5 的真实 Gradle 工程验收:在 Gradle Tasks 里跑 clean 和 test,测试 JVM 真正启动,IDE 显示 1 个测试通过。这里要注意,IDE 的 Build 命令带了 -x check,所以"Build 成功"不等于测试跑过了,必须单独执行 Test 才算数。

鸿蒙PC桌面窗口模式

窗口模式下最大化、还原、最小化、任务栏恢复都正常,没有黑边。顺带一提,13 个顶级菜单(文件、编辑、视图、导航、源、重构、运行、调试、性能分析、团队开发、工具、窗口、帮助)加载的都是 NetBeans 的真实命令。

七、迁移能力分级:T0 / T1 / T2

按仓库 README 的规范,开源软件迁移能力分三档,后一档建立在前一档的验收结果上:

阶段验收目标本项目状态
T0 基础可用能编译、安装、启动并显示原应用双架构通过:HNP/HAP 构建签名、安装启动、原始 Swing 主窗口、菜单、窗口最大化还原、基础键鼠输入
T1 核心业务可用能完成 IDE 的主要开发任务双架构主链路通过:工程创建编辑、Java Ant、Gradle、Maven、Web、查找替换、项目属性、插件管理器、调试与 Git
T2 PC 增强与完整度补齐系统集成、工具链与性能边界持续完善中:中文 IME 候选窗、触控板细粒度滚动、持久工程索引、窗口与剪贴板路径

这三档的价值在于把"能装能起"和"能干活"分开了。很多人做移植止步于 T0——窗口出来了,菜单点得动,就宣布成功。但只要真的建一个工程就原形毕露:编译不通过、断点不生效、Git 不认仓库。T1 才是一个移植项目该有的及格线。

八、已知限制

我不打算写"完美适配"。下面这些是当前真实状态:

  • Web 工程首次激活需要重启 HAP 绕行,还没修掉;
  • x86_64 模拟器的键盘面板保持 0x0,中文候选窗观察不到,文本客户端已通过,但完整 IME 模式仍属实验性;
  • 触控板滚动的累积逻辑已在目标端通过测试,但真实物理触控板的方向与加速度还需要硬件复核;
  • 启动性能受 Zero VM 解释执行和设备内存压力影响,冷启动明显慢于桌面版,缓存启动仍待优化;
  • PHP、Node、C/C++ 等模块能看到入口,但不等于工具链可用,不能凭"模块可见"就对外宣称支持。

把这些边界写清楚,比写一句"全面适配"有用得多——后来的人照着做,才不会被假象误导。

九、仓库与参与

代码托管在 AtomGit 的 PC 仓:

README.OpenHarmony_CN.md 里写了完整的环境准备、交叉编译、HNP/HAP 打包、签名配置和安装运行步骤,包括目标 JDK 怎么选、签名材料为什么不能进仓库、HNP 不随仓库分发的处理方式。想复现的话按那份文档走一遍就行。

开源鸿蒙的 PC 生态现在最缺的不是"更多应用上架",而是有人肯把一个复杂软件真正啃下来,把过程完整地记下来。NetBeans 这个项目走通的每一条弯路——换 VM、自带 X11、输入转发、缓存策略——都可以直接套到其他 Java 桌面软件、Electron 应用或者 Qt 应用上。如果你也在做类似的事,欢迎到 PC 社区来交流。

Logo

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

更多推荐