从 Cordova 到 Capacitor： CPF 生态把两大混合应用框架整体搬上鸿蒙

混合应用（Hybrid App）技术栈在移动开发史上拥有最庞大的存量应用群。当行业焦点转向 Flutter、React Native 与鸿蒙原生时，数量以十万计的 Cordova / Capacitor / Ionic 应用如何迁移到 OpenHarmony？
CPF 团队给出的答案是两个组织、两套 CLI、50+ 插件的整体生态移植：
CPF-Cordova（Cordova 鸿蒙化）与 CPF-Ionic（Capacitor/Ionic 鸿蒙化）。
本文基于本机实测（hcordova 1.0.7 + cordova-openharmony 14.0.2、hionic 2.1.16 + @capacitor-ohos/ohos 8.0.2，应用已跑在 OpenHarmony 模拟器上），从架构、命令、插件、踩坑四个维度对两个生态做全景解析。

一、为什么是 Cordova 和 Capacitor

1.1 两大框架的历史地位

框架诞生维护方定位
Cordova（前身 PhoneGap）2009Apache 基金会混合应用开山之作，WebView + 插件桥接
Capacitor2017Ionic 团队“现代版 Cordova”，原生工程归开发者所有，桥接更薄
Ionic2013Ionic 团队基于 Angular/React/Vue 的 UI 框架，底层依赖 Capacitor/Cordova

三者的存量应用规模巨大，且大量企业内部应用仍在维护。迁移鸿蒙的现实路径不是重写，而是换原生容器——这正是 CPF 两个组织做的事。

1.2 整体思路

两个组织采用同一套方法论：

Web 层（HTML/JS/React/Vue/Angular）── 完全不动
    │
桥接层（cordova.js exec 协议 / capacitor native-bridge）
    │  ── 用 ArkTS + C++ (NAPI) 重写，对接 ArkWeb
    ▼
原生容器层 ── 生成鸿蒙壳工程（entry + 平台 HAR）
    │
    ▼
OpenHarmony / HarmonyOS 设备

Web 代码零改动是核心承诺：业务代码、第三方 JS 库、插件调用方式全部保持原样，鸿蒙化发生在"用户看不见的原生层"。

二、CPF-Cordova：Cordova 鸿蒙化

组织主页：https://atomgit.com/CPF-Cordova

2.1 仓库地图

仓库角色实测版本
hcordovaCLI，对标 cordova@13.0.0，npm 包名 hcordova1.0.7
cordova-openharmony平台运行时，npm 包 @cordova-ohos/ohos（HAR + 预编译 so 分发）14.0.2
30+ 插件仓库cordova-plugin-* 鸿蒙实现—
cicdCI 流水线—

2.2 核心架构（源码级）

cordova-openharmony 的原生层用 C++ (NAPI) 完整重写了 Cordova 的桥接协议（查看 harmonyos/cordova/src/main/cpp/）：

模块对标 Android
CordovaBridge / NativeToJsMessageQueue / CordovaExposedJsApiCordovaBridge + 消息队列
PluginManager / PluginEntry / CordovaPlugin / PluginResult插件系统
CordovaWebViewEngine / CordovaViewController / rawfile_requestWebView 容器（ArkWeb + rawfile 协议拦截）
ConfigXmlParser / XMLParser / CordovaPreferencesconfig.xml 解析
Socket / SSLSocket / HttpUrl / ConnPool + openssl自研网络栈
CoreHarmony / TsCordovaPluginCoreAndroid

特点：运行时以预编译 so 分发（cordova/libs/arm64-v8a、x86_64），openssl 源码随工程拷入参与编译。

2.3 命令实测（全流程通过）

npm install -g cordova && npm install -g hcordova
hcordova create MyApp com.nutpi.MyApp MyHarmonyApp
cd MyApp && hcordova platform add ohos    # 自动克隆编译 openssl，渲染 43 个模板
cd openharmony && hvigorw assembleHap      # 构建成功
hdc install && aa start                    # 模拟器运行，deviceready 正常触发

亮点：platform add ohos 时 hcordova 会自动安装 openssl（交互式确认后克隆源码并拷入库文件），开箱即用。

不足：build ohos / run ohos 只打印引导提示（源码中 ohos 分支未实现构建），实际构建需手动 hvigorw 或 DevEco。

2.4 插件清单（30+，全部为存量热门插件）

按类别整理（仓库均见 CPF-Cordova 组织）：

类别插件
推送/通知cordova-plugin-huawei-push（鸿蒙推送）、cordova-plugin-local-notification
扫码cordova-plugin-qrscanner、phonegap-plugin-barcodescanner
多媒体cordova-plugin-camera-preview、cordova-plugin-imagepicker、cordova-plugin-mediapicker-dmcsdk、cordova-plugin-photo-library
UI/窗口cordova-plugin-navigationbar(-color)、cordova-plugin-keyboard、cordova-plugin-ionic-keyboard、cordova-plugin-spinnerdialog、cordova-plugin-themeablebrowser、cordova-plugin-injectview、cordova-plugin-privacyscreen、cordova-plugin-detect-screenshot
数据/存储cordova-sqlite-storage、cordova-plugin-nativestorage、cordova-plugin-file-md5
网络/系统cordova-plugin-networkinterface、cordova-plugin-broadcaster、cordova-plugin-contacts、cordova-plugin-ble-central（蓝牙）
三方 SDKcordova-plugin-qqsdk、cordova-plugin-weibosdk
工具cordova-plugin-customconfigparameters、cordova-plugin-app-exit、cordova-hot-code-push-plugin（热更新）

