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 能调用设备原生能力。

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

层	内容	说明
Web 层	www/ 目录下的 HTML/CSS/JS	应用业务代码，一次编写
桥接层	cordova.js + NativeToJsMessageQueue	JS↔原生的消息队列与回调协议
原生层	各平台容器工程 + 插件系统	Android/iOS 原生工程，插件以统一接口暴露 exec() 能力

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

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

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

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

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

仓库	地址	角色
hcordova	https://atomgit.com/CPF-Cordova/hcordova	命令行工具（对标 cordova@13.0.0），负责 create/platform/plugin 管理
cordova-openharmony	https://atomgit.com/CPF-Cordova/cordova-openharmony	OHOS 平台本体（npm 包名 @cordova-ohos/ohos），生成鸿蒙壳工程，是基于 cordova-android@14.0.1 开发，并适配了 OHOS 平台特性

架构关系：

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 适配目标

维度	要求
功能一致性	Web 层零改动，cordova.js 桥接协议在 OHOS 上行为一致
工程规范	生成的鸿蒙工程可直接用 DevEco Studio 打开开发调试
构建验证	命令行可产出未签名 HAP，模拟器可安装运行
插件生态	OHOS 插件从 CPF-Cordova 组织获取，--platform ohos 安装

---

二、适配路线图

整个迁移分为 4 个阶段：

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

---

三、逐步适配过程

第 1 阶段：环境准备

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

依赖	版本	说明
Node.js	v26.0.0（README 推荐 v18 LTS）	实测 v26 亦可
cordova	13.0.0	hcordova 底层依赖，必装
hcordova	1.0.7	鸿蒙 CLI
DevEco Studio	含内置 hvigor / ohpm / SDK	构建 HAP 用

安装命令：

# 先装原版 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 真正干活的地方，实际执行了三件事：

1. 自动安装 openssl：交互式询问 Automatically install openssl(y|n)，选 Y 后自动克隆 openssl 源码，把 C 库拷贝到 harmonyos/cordova/src/main/cpp/openssl（cordova-openharmony 的原生网络层 Socket/SSLSocket 依赖它）；
2. 拉取 cordova-openharmony：将 @cordova-ohos/ohos 平台包落到 harmonyos/cordova/，其中 libs/ 下含 arm64-v8a、x86_64 两个 ABI 的预编译库（分别对应真机和模拟器）；
3. 渲染模板：处理 43 个模板文件，包括 AppScope/app.json5（写入你的包名 com.nutpi.MyApp）、string.json（应用名 MyHarmonyApp）、rawfile/config.xml 等。

成功后目录结构：

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/ 源码目录）：

模块	文件	作用
桥接核心	CordovaBridge / NativeToJsMessageQueue / CordovaExposedJsApi	实现 JS↔原生消息队列，对标 Android 的 CordovaBridge
插件系统	PluginManager / PluginEntry / CordovaPlugin / PluginResult	插件注册与生命周期管理
Web 容器	CordovaWebViewEngine / CordovaViewController / rawfile_request	基于 ArkWeb 加载 www/，rawfile 协议拦截
配置解析	ConfigXmlParser / XMLParser / CordovaPreferences	解析 config.xml 与 preferences
网络层	Socket / SSLSocket / HttpUrl / ConnPool	自研 C++ 网络实现（依赖打包进来的 openssl）
核心插件	CoreHarmony / TsCordovaPlugin	对标 cordova-android 的 CoreAndroid
工具	Base64 / FileCache / MemPool / Thread / cJSON	基础设施

可见鸿蒙版并非简单把 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 自动签名：

1. DevEco Studio 打开 MyApp/harmonyos；
2. File → Project Structure → Signing Configs，勾选 Automatically generate signature；
3. 选择模拟器目标，点击 Run。

应用即安装到模拟器并启动：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

