从 0 到 1：使用 hionic 将 Web 应用部署到鸿蒙PC平台

本教程基于 hionic CLI，以 React + Capacitor 为例，完整演示如何从零搭建一个鸿蒙原生应用，并涵盖 Mac 环境下常见踩坑与解决方案。

目录

  1. 环境准备
  2. 安装 hionic CLI
  3. 创建 Capacitor 项目
  4. 添加 OpenHarmony 平台
  5. 修复 OpenSSL 依赖（必读！）
  6. 前端构建
  7. 在 DevEco Studio 中打开与编译
  8. 完整构建 HAP 包
  9. 部署到设备 / 模拟器
  10. 常见问题

1. 环境准备

工具 说明
Node.js 推荐 v18+，通过 Homebrew 安装（见下文）
npm 随 Node.js 一起安装
DevEco Studio 鸿蒙官方 IDE，用于编译和签名 HAP 包
hdc 鸿蒙设备连接工具，随 DevEco Studio 附送
OpenHarmony SDK DevEco Studio 中配置

⚠️ 重点：Node.js 安装方式

不要使用 DevEco Studio 内嵌的 Node.js（路径包含 /Applications/DevEco-Studio.app/），因为该目录是只读的，npm install -g 会报 EPERM 错误：

npm ERR! Error: EPERM: operation not permitted, mkdir '/Applications/DevEco-Studio.app/.../node_modules/hionic'

正确的做法：通过 Homebrew 安装独立的 Node.js：

# 安装 Homebrew 的 Node.js
brew install node

# 验证
which node      # 应输出 /opt/homebrew/bin/node
node -v         # 应输出 v18+ 或 v20+ / v26+
npm -v

Homebrew 的 Node.js 安装在 /opt/homebrew 下，用户有完整写入权限。

2. 安装 hionic CLI

hionic 是基于 Ionic CLI 二次开发的命令行工具，支持将 Web 项目（Capacitor / Cordova）添加 OpenHarmony 平台支持。

npm install -g hionic

安装后验证：

hionic -v
# 输出：hionic 2.1.15（或更高版本）

说明：hionic 的官方仓库在 atomgit.com/CPF-Ionic/capacitor-cli，更多使用说明可参考该仓库的 README。

3. 创建 Capacitor 项目

hionic 支持两种框架：cordova 和 capacitor。本教程以 Capacitor + React 为例。

# 语法：hionic start <框架> <项目目录> <包名> <应用名> [模板]
hionic start capacitor MyApp com.nutpi.MyApp MyHarmonyApp react

执行过程说明：

  1. 创建 Vite + React 前端项目：内部调用 npm create vite MyApp -- --template react
  2. 安装前端依赖：执行 npm install
  3. 初始化 Capacitor：执行 npx cap init MyHarmonyApp com.nutpi.MyApp

⚠️ 踩坑：npx cap init 失败

在某些环境中，hionic start 执行到 npx cap init 时会报错：

npm error could not determine executable to run

原因：@capacitor/cli 尚未安装，npx 找不到可执行文件。

解决方法：手动安装 Capacitor CLI 和 Core，然后重新初始化：

cd MyApp
npm install @capacitor/core @capacitor/cli
npx cap init MyHarmonyApp com.nutpi.MyApp

成功后会在项目根目录生成 capacitor.config.json。

4. 添加 OpenHarmony 平台

cd MyApp
hionic platform add openharmony

执行成功后，你会看到：

detect result: Capacitor
confidence: 70%
Certificate:
1. Found Capacitor packages: @capacitor/cli, @capacitor/core
2. Found Capacitor config file: capacitor.config.json
3. Capacitor CLI available

Using hionic openharmony platform support
Project created successfully

此时项目根目录下会生成 openharmony/ 目录，这就是鸿蒙原生工程。

项目目录结构

MyApp/
├── openharmony/              # OpenHarmony 原生工程目录
│   ├── entry/                # 应用主模块
│   ├── capacitor/            # Capacitor 适配层（C++ + ArkTS）
│   ├── AppScope/             # 应用级配置
│   └── build-profile.json5   # 构建配置
├── src/                      # React 前端源码
├── dist/                     # 前端构建输出
├── capacitor.config.json     # Capacitor 配置
├── index.html                # 应用入口
├── vite.config.js
└── package.json

5. 修复 OpenSSL 依赖（必读！）

问题现象

此时如果直接编译，会报如下错误：

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

原因分析

Capacitor 适配层的 C++ 代码（HTTP/HTTPS 通信、WebSocket 等）依赖 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
)

但 openharmony/capacitor/libs/ 目录为空，缺少预编译的 OpenSSL 动态库。

解决方案

官方提供了预编译好的 OpenSSL 3.5 库，仓库地址：atomgit.com/li_in/openharmony-capacitor-openssl3.5

# 克隆 OpenSSL 预编译库
git clone --depth 1 https://gitcode.com/li_in/openharmony-capacitor-openssl3.5.git /tmp/ohos-openssl

# 复制 .so 库文件到 capacitor 的 libs 目录
cp -r /tmp/ohos-openssl/libs /Users/nutpi/Desktop/study/cordova/MyApp/openharmony/capacitor/libs

# 复制 OpenSSL 头文件到 cpp 目录
cp -r /tmp/ohos-openssl/openssl /Users/nutpi/Desktop/study/cordova/MyApp/openharmony/capacitor/src/main/cpp/openssl

# 清理临时文件
rm -rf /tmp/ohos-openssl

复制后的目录结构应如下：