其中 热更新（cordova-hot-code-push-plugin）与华为推送（cordova-plugin-huawei-push） 是企业级应用迁移的刚需件，覆盖很关键。

三、CPF-Ionic：Capacitor / Ionic 鸿蒙化

组织主页：https://atomgit.com/cpf-ionic

3.1 仓库地图

仓库角色实测版本
capacitor-cliCLI，npm 包名 hionic（27 star，生态内最热仓库）2.1.16
openHarmony-capacitor平台运行时，npm 包 @capacitor-ohos/ohos，HAR 源码分发（可读可改）8.0.2
ionic-readme插件总清单与迁移指南入口—
29 个 capacitor-* 插件 + 14 个 ionic-native-* 插件官方与 Ionic 三方插件的 OHOS 实现—
cicdCI 流水线—

3.2 与 hcordova 的架构差异

维度hcordova（CPF-Cordova）hionic（CPF-Ionic）
框架CordovaCapacitor（+ Cordova 兼容层）
运行时分发预编译 soHAR 源码直接拷入工程
openssl 集成✅ 自动（platform add 时）❌ 手动（需自行集成 openssl 3.x，libs + 头文件两处）
命令丰富度create/platform/plugin（build 仅提示）start/init/sync/copy/buildui/buildapp/run/open/info 全链路
前端接入cordova 工程结构任意前端项目（Vite/React/Vue），npx cap init 接入
CLI 依赖转发原版 cordova CLI项目内需装 @capacitor/core + cli

3.3 命令实测（全流程通过）

npm install -g hionic
hionic start capacitor capacitorMyApp com.nutpi.MyApp capacitorMyHarmonyApp react
# → Vite + React 19 项目 + Capacitor 初始化（init 步骤需手动补装 @capacitor/cli，见踩坑）
hionic add openharmony          # 渲染 48 个模板，拷入 HAR 源码运行时
# 集成 openssl（从 hcordova 项目复用编译产物，或按官方 openharmony-capacitor-openssl3.5 仓库编译）
hionic buildui                  # vite build
hionic sync openharmony         # dist → rawfile/www/，刷新插件注册
hvigorw assembleHap             # BUILD SUCCESSFUL，DevEco 自动签名产出 signed HAP
hdc install && aa start         # 模拟器运行成功

3.4 插件清单（43 个，官方 README 逐一对齐上游）

Capacitor 官方插件鸿蒙版（29 个），与 @capacitor/xxx 一一对应：

app、browser、camera、device、filesystem、keyboard、barcode-scanner、app-launcher、clipboard、geolocation、haptics、push-notifications、network、share、status-bar、text-zoom、action-sheet、dialog、screen-reader、splash-screen、toast、file-transfer、file-viewer、inappbrowser、local-notifications、motion、preferences、privacy-screen、screen-orientation

Ionic 三方插件鸿蒙版（14 个），与 @ionic-native/xxx 一一对应：

status-bar、splash-screen、file、in-app-browser、device、file-transfer、app-version、camera、clipboard、file-opener、keyboard、network、android-permissions、pdf-generator

安装体验极佳——hionic plugin add @capacitor/device 一条命令自动完成四项工程修改（插件注册表 / CMake / 源码拷贝 / ArkTS 编译范围），Web 层 import 原包调用，API 与 Android/iOS 完全一致。本机已实测 device 插件在模拟器上返回完整设备信息（platform: HarmonyOS、osVersion: OpenHarmony-7.0.0.105、isVirtual: true）。

四、两大生态横向对比

4.1 迁移路径对比

Cordova 存量应用                Capacitor/Ionic 存量应用
      │                                │
hcordova create +                hionic start/init +
platform add ohos                add openharmony
      │                                │
      └────────────┬───────────────────┘
                   ▼
        鸿蒙壳工程（ArkWeb 容器）
                   │
        hvigorw / DevEco 构建签名
                   ▼
        OpenHarmony 设备运行

4.2 选型建议

场景建议
存量 Cordova 应用（老项目，plugin.xml 体系）hcordova + CPF-Cordova 插件，Web 代码不动
新项目 / Ionic / React / Vue 技术栈hionic + Capacitor，工程现代化程度更高（原生工程归开发者、插件注册透明）
需要深度定制原生层选 hionic：HAR 源码运行时可直接改；hcordova 的 so 是黑盒
企业推送/热更新等刚需CPF-Cordova 已有 huawei-push、hot-code-push 插件；CPF-Ionic 走 capacitor-push-notifications
两者共存完全可行且互补——本机实测 hcordova 下载的 openssl 编译产物可直接供 hionic 项目使用（CPF 生态 openssl 材料同构）

