Cordova 应用鸿蒙化实战：用 hcordova 把 Web 应用跑在 OpenHarmony 模拟器上

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

Cordova 应用鸿蒙化实战：用 hcordova 把 Web 应用跑在 OpenHarmony 模拟器上

本文记录了使用华为 CPF-Cordova 团队开源的 hcordova 命令行工具，将一个标准 Apache Cordova 应用创建、添加 OpenHarmony 平台、构建 HAP 并最终运行到 HarmonyOS 模拟器上的完整过程。 包含 Cordova 框架介绍、hcordova 与 cordova-openharmony 的架构关系、逐步操作记录、构建验证和踩坑复盘。所有步骤均在本机（macOS + DevEco Studio）实际执行验证。

一、背景

1.1 Apache Cordova 简介

Apache Cordova（前身是 PhoneGap）是最老牌的混合应用（Hybrid App）框架，比 React Native（2015）、Flutter（2017）都要早。它的核心思想非常简单：

用系统自带的 WebView 加载本地 HTML/CSS/JavaScript，再通过一层"桥接"（Bridge）让 JS 能调用设备原生能力。

它的架构可以概括为三层：

Cordova 的生态核心是插件：相机、定位、文件、网络状态等设备能力都通过 cordova-plugin-* 插件提供，Web 层调用方式统一：

// Web 层调用原生相机（伪代码）
navigator.camera.getPicture(successCallback, errorCallback, options);

凭借"Web 技术栈 + 插件生态"这两个特点，Cordova 至今仍有大量存量应用在维护，这也是华为团队愿意为它做鸿蒙化的原因——让存量 Cordova 应用几乎零成本迁移到鸿蒙。

1.2 hcordova 与 cordova-openharmony：两个关键仓库

鸿蒙化 Cordova 由CPF-Cordova 团队维护，涉及两个仓库（已同步到 AtomGit）：

架构关系：

hcordova (CLI, 对标 cordova@13.0.0)
│ create / platform add ohos / plugin add
▼
cordova-openharmony (@cordova-ohos/ohos, 平台 HAR 包)
│ 生成鸿蒙壳工程 harmonyos/
▼
鸿蒙壳工程 (EntryAbility + CordovaWebView + NAPI 桥接层)
│ Web 层通过 ArkWeb 加载 www/
▼
OpenHarmony / HarmonyOS 设备

hcordova 的设计哲学是最小侵入：它只在 platform add ohos 时接管平台生成逻辑（自动拉取 cordova-openharmony、处理 openssl 依赖、渲染 43 个模板文件），其余 create/plugin 命令直接转发给原版 cordova CLI 执行。所以安装 hcordova 前必须先全局安装 cordova。

1.3 适配目标

二、适配路线图

整个迁移分为 4 个阶段：

第 1 阶段：环境准备 ── 安装 cordova + hcordova CLI
第 2 阶段：项目初始化 ── hcordova create 生成 Cordova 工程骨架
第 3 阶段：平台添加 ── hcordova platform add ohos 生成鸿蒙壳工程
第 4 阶段：构建与运行 ── hvigorw 构建 HAP → 签名 → 模拟器运行

三、逐步适配过程

第 1 阶段：环境准备

基础环境要求（macOS 实测版本）：

安装命令：

# 先装原版 cordova（hcordova 底层会调用它）
npm install -g cordova

# 再装鸿蒙 CLI
npm install -g hcordova

# 验证
hcordova -v # 1.0.7
cordova -v # 13.0.0

踩坑 1：直接执行 hcordova create 会报 /bin/sh: cordova: command not found。 根因：hcordova 的 create 命令是转发给原版 cordova CLI 执行的（见 hcordova 源码 src/base-cli.js 的 executeCordovaCommand），它自己不带 create 实现。 解法：npm install -g cordova 后重试即可。

第 2 阶段：项目初始化

hcordova create MyApp com.nutpi.MyApp MyHarmonyApp
cd MyApp

生成标准 Cordova 工程结构：