openharmony/capacitor/
├── libs/
│   ├── arm64-v8a/
│   │   ├── libssl.so.3
│   │   ├── libcrypto.so.3
│   │   └── ...
│   └── x86_64/
│       ├── libssl.so.3
│       ├── libcrypto.so.3
│       └── ...
└── src/main/cpp/
    └── openssl/
        ├── arm64-v8a/include/openssl/   # arm64 头文件
        └── x86_64/include/openssl/       # x86 头文件

说明：该仓库提供了 arm64-v8a（真机/模拟器）和 x86_64（模拟器）两个架构的预编译库，覆盖开发和部署两种场景。

6. 前端构建

Capacitor 项目需要先将 Web 资源构建为静态文件，才能集成到原生包中。

# 构建前端（Vite 打包到 dist/）
hionic buildui

该命令等同于直接执行 npm run build，将 React 源码构建到 dist/ 目录。

7. 在 DevEco Studio 中打开与编译

方式一：命令行打开

hionic open openharmony

方式二：手动打开

直接用 DevEco Studio 打开 MyApp/openharmony/ 目录。

配置签名

在 DevEco Studio 中：

  1. File → Project Structure → Signing Configs
  2. 登录华为开发者账号，自动生成签名证书
  3. 或导入已有 .p12 / .cer / .p7b 证书

编译构建

在 DevEco Studio 中点击 Build → Build HAP(s)，或使用命令行：

# 使用 DevEco 内嵌的 Node.js 运行 hvigor
/Applications/DevEco-Studio.app/Contents/tools/node/bin/node \
  /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js \
  --mode module \
  -p module=entry@default \
  -p product=default \
  -p requiredDeviceType=phone \
  assembleHap \
  --analyze=normal --parallel --incremental --daemon

构建成功后输出：

> hvigor BUILD SUCCESSFUL in 10 s 778 ms

生成的 HAP 包位于：

openharmony/entry/build/default/outputs/default/
├── entry-default-signed.hap       # 已签名，可直接安装
└── entry-default-unsigned.hap     # 未签名

8. 完整构建 HAP 包

hionic 也封装了完整的构建命令（需先配置 DEVECO_SDK_HOME 和 DEVECO_IDE_PATH 环境变量）：

# 配置环境变量
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export DEVECO_IDE_PATH=/Applications/DevEco-Studio.app

# 构建
hionic buildapp openharmony

9. 部署到设备 / 模拟器

启动模拟器

在 DevEco Studio 中：Tools → Device Manager → 创建并启动模拟器。

安装 HAP

# 连接设备
hdc list targets

# 安装 HAP
hdc install openharmony/entry/build/default/outputs/default/entry-default-signed.hap

一行命令部署（hionic）

hionic run openharmony

Screenshot_20260602100546669

查看运行日志

hdc shell hilog | grep capacitor

10. 常见问题

Q1：npm install -g hionic 报 EPERM

原因：使用了 DevEco Studio 内嵌的 Node.js，全局安装目录只读。

解决：通过 Homebrew 重新安装 Node.js，确保 which node 指向 /opt/homebrew/bin/node。

Q2：hionic start 执行到 npx cap init 失败

原因：@capacitor/cli 尚未安装，npx 找不到可执行文件。

解决：

npm install @capacitor/core @capacitor/cli
npx cap init MyHarmonyApp com.nutpi.MyApp

Q3：编译报错 libssl.so.3 missing

原因：OpenSSL 预编译库未集成。

解决：

git clone --depth 1 https://gitcode.com/li_in/openharmony-capacitor-openssl3.5.git /tmp/ohos-openssl
cp -r /tmp/ohos-openssl/libs openharmony/capacitor/libs
cp -r /tmp/ohos-openssl/openssl openharmony/capacitor/src/main/cpp/openssl
rm -rf /tmp/ohos-openssl

Q4：page_text_font_size 资源冲突

Warning: 'page_text_font_size' conflict, first declared at .../entry/.../float.json
but declared again at .../capacitor/.../float.json

这是警告而非错误，不影响构建。两个模块都定义了同名资源，entry 模块的声明优先级更高。如需消除警告，可以删除 capacitor 模块中重复的 float.json 配置。

Q5：报错 FetchPackageInfo: "@ohos/hypium" failed

解决：将 openharmony/capacitor/oh-package.json5 中的 devDependencies 内容删除后重试。

总结

通过本教程，你完成了从零到一将 React Web 应用部署到鸿蒙平台的完整流程：

Web 应用 (React)
    │
    ▼
Capacitor 封装 (跨平台桥接层)
    │
    ▼
hionic CLI 添加 OpenHarmony 平台
    │
    ▼
OpenSSL 预编译库集成 ← 关键步骤，容易遗漏
    │
    ▼
DevEco Studio 编译 → HAP 包
    │
    ▼
安装到鸿蒙设备 / 模拟器 ✅

hionic 工具链的核心价值在于：一次开发，多端部署——同一份 React/Vue/Angular 代码，可以同时构建 Android、iOS 和 OpenHarmony 三平台的原生应用。

项目地址：https://gitcode.com/jianguoxu/hionic

参考资源

# 前端 # harmonyos # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

第41篇｜补光与水印：效果选项如何参与最终照片记录

avatar HarmonyOS开发者社区
cover

HarmonyOS 6.1 开发者盛宴｜《灵犀厨房》实战（二十三）：【交互动效】转场、列表动画与趣味反馈——让每一次点击都有温度

avatar HarmonyOS开发者社区
cover

基于HarmonyOS的英语学习应用技术实现与价值分析

avatar HarmonyOS开发者社区