CPF-Ionic 0-1：从零搭建 Capacitor 鸿蒙化开发环境，到真机跑通首个应用

坚果派

111人浏览 · 2026-09-04 20:20:34

坚果派 · 2026-09-04 20:20:34 发布

CPF-Ionic 0-1：从零搭建 Capacitor 鸿蒙化开发环境，到真机跑通首个应用

本文记录一次完整的「0 → 1」实战：在 macOS 上从空环境开始，基于 CPF-Ionic 组织的 openHarmony-capacitor 框架 与 capacitor-cli（hionic 命令行工具），完成开发环境搭建、初始化项目创建、openssl 集成、HAP 编译，并最终安装运行到 OpenHarmony 真机（HUAWEI Mate 60 Pro）。

一、背景与目标

Ionic + Capacitor 是当前移动端非常主流的跨平台方案：Web 技术（HTML5/CSS3/JS）开发，Capacitor 作为原生容器桥接系统能力，一套代码同时覆盖 Android、iOS。但官方 Capacitor 至今不支持 OpenHarmony，开发者想迁移鸿蒙只能从零适配，工作量巨大。

CPF-Ionic 组织正是为了解决这个问题而存在：它基于 OpenHarmony-Cordova 衍生，孵化了完整的 Capacitor 鸿蒙化生态：

组件	说明
openHarmony-capacitor	Capacitor 鸿蒙化核心框架，接口兼容官方 Android/iOS 版本
capacitor-cli	hionic 命令行工具，基于 @ionic/cli@2.1.15 开发
ionic-readme	项目总介绍与插件映射表

本篇文章的目标很简单、很具体：

从 0 搭建开发环境（Node / JDK / DevEco Studio / HarmonyOS SDK / hionic）
用 hionic 创建 Capacitor 初始化项目
添加 OpenHarmony 平台壳工程
集成 openssl（框架编译前置依赖）
配置签名，命令行编译出 HAP
安装到真机并启动运行

二、技术栈与架构速览

2.1 openHarmony-capacitor 框架

openHarmony-capacitor 是 Capacitor 的 OpenHarmony 化版本，基于 @capacitor/android@8.0.0 开发：

所有接口兼容 Capacitor Android/iOS 版本，迁移几乎零成本；
框架主体用 C/C++ 研发，底层自研 Socket TCP/IP 通讯，封装 HTTP/HTTPS 协议栈，解决跨域访问问题，无需配置 Web 服务端；
支持 ArkTS 侧与 C/C++ 侧自定义插件研发；
采用多页面视图，同时兼容原有单页面视图，复杂项目可创建多个 WebView 协同工作。

2.2 版本兼容要求（实测）

组件	版本要求	本文实测环境
OpenHarmony	5.0+	OpenHarmony-7.0.0.105（Mate 60 Pro）
HarmonyOS SDK	5.0.5(17) 及以上	26.0.0（ets / js / native）
DevEco Studio	6.0.0 及以上	26.0.0
Node.js	v16+（推荐 20/22 LTS）	v26.0.0
JDK	17	17.0.12 LTS
openssl	3.5.x（预编译二进制）	3.5.5

⚠️ 关键点：框架 CMake 构建强依赖 openssl（libssl.so.3 / libcrypto.so.3），必须先集成，否则编译直接报错（详见第六节）。

三、环境准备

3.1 基础工具

node -v    # v26.0.0
npm -v     # 11.12.1
java -version  # 17.0.12 LTS
git --version  # 2.39.5

3.2 DevEco Studio 与 HarmonyOS SDK

安装 DevEco Studio（macOS 版），内置/关联 HarmonyOS SDK，并确认 hdc、ohpm、hvigorw 可用：

# hdc（设备调试工具）
/Users/nutpi/Library/OpenHarmony/Sdk/26.0.0/toolchains/hdc
# ohpm（鸿蒙包管理，随 DevEco 提供）
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm
# hvigor（构建工具，随 DevEco 提供）
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw --version  # 6.26.4

连接真机并确认设备可见：

hdc list targets
# 192.168.10.2:42923
hdc shell param get const.ohos.fullname   # OpenHarmony-7.0.0.105
hdc shell uname -m                        # aarch64

3.3 安装 hionic CLI

hionic 已发布到 npm，直接全局安装：