MyApp/
├── config.xml # Cordova 工程配置（应用名、包名、版本、白名单）
├── www/ # Web 业务代码（index.html / css / js / img）
├── package.json
└── hooks/ # 构建钩子脚本

config.xml 关键内容：

<widget id="com.nutpi.MyApp" version="1.0.0">
<name>MyHarmonyApp</name>
<content src="index.html" />
<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
</widget>

这个文件后续会被解析进鸿蒙工程的 entry/src/main/resources/rawfile/config.xml，作为运行时的应用配置源。

第 3 阶段：添加 OHOS 平台

hcordova platform add ohos

这一步是 hcordova 真正干活的地方，实际执行了三件事：

成功后目录结构：

MyApp/
├── harmonyos/ # 鸿蒙壳工程（DevEco 可直接打开）
│ ├── AppScope/ # 应用级配置（bundleName 等）
│ ├── entry/ # 主模块（EntryAbility + CordovaWebView）
│ ├── cordova/ # @cordova-ohos/ohos 平台 HAR
│ │ ├── libs/ # arm64-v8a / x86_64 预编译 so
│ │ └── src/main/cpp/ # NAPI 桥接层 C++ 源码
│ ├── build-profile.json5 # targetSdk 5.0.5(17) / compatible 5.0.0(12)
│ └── oh-package.json5
├── oh-plugins/ # 鸿蒙专用插件目录
├── www/ # Web 代码（不变）
└── config.xml

cordova-openharmony 的原生层构成（查看 harmonyos/cordova/src/main/cpp/ 源码目录）：

可见鸿蒙版并非简单把 Android WebView 换成 ArkWeb，而是用 C++ (NAPI) + ArkTS 完整重写了 Cordova 的原生层协议。

验证平台已添加：

hcordova platform ls
# HarmonyOS (installed)

第 4 阶段：构建与运行

4.1 hcordova build ohos 的真相

hcordova build ohos
# Please use the "hvigorw" command tool of HarmonyOS to build app

hcordova 对 ohos 平台的 build/run 命令不做任何实际构建——查看其源码 base-cli.js 第 1186-1188 行，它只打印提示，让你用 hvigorw 或 DevEco。README 4.1 节也是同样表述：“项目构建成功后，推荐使用 DevEco 进行开发和调试，当前命令行工具不支持开发调试”。

所以命令行构建需自己调用 DevEco 内置的 hvigorw。

4.2 hvigorw 命令行构建

cd MyApp/harmonyos

# 配置环境（hvigorw/ohpm/node 均在 DevEco 安装目录内）
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export PATH="/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:\\
/Applications/DevEco-Studio.app/Contents/tools/node/bin:\\
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:$PATH"

# 安装依赖
ohpm install –all

# 构建 HAP
hvigorw assembleHap –mode module -p product=default –no-daemon

构建输出：

> hvigor Finished :entry:default@CompileArkTS… after 5 s 967 ms
> hvigor Finished :entry:default@PackageHap… after 456 ms
> hvigor WARN: Will skip sign 'hos_hap'. No signingConfigs profile is configured in current project.
> hvigor BUILD SUCCESSFUL in 19 s 995 ms

41 tasks in total: 41 executed, 0 up-to-date

产物：entry/build/default/outputs/default/entry-default-unsigned.hap

仅有两类 WARN（无 ERROR）：SplashScreen 组件部分 API 在 2in1 设备不可用、ArkTS 异常处理提示，均不影响运行。

4.3 签名与模拟器运行

HAP 默认未签名。最简单的方式是 DevEco Studio 自动签名：

应用即安装到模拟器并启动：ArkWeb 加载 www/index.html，deviceready 事件正常触发，标准 Cordova 示例页（Apache Cordova 设备信息页）在鸿蒙模拟器上正常运行。