4.3 共性架构特点

  1. ArkWeb 为渲染核心：两个运行时都用系统 ArkWeb 加载 Web 层，性能与安全随系统升级；
  2. C++ NAPI 承载高频桥接：消息队列、插件管理、网络栈用 C++ 实现，ArkTS 做容器编排；
  3. 插件契约对齐上游：plugin.xml（Cordova）/ capacitor.plugins.json（Capacitor）注册机制与上游一致，存量插件开发经验可复用；
  4. 配置源自动渲染：config.xml / capacitor.config.json 由 CLI 渲染进鸿蒙工程模板（43 / 48 个文件），包名、应用名、版本自动同步。

五、踩坑总表（两生态合计 9 项，均实测）

#生态踩坑点现象解法
1Cordovahcordova create 报错cordova: command not foundhcordova 转发原版 CLI，先 npm i -g cordova
2Cordovabuild 不干活只打印引导提示手动 hvigorw（DevEco 内置）
3CordovaHAP 未签名Will skip sign 'hos_hap'DevEco 自动签名或 hap-sign-tool
4Ionicnpx cap init 失败匹配到无关旧包 cap@0.2.1项目内先装 @capacitor/core + cli 再 init
5Ionicopenssl so 缺失ninja 报 libssl.so.3 missing手动集成（hionic 无自动安装）
6Ionicopenssl 头文件缺失openssl/ssl.h not foundlibs 与头文件两处材料缺一不可
7IonicwebDir 不匹配sync 找不到 wwwcapacitor.config.json 改 webDir: dist
8Ionic环境变量DEVECO_IDE_PATH is not configuredexport DEVECO_SDK_HOME + DEVECO_IDE_PATH
9共性CLI 找不到 hvigorwPATH 不含 DevEco 工具链PATH 加 tools/{hvigor,node,ohpm}/bin

六、总结

CPF-Cordova 与 CPF-Ionic 两个组织构成了鸿蒙生态中对存量混合应用最完整的迁移方案：

CPF-Cordova：换容器保契约   ── Cordova 应用 Web 层零改动迁移鸿蒙，30+ 插件护驾
CPF-Ionic：  现代化全链路   ── Capacitor/Ionic 应用一条 CLI 走完 start→sync→build，43 插件对齐上游

从开发者视角看：

  • 迁移成本：核心业务代码零改动，工作集中在 CLI 命令 + 插件替换 + 原生工程构建配置；
  • 生态成熟度：常用插件（推送、热更新、扫码、相机、存储、蓝牙、社交 SDK）均有鸿蒙实现，企业级刚需已覆盖；
  • 仍待完善：hionic 的 openssl 自动集成、hcordova 的 build/run 实装、部分长尾插件覆盖度，是社区可贡献的方向。

Cordova 2009 年开创的"Web 技术写原生应用"范式，在 2026 年的 OpenHarmony 上，通过这两套生态获得了新的生命力。

参考文档

# harmonyos # 华为
Logo
人工智能6S服务平台

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

更多推荐

鸿蒙实用APP《民族宝典》，一站式解锁56个民族多元文化，求支持

APP精准收录各民族核心资料，包含地域分布、语言文字、传统节日、特色饮食、民俗服饰、人文习俗等核心板块，补齐了碎片化科普信息杂乱、内容残缺的痛点，构建出完整的民族文化知识体系。无需复杂操作，打开即可快速检索、浏览各民族文化知识点，无论是日常碎片化学习、课业资料查阅，还是文化爱好者深耕民俗知识，都能满足需求，适配多场景使用。想要系统学习民族文化、积累人文知识，不妨打开鸿蒙应用市场搜索《民族宝典》，依

avatar 人工智能6S服务平台

Flutter 鸿蒙化实战：qrcode_flutter 适配 OpenHarmony，二维码生成与识别

Flutter 鸿蒙化实战：qrcode_flutter 适配 OpenHarmony## 前言随着鸿蒙生态的快速发展，越来越多的 Flutter 应用需要适配 OpenHarmony 平台。但生态早期，大量常用三方库只有 Android / iOS 实现，鸿蒙侧只能自己造轮子。为了解决这个问题，CPF-Flutter 社区对一批高频使用的 Flutter 三方库做了 OpenHarmony 平台

avatar 人工智能6S服务平台

纯血鸿蒙隐私三件套实测：零权限输入法、本地录音转码与离线课程表

手机里最敏感的是哪几类数据？我自己排了一下：一是每天输入的文字，二是开会上课时录的音频，三是行程与日程安排。这三类数据一旦被上传，等于把工作和生活的轮廓交了出去。最近在鸿蒙手机上凑齐了三款对应的原生工具：负责打字的卓越输入法、负责录音和转码的爱录音、负责课表与备忘的课程表管家。三款都是鸿蒙原生应用，目前都免费，且共同特点是功能在本机完成、不需要账号、不收集用户数据。

avatar 人工智能6S服务平台