维度	Android (cordova-android)	OHOS (cordova-openharmony)
WebView	android.webkit.WebView	ArkWeb (Web 组件)
原生语言	Kotlin / Java	ArkTS + C++ (NAPI)
桥接协议	CordovaBridge + NativeToJsMessageQueue	CordovaBridge.cpp + NativeToJsMessageQueue.cpp（C++ 重写）
插件接口	CordovaPlugin (Java 抽象类)	CordovaPlugin.h (C++) / TsCordovaPlugin (ArkTS)
核心插件	CoreAndroid	CoreHarmony / TsCordovaPlugin
网络栈	java.net / OKHttp 可选	自研 C++ Socket/SSLSocket + openssl
配置源	res/xml/config.xml	rawfile/config.xml（由 hcordova 从根 config.xml 渲染）
本地页面	file:///android_asset/	rawfile 协议拦截（rawfile_request.cpp）

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 定位、签名、增量编译等复杂逻辑，也与鸿蒙官方工具链保持一致。

---

六、测试与验证

测试环境

项目	版本
macOS	arm64 (Apple Silicon)
Node.js	v26.0.0
cordova CLI	13.0.0
hcordova	1.0.7
cordova-openharmony	@cordova-ohos/ohos 14.0.2（oh-package.json5 实测）
HarmonyOS SDK	targetSdkVersion 5.0.5(17) / compatibleSdkVersion 5.0.0(12)
IDE	DevEco Studio（内置 hvigor / ohpm）
设备 ROM	模拟器 7.0.0.106(SP1DEVC00E999R4P11)

版本获取方式：

版本项	获取方式
hcordova	hcordova -v
cordova	cordova -v
cordova-openharmony 平台版本	读 harmonyos/cordova/oh-package.json5 的 version
HarmonyOS SDK	读 harmonyos/build-profile.json5 的 targetSdkVersion / compatibleSdkVersion
设备 ROM	hdc shell param get const.product.software.version（先 hdc list targets 确认连接）

验证要点

1. 项目创建 — hcordova create 生成标准 Cordova 骨架，config.xml 包名/应用名正确
2. 平台添加 — platform add ohos 完成 openssl 拷贝 + 43 个模板渲染，platform ls 显示 HarmonyOS (installed)
3. 构建验证 — hvigorw assembleHap 成功，41 任务零失败，产出 unsigned HAP
4. 运行验证 — 签名后安装到模拟器，deviceready 触发，Web 页面正常渲染
5. 包名核对 — hdc shell bm dump -n com.nutpi.MyApp 能查到已安装应用

---

七、运行效果

模拟器运行标准 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 .

---

八、遗留问题与改进方向

踩坑复盘

踩坑点	现象 / 报错	根因与解法
hcordova create 报 cordova 不存在	/bin/sh: cordova: command not found，退出码 127	hcordova 的 create 转发给原版 cordova CLI；先 npm install -g cordova
hcordova build ohos “不干活”	只打印 Please use the "hvigorw" command tool...	源码中 ohos 分支不实现构建，属设计行为；自行调用 DevEco 内置 hvigorw
HAP 无法直接安装	Will skip sign 'hos_hap'. No signingConfigs profile is configured	build-profile.json5 无签名配置；DevEco 自动签名或手动 hap-sign-tool 签名
hvigorw 找不到	shell 中无该命令	hvigorw 在 DevEco 安装目录内，需 export PATH 指向 DevEco-Studio.app/Contents/tools/{hvigor,node,ohpm}/bin
SplashScreen 告警	This API is unavailable to 2in1	平台包对 2in1（PC/二合一）形态的 API 差异告警，仅 WARN，不影响 phone/tablet 运行

已知问题

1. CLI 不支持鸿蒙调试 — hcordova run ohos 同样只打印提示，日志查看、断点调试需 DevEco Studio（README 4.1/4.3 明确说明）
2. build 产物为 unsigned HAP — 命令行链路不包含签名环节，自动化 CI 需自行接入 hap-sign-tool

未来优化

• 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 开源。