踩坑 2：模拟器上如遇安装/签名失败，可参考"SDK 模板 profile 手动签名"方案（hdc shell bm get –udid 取 UDID → 基于 UnsgnedDebugProfileTemplate.json 改 bundle-name 与 device-ids → hap-sign-tool.jar 签 profile → 签 HAP）。模拟器无需真机 UDID 备案，SDK 自带材料自签即可。

四、完整架构对照

4.1 cordova-android vs cordova-openharmony

4.2 Web 层零改动验证

www/ 目录在 platform add ohos 前后完全没有被修改。cordova.js 由平台包在构建时注入鸿蒙工程，Web 层调用 cordova.exec() 的方式与 Android/iOS 完全一致——这正是 Cordova "一次编写、多端运行"承诺在鸿蒙上的延续。

五、关键决策说明

决策 1：hcordova 只接管平台层，其余转发原版 cordova

hcordova 没有fork 整个 cordova CLI，而是只实现 platform add ohos 的鸿蒙分支，create/plugin 等命令转发给原版 cordova@13.0.0。好处是紧跟上游生态（插件解析、hooks 机制全部复用），代价是用户必须同时安装两个 CLI（踩坑 1 即来源于此）。

决策 2：C++ NAPI 实现桥接层而非纯 ArkTS

cordova-openharmony 的桥接层（消息队列、插件管理、网络）用 C++ 实现，通过 NAPI 暴露给 ArkTS 容器层。桥接协议是高频调用路径，C++ 实现能显著降低消息序列化开销；同时 openssl 直接以源码形式打进工程，避免二进制依赖分发问题。

决策 3：构建走 hvigorw 而非 CLI 内置

hcordova 放弃在 CLI 内实现鸿蒙构建，直接引导用户使用 hvigorw/DevEco。这避免了 CLI 重复实现 SDK 定位、签名、增量编译等复杂逻辑，也与鸿蒙官方工具链保持一致。

六、测试与验证

测试环境

版本获取方式：

验证要点

七、运行效果

模拟器运行标准 Cordova 欢迎页，设备信息由 CoreHarmony 插件注入：

• 应用包名 com.nutpi.MyApp，显示名 MyHarmonyApp
• ArkWeb 容器加载 rawfile 内置页面，deviceready 正常触发
• hdc list targets 确认模拟器 127.0.0.1:5555 在线

可用以下命令截取模拟器画面：

hdc shell snapshot_display -f /data/local/tmp/cordova_ohos.jpeg
hdc file recv /data/local/tmp/cordova_ohos.jpeg .

八、遗留问题与改进方向

踩坑复盘

已知问题

未来优化

• CLI 集成 hvigorw 构建：hcordova 后续版本若在 ohos 分支内自动定位 DevEco 工具链并调用 hvigorw，可闭合"create → build → run"命令行全流程
• 插件生态覆盖度：OHOS 插件从 CPF-Cordova 组织获取，存量项目常用插件的鸿蒙覆盖情况需逐一评估，未覆盖的需自行适配（参照 cordova-plugin 开发规范 + TsCordovaPlugin 接口）

九、总结

把存量 Cordova 应用迁移到鸿蒙，核心路径可以概括为三步走：

1. 换容器 ── hcordova platform add ohos 生成 ArkWeb 壳工程，www/ 零改动
2. 保契约 ── C++ 桥接层完整复刻 cordova.js 的 exec 协议与消息队列
3. 走工具 ── 构建签名交给 DevEco/hvigorw 官方工具链，CLI 不重复造轮子

对开发者而言，迁移成本几乎只有"装两个 CLI + 跑一次 platform add"——www/ 下的 Web 业务代码、插件调用方式（navigator.* / cordova.exec）完全不变。Cordova 这个 2009 年诞生的框架，通过华为团队的桥接层重写，在 OpenHarmony 上焕发了新的生命力。

参考文档

• hcordova 仓库（AtomGit）
• cordova-openharmony 仓库（AtomGit）
• Apache Cordova 官方文档
• HarmonyOS 应用开发指南 – 命令行工具
• CPF-Cordova 插件组织

本项目基于 Apache License 2.0 开源。