npm install -g hionic
hionic -v   # 2.1.16
hionic -h   # 查看全部命令

hionic 覆盖项目创建、平台管理、插件管理、构建调试全流程，核心命令如下：

命令	作用
`hionic start <framework> <path> [id] [name] [template]`	创建新项目（cordova / capacitor）
`hionic init <name> <id>`	已有 Web 项目初始化 Capacitor
`hionic platform add openharmony`	添加 OpenHarmony 平台壳工程
`hionic plugin add <plugin> --platform openharmony`	安装鸿蒙化插件
`hionic buildui`	构建前端（Capacitor 项目）
`hionic copy / sync <platform>`	同步前端产物到壳工程

四、创建初始化项目

4.1 命令

hionic start capacitor MyApp com.example.MyApp MyHarmonyApp

参数说明：<framework=capacitor> <path=MyApp> <appId=com.example.MyApp> <appName=MyHarmonyApp> [template 默认 vinilla]。

4.2 ⚠️ 坑 1：`hionic start` 在非交互终端挂起

首次运行时命令卡住直到超时。项目骨架（Vite 前端）已生成，但停在 _initializeCapacitor 阶段——该阶段通过 npx cap init 初始化 Capacitor，而非交互终端中 npx 会等待「确认安装 @capacitor/cli」的提示，导致挂起。

解决：进入项目目录，手动安装依赖并执行 cap init：

cd MyApp
npm install @capacitor/cli@3.9.0 @capacitor/core@3.9.0 --save
npx cap init MyHarmonyApp com.example.MyApp --web-dir=dist

成功后会生成 capacitor.config.ts：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.MyApp',
  appName: 'MyHarmonyApp',
  webDir: 'dist',
  bundledWebRuntime: false
};

export default config;

注：这里的 @capacitor/core@3.9.0 后面会被替换为 8.x（见 5.2），以匹配框架基于 @capacitor/android@8.0.0 的版本基线。

五、添加 OpenHarmony 平台

5.1 命令

hionic platform add openharmony

5.2 ⚠️ 坑 2：ERESOLVE 依赖版本冲突

第一次执行报错：

npm error ERESOLVE unable to resolve dependency tree
npm error Found: @capacitor/core@3.9.0
npm error Could not resolve dependency:
npm error peer @capacitor/core@"^8.0.0" from @capacitor-ohos/ohos@8.0.2

原因：hionic 添加 openharmony 平台时会从 npm 下载壳工程框架包 @capacitor-ohos/ohos@8.0.2，其 peer 依赖要求 @capacitor/core@^8.0.0，与项目里的 3.9.0 冲突。

解决：将 Capacitor 相关包升级到 8.x（与 openHarmony-capacitor 基于的 android@8.0.0 对齐）：

npm install @capacitor/cli@8 @capacitor/core@8 --save
hionic platform add openharmony

5.3 平台添加成功后的目录结构

MyApp/
├── index.html / src/ / vite.config.js   # Vite 前端（已自动配置 base:'./'）
├── capacitor.config.ts                  # appId=com.example.MyApp, appName=MyHarmonyApp
├── package.json                         # @capacitor/cli@8 + @capacitor/core@8
└── openharmony/                         # OpenHarmony 壳工程（hionic 模板生成）
    ├── AppScope/                        # 应用级配置（app.json5 等）
    ├── entry/                           # entry 模块（HAP 载体）
    ├── capacitor/                       # openHarmony-capacitor 框架源码（自动从 npm 包复制）
    ├── build-profile.json5              # 工程构建配置（模块挂载）
    ├── hvigor/ hvigorfile.ts            # hvigor 构建配置
    ├── oh-package.json5
    └── local.properties

壳工程已自动完成框架集成：entry/oh-package.json5 中声明 "harmony-capacitor": "file:../capacitor"，build-profile.json5 中挂载了 entry 与 capacitor 两个模块。

六、集成 openssl（编译前置依赖）

6.1 为什么需要 openssl

框架的 C/C++ 层（Socket/HTTP/HTTPS 协议栈、SSL）依赖 openssl。CMakeLists.txt 明确引用了：

set(OPENSSL_LIB_PATH ${NATIVERENDER_ROOT_PATH}/../../../libs/${OHOS_ARCH})
target_link_libraries(capacitor PUBLIC
    ${OPENSSL_LIB_PATH}/libssl.so.3
    ${OPENSSL_LIB_PATH}/libcrypto.so.3
)
include_directories(${NATIVERENDER_ROOT_PATH}/openssl/${OHOS_ARCH}/include)

即框架期望的目录结构为：

openharmony/capacitor/
├── libs/{OHOS_ARCH}/libssl.so.3 + libcrypto.so.3   # 动态库
└── src/main/cpp/openssl/{OHOS_ARCH}/include/       # 头文件

6.2 获取预编译二进制

官方推荐直接使用 openharmony-capacitor-openssl3.5 提供的预编译产物（含 arm64-v8a 与 x86_64），免去自行交叉编译：

git clone --depth 1 -b master https://atomgit.com/li_in/openharmony-capacitor-openssl3.5.git

仓库内 libs/ 与 openssl/ 目录结构与框架期望完全一致，直接复制集成：

CAP=MyApp/openharmony/capacitor
cp -R openssl-repo/libs/arm64-v8a       "$CAP/libs/"
cp -R openssl-repo/openssl/arm64-v8a    "$CAP/src/main/cpp/openssl/"
cp -R openssl-repo/libs/x86_64          "$CAP/libs/"
cp -R openssl-repo/openssl/x86_64       "$CAP/src/main/cpp/openssl/"

6.3 ⚠️ 坑 3：只集成 arm64 导致 x86_64 编译失败

第一次只拷贝了 arm64-v8a，编译时报：

ninja: error: '.../capacitor/libs/x86_64/libssl.so.3', needed by
'.../obj/x86_64/libcapacitor.so', missing and no known rule to make it

原因：hvigor 默认会为 arm64-v8a 和 x86_64 两个架构分别构建 native 库（x86_64 供模拟器使用），因此两套架构的 openssl 都必须就位。补齐 x86_64 后即可。

至此，编译前的所有前置条件已就绪。

七、配置编译环境与签名

7.1 指定 HarmonyOS SDK 路径

在 openharmony/local.properties 中写入 SDK 路径，hvigor 才能找到工具链与系统库：

sdk.dir=/Users/nutpi/Library/OpenHarmony/Sdk/26.0.0

7.2 签名配置

真机安装要求 HAP 必须签名。签名材料用 DevEco Studio 生成（File → Project Structure → Signing Configs，勾选自动签名或使用调试证书），生成的 signingConfigs 会自动写入 openharmony/build-profile.json5：

"signingConfigs": [
  {
    "name": "default",
    "type": "HarmonyOS",
    "material": {
      "certpath": "/Users/nutpi/.ohos/config/xxx.cer",
      "keyAlias": "debugKey",
      "keyPassword": "******",
      "profile": "/Users/nutpi/.ohos/config/xxx.p7b",
      "signAlg": "SHA256withECDSA",
      "storeFile": "/Users/nutpi/.ohos/config/xxx.p12",
      "storePassword": "******"
    }
  }
]

💡 命令行场景下也可以自己用 keytool + SDK 自带的 hap-sign-tool.jar（{SDK}/toolchains/lib/hap-sign-tool.jar）生成本地调试签名链（根 CA → 应用证书 → profile 证书 → 签名 profile），设备是 OpenHarmony 系统时同样可安装；本文使用 DevEco 自动签名方案，更省事。

八、命令行编译 HAP

无需打开 IDE，直接在 shell 中用 hvigor 编译：

cd MyApp/openharmony

# 1. 解析 oh-package 依赖（首次需要）
ohpm install

# 2. 编译并签名（debug 模式）
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

编译日志关键节点：CompileArkTS → BuildNativeWithCmake（C++ 层，含 openssl 链接）→ PackageHap → SignHap → BUILD SUCCESSFUL。

产物：

openharmony/entry/build/default/outputs/default/
├── entry-default-signed.hap      # 已签名，约 43 MB（含 libcapacitor.so + 前端资源）
└── entry-default-unsigned.hap    # 未签名版本

九、真机安装与运行

9.1 安装

cd MyApp/openharmony
hdc install entry/build/default/outputs/default/entry-default-signed.hap
# [Info]App install path:... msg:install bundle successfully.

9.2 启动

hdc shell aa start -a EntryAbility -b com.example.MyApp
# start ability successfully.

9.3 运行验证

# ① 进程检查：主进程 + 渲染进程
hdc shell ps -ef | grep -i myapp
# 20021079 ... com.example.MyApp
# 20100005 ... com.example.MyApp:render

# ② 日志检查：webview 已加载模板内置页面并渲染
hdc shell hilog | grep -iE "myapp|capacitor"
# ARKWEB-CONSOLE: "deviceready has not fired after 5 seconds." source: https://app.com/www/cordova.js

# ③ 截图确认 UI 正常渲染
hdc shell snapshot_display -f /data/local/tmp/cap.jpeg
hdc file recv /data/local/tmp/cap.jpeg ./cap_screen.jpeg

com.example.MyApp 主进程与 :render 渲染进程同时存活、WebView 输出渲染日志、截图正常拉取（1260×2720）——应用已在真机跑通 ✅

十、踩坑问题汇总

#	现象	根因	解决
1	`hionic start` 终端卡住直到超时	非交互环境下 `npx cap init` 等待确认安装 @capacitor/cli	手动 `npm install @capacitor/cli @capacitor/core` 后执行 `npx cap init`
2	`hionic platform add openharmony` 报 ERESOLVE	`@capacitor-ohos/ohos@8.0.2` 要求 peer `@capacitor/core@^8.0.0`，项目却是 3.9.0	升级 `@capacitor/cli@8 @capacitor/core@8` 后重试
3	编译报 ninja: missing `libs/x86_64/libssl.so.3`	只集成了 arm64-v8a 的 openssl，hvigor 默认双架构构建	补齐 x86_64 的 libs 与头文件
4	`snapshot_display` 截图失败	文件名后缀必须为 `.jpeg`	改用 `.jpeg` 后缀

十一、后续路线

至此已完成「0 → 1」：环境搭建 → 初始化项目 → HAP 编译 → 真机运行。接下来可以继续：

11.1 让应用显示自己的前端页面

当前真机上跑的是壳工程内置模板页，把前端产物同步进壳工程：

cd MyApp
hionic buildui        # 构建前端 → dist
hionic copy openharmony   # 拷贝 dist 产物到壳工程 rawfile/www

重新编译安装 HAP 后即显示自己的页面。

11.2 插件移植

按 ionic-readme 插件映射表把原项目用到的插件替换为鸿蒙化版本：

hionic plugin add @capacitor/camera --platform openharmony
hionic plugin add @capacitor/device --platform openharmony

11.3 热更新

框架内置 HotCodePushPlugin（基于 Cordova 热更新能力改造），无需额外安装，前端发版后 Web 资源可增量更新。

11.4 正式发布

将 debug 签名替换为 release 签名（发布证书 + release profile），按 OpenHarmony 上架规范打包上架。

所有评论(0)

查看更多评论

坚果派

@qq_39132095

已为社区贡献81条内容

CPF-Ionic 0-1：从零搭建 Capacitor 鸿蒙化开发环境，到真机跑通首个应用

坚果派

CPF-Ionic 0-1：从零搭建 Capacitor 鸿蒙化开发环境，到真机跑通首个应用

一、背景与目标

二、技术栈与架构速览

2.1 openHarmony-capacitor 框架

2.2 版本兼容要求（实测）

三、环境准备

3.1 基础工具

3.2 DevEco Studio 与 HarmonyOS SDK

3.3 安装 hionic CLI

四、创建初始化项目

4.1 命令

4.2 ⚠️ 坑 1：hionic start 在非交互终端挂起

五、添加 OpenHarmony 平台

5.1 命令

5.2 ⚠️ 坑 2：ERESOLVE 依赖版本冲突

5.3 平台添加成功后的目录结构

六、集成 openssl（编译前置依赖）

6.1 为什么需要 openssl

6.2 获取预编译二进制

6.3 ⚠️ 坑 3：只集成 arm64 导致 x86_64 编译失败

七、配置编译环境与签名

7.1 指定 HarmonyOS SDK 路径

7.2 签名配置

八、命令行编译 HAP

九、真机安装与运行

9.1 安装

9.2 启动

9.3 运行验证

十、踩坑问题汇总

十一、后续路线

11.1 让应用显示自己的前端页面

11.2 插件移植

11.3 热更新

11.4 正式发布

相关链接

所有评论(0)

温馨提示：您尚未绑定手机号

坚果派

4.2 ⚠️ 坑 1：`hionic start` 在非交互终端挂起