OpenHarmony 跨端生态适配与 C/C++ 库鸿蒙化实战指南

基于 WebView 的跨端框架鸿蒙适配版，适合 Web 开发者低成本迁移。

• 官方仓库：https://atomgit.com/OpenHarmony-Cordova
• 适配特点：核心插件体系完成鸿蒙化适配，Web 页面无修改直接运行，原生桥接层封装鸿蒙系统能力。

KMP-OH (Kotlin Multiplatform for OpenHarmony)

Kotlin 多平台鸿蒙适配版，主打跨 Android/鸿蒙/桌面端的 Kotlin 原生开发。

• 官方仓库：https://atomgit.com/OpenHarmony-kmp
• 适配特点：基于 Kotlin 的跨平台能力，无缝兼容鸿蒙的 ArkTS，适合 Kotlin 技术栈团队。

Capacitor 鸿蒙兼容说明

Ionic 团队出品的现代化跨端框架，暂未推出专属 OH 版本，原生支持鸿蒙的 Web+ 原生混合开发模式。

• 官方仓库：https://github.com/ionic-team/capacitor

桌面端补充：PC 端生态适配方案

鸿蒙不仅覆盖移动端，也完成了 PC 端（桌面版）的生态布局，核心分为「Electron 桌面应用适配」和「PC 命令行工具鸿蒙化」两大方向。

Electron-OH 鸿蒙桌面版适配

桌面端跨平台框架 Electron 的鸿蒙专属适配版，支持开发鸿蒙桌面应用。

• 官方仓库 1：https://atomgit.com/OpenHarmony-electron
• 官方仓库 2：https://atomgit.com/openharmony-sig/electron
• 适配特点：完整兼容 Electron 的 API 体系，底层适配鸿蒙的桌面系统能力，桌面端应用开发无感知迁移。

PC 命令行工具鸿蒙化

核心方向：To D（工具化）。所有 PC 端的命令行工具、终端工具，均可通过鸿蒙的交叉编译能力完成移植，无标准化适配模板，核心依托「通用 C/C++ 库鸿蒙化」的编译方案完成构建。

重中之重：通用 C/C++ 三方库标准化鸿蒙化适配

这部分其实是重头戏。鸿蒙的底层能力和三方库生态均依赖 C/C++ 库的支撑，官方对 C/C++ 库的鸿蒙化适配做了极致标准化的定义。所有适配工作均围绕「固定 6 个文件」展开，无任何额外开发工作，所有 C/C++ 库的适配流程、文件结构完全一致。

适配核心：仅需 6 个文件，完成全量鸿蒙化

所有 C/C++ 三方库的鸿蒙化适配，最终产出物固定为 6 个文件，缺一不可。文件清单及作用如下，所有文件均有官方标准模板，直接复用修改即可：

├── HPKBUILD # 核心文件：编译构建脚本（configure/cmake/make 编译逻辑、交叉编译配置、打包安装）
├── HPKCHECK # 测试校验脚本：定义鸿蒙设备端的测试逻辑、日志输出、用例执行
├── README.OpenSource # 开源声明文件：必填，标注库的开源协议、版权信息、源码来源
├── README_zh.md # 中文说明文档：适配说明、编译步骤、使用方式、注意事项
├── SHA512SUM # 可选：源码包哈希校验文件，校验下载的源码完整性，无需校验可忽略
└── xxx_oh_pkg.patch # 补丁文件：源码兼容补丁，解决鸿蒙系统的编译报错、路径兼容、接口兼容等问题，按需添加

官方标准模板地址

所有文件的标准模板均由鸿蒙官方维护，直接 fork 修改即可，无需从零编写。

模板仓库：https://gitcode.com/openharmony-sig/tpc_c_cplusplus/tree/master/lycium/template

核心文件详解 & 实战案例

HPKBUILD：鸿蒙化适配的核心文件

HPKBUILD 是 Shell 编写的标准化编译构建脚本，也是 C/C++ 库鸿蒙化的核心。该文件定义了库的基础元信息、源码下载地址、交叉编译环境配置、编译构建逻辑、打包安装路径、测试准备、环境清理等所有核心流程。鸿蒙官方提供了标准模板，同时业界已有大量实战案例，所有适配均基于此模板修改，模板通用，案例可复用。

【官方标准 HPKBUILD 模板】

# This is an example HPKBUILD file. Use this as a start to creating your own,
# and remove these comments.
# NOTE: Please fill out the license field for your package! If it is unknown,
# then please put 'unknown'.
# Contributor: Your Name <[email protected]>
# Maintainer: Your Name <[email protected]>
pkgname=NAME # 库名，必填
pkgver=VERSION # 库版本，必填
pkgrel=0 # 发布号，固定为 0 即可
pkgdesc="" # 库功能描述，必填
url="" # 库官网地址，必填
archs=("armeabi-v7a" "arm64-v8a") # 鸿蒙主流 CPU 架构，固定这两个即可
license=() # 开源协议，必填
depends=() # 运行依赖库，无则留空，依赖库需适配同架构
makedepends=() # 编译依赖工具，无则留空
source="https://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz" # 源码下载链接
downloadpackage=true # 是否自动下载源码包，默认 true
autounpack=true # 是否自动解压源码包，默认 true
buildtools=# 编译方式，支持 cmake/configure/make，必填
builddir=# 源码解压后的目录名
packagename=$builddir.tar.gz # 源码包文件名

# 编译前环境准备：创建目录、设置环境变量、源码预处理
prepare(){
cd $builddir
cd ${OLDPWD}
}

# 核心编译逻辑：交叉编译核心步骤，架构判断、编译命令执行
build(){
cd $builddir
${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" -DOHOS_ARCH=$ARCH -B$ARCH-build -S./ -L
make -j4 -C $ARCH-build
ret=$?
cd $OLDPWD
return $ret
}

# 打包安装：将编译产物安装到鸿蒙指定目录
package(){
cd $builddir
make -C $ARCH-build install
cd $OLDPWD
}

# 测试说明：鸿蒙设备端测试的前置说明
check(){
echo "The test must be on an OpenHarmony device!"
}

# 环境清理：编译完成后清理构建产物
cleanbuild(){
rm -rf ${PWD}/$builddir
}

【实战案例 1】fftw3 的 HPKBUILD（无依赖纯算法库，configure 编译）

# Contributor: Maintainer <[email protected]>
# Maintainer: Maintainer <[email protected]>
pkgname=fftw3
pkgver=3.3.10
pkgrel=0
pkgdesc="FFTW is a C subroutine library for computing the discrete Fourier transform (DFT) in one or more dimensions, of arbitrary input size, and of both real and complex data."
url="http://fftw.org/"
archs=("armeabi-v7a" "arm64-v8a")
license=("GPL-2.0-or-later")
depends=()
makedepends=()
source="http://fftw.org/fftw-${pkgver}.tar.gz"
autounpack=true
downloadpackage=true
buildtools="configure"
builddir=fftw-$pkgver
packagename=$builddir.tar.gz
source envset.sh
host=optargs=

prepare(){
mkdir -p $builddir/$ARCH-build
if [$ARCH=="armeabi-v7a"]
then setarm32ENV host=arm-linux fi
if [$ARCH=="arm64-v8a"]
then setarm64ENV host=aarch64-linux fi
optargs="--enable-single --with-slow-timer"
}

build(){
cd $builddir/$ARCH-build
PKG_CONFIG_LIBDIR="${pkgconfigpath}" ../configure "$@$optargs \
--enable-threads --enable-shared --host=$host >$buildlog 2>&1
$MAKEVERBOSE=1 >>$buildlog 2>&1
ret=$?
cd $OLDPWD
return $ret
}

package(){
cd $builddir/$ARCH-build
$MAKEVERBOSE=1 install >>$buildlog 2>&1
cd $OLDPWD
if [$ARCH=="armeabi-v7a"];then unsetarm32ENV;fi
if [$ARCH=="arm64-v8a"];then unsetarm64ENV;fi
unsethost optargs
}

check(){
cd $builddir/$ARCH-build
sed -i '/.*check-local: bench$(EXEEXT)/c\check-local: #bench$(EXEEXT)' tests/Makefile
sed -i "s#/usr/bin/sed#sed#g" tests/bench
sed -i "s#/bin/bash#/data/CIusr/bin/bash#g" tests/Makefile tests/bench
cd $OLDPWDecho "The test must be on an OpenHarmony device!"
}

cleanbuild(){
rm -rf ${PWD}/$builddir
}

【实战案例 2】tassl 的 HPKBUILD（带依赖加密库，configure 编译 + 补丁适配）

# Copyright (c) 2023 Huawei Device Co., Ltd.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# Contributor: Maintainer <[email protected]>
# Maintainer: Maintainer <[email protected]>
pkgname=tassl
pkgver=1.1.1
pkgrel=0
pkgdesc="TASSL is an SSL/TLS protocol implementation that supports national secret algorithms"
url="https://github.com/jntass/TASSL-1.1.1"
archs=("armeabi-v7a" "arm64-v8a")
license=("OpenSSL")
depends=(openssl_1_1_1w zlib_1_3_1)
makedepends=()
commitId="a30d107669fdf7d6909b10f1e179de4aaff38ff5"
source="https://github.com/jntass/$pkgname-$pkgver/archive/$commitId.zip"
autounpack=true
downloadpackage=true
buildtools="configure"
builddir=TASSL-${pkgver}-$commitId
packagename=$builddir.zip
source envset.sh
patchflag=true

prepare(){
if $patchflag
then
cd $builddir
patch -p1 <`pwd`/../tassl_oh_pkg.patch >>$publicbuildlog 2>&1
patchflag=false
cd $OLDPWD
fi
cp $builddir${builddir}-${ARCH}-build -rf
if [$ARCH=="armeabi-v7a"];then setarm32ENV;elif [$ARCH=="arm64-v8a"];then setarm64ENV;else echo "${ARCH} not support";return -1;fi
}

build(){
cd $builddir-$ARCH-build
./config "$@" no-asm >$buildlog 2>&1
$MAKE >>$buildlog 2>&1
ret=$?
cd $OLDPWD
return $ret
}

package(){
cd $builddir-$ARCH-build
mkdir -p ${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/
$MAKE install >>$buildlog 2>&1
cd $OLDPWD
}

check(){
if [$ARCH=="armeabi-v7a"];then unsetarm32ENV;elif [$ARCH=="arm64-v8a"];then
cd $builddir-$ARCH-build
sed -i.bak "s|PERL=/usr/bin/perl|PERL=/data/CIusr/bin/perl|g" ./Makefile
maketest >>$buildlog 2>&1
cd $OLDPWD
unsetarm64ENV
else echo "${ARCH} not support";return -1;fi
echo "The test must be on an OpenHarmony device!"
}

cleanbuild(){
rm -rf $builddir-$ARCH-build $packagename$builddir
}

HPKCHECK：标准化测试校验脚本

该文件是鸿蒙化适配的测试标准文件，定义了 C/C++ 库在鸿蒙设备端的测试逻辑，所有库的 HPKCHECK 结构一致，仅需修改测试命令即可。

# This is an example HPKCHECK file. Use this as a start to creating your own,
# and remove these comments.
# Contributor: Your Name <[email protected]>
# Maintainer: Your Name <[email protected]>
source HPKBUILD > /dev/null 2>&1
# 导入 HPKBUILD 的元信息
logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log # 测试前准备，无则留空
checkprepare(){
return 0
}

# 鸿蒙设备端核心测试接口，所有测试逻辑写在这里
openharmonycheck(){
res=0
cd ${builddir}/${ARCH}-build
ctest >${logfile} 2>&1
# 测试命令，按需修改为 make test/ctest 等
res=$?
cd $OLDPWD
return $res
}

其他 4 个文件：标准化无定制成本

• README.OpenSource：固定格式，填写库名、版本、开源协议、源码地址即可；
• README_zh.md：填写编译步骤、适配说明、使用方式，无固定格式；
• SHA512SUM：可选，无需校验则不创建，需要则生成源码包的 sha512 哈希值即可；
• xxx_oh_pkg.patch：按需创建，解决鸿蒙编译的兼容性问题，比如路径适配、接口兼容、编译报错等，补丁文件通过 patch -p1 命令在 prepare 阶段执行。

C/C++ 库鸿蒙化的核心编译逻辑

所有 C/C++ 库的编译均基于鸿蒙交叉编译环境，核心要点如下，也是 HPKBUILD 中最核心的逻辑：

1. 架构支持：固定适配 armeabi-v7a(arm32) 和 arm64-v8a(arm64) 两大主流架构；
2. 环境配置：通过 source envset.sh 导入鸿蒙交叉编译环境变量，通过 setarm32ENV/setarm64ENV 设置对应架构的编译环境；
3. 编译方式：支持 configure/make/cmake 三种主流 C/C++ 编译方式，官方均做了兼容；
4. 编译产物：最终编译产物会安装到 ${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/ 目录，鸿蒙系统可直接调用；
5. 测试要求：所有 C/C++ 库的测试均需在鸿蒙真机设备上执行，模拟器暂不支持完整测试。

鸿蒙原生：仓颉语言三方库生态 & 适配指南

仓颉（CangJie）是 OpenHarmony 官方原生编程语言，为鸿蒙而生，主打高性能、简洁语法、原生鸿蒙适配，是鸿蒙未来的核心开发语言。其核心定位是鸿蒙原生开发的首选语言，替代部分 C/C++ 和 ArkTS 的开发场景，生态正在快速建设中。

仓颉三方库核心资源

• 仓颉官方开源库合集：https://gitcode.com/cj-awesome
• 仓颉库标准化适配模板：https://gitcode.com/cj-awesome/template
• 仓颉语言官方文档：https://cangjie-lang.cn/playground
• 仓颉鸿蒙生态文档：https://atomgit.com/openharmony-sig/docs_cangjie

仓颉库适配特点

1. 仓颉库为鸿蒙原生设计，无需鸿蒙化适配，直接开发即可运行在鸿蒙设备上；
2. 官方提供了标准化的库开发模板，所有仓颉三方库均遵循统一规范；
3. 仓颉可无缝调用鸿蒙的 C/C++ 库，与上文的通用 C/C++ 库生态形成互补。

鸿蒙化适配核心总结 & 最佳实践

适配优先级 & 成本排序（从低到高）

1. 纯 Dart Flutter 库：零成本，无需适配，直接复用；
2. 仓颉语言三方库：零成本，原生鸿蒙支持，直接开发；
3. 无 Android/iOS 目录的跨端库：零成本，直接复用；
4. 通用 C/C++ 三方库：低成本，6 个标准化文件，模板复用，仅需修改元信息和编译逻辑；
5. 带原生桥接层的跨端库（Flutter/RN/Cordova）：中成本，基于官方适配版的桥接层修改，无需重构；
6. PC 命令行工具/桌面端工具：中高成本，基于 C/C++ 交叉编译方案移植，无标准化模板。

核心原则

1. 所有鸿蒙化适配均遵循官方标准化方案，不做自定义适配，降低维护成本；
2. 跨端框架优先使用官方的 XX-OH 适配版本，不做自研适配；
3. C/C++ 库严格遵循 6 个文件的标准化适配方案，这是鸿蒙官方的硬性规范；
4. 仓颉语言是鸿蒙未来的核心，优先在新项目中使用仓颉开发原生能力。

核心资源汇总

OpenHarmony 的生态建设已经进入标准化、规模化阶段，从主流跨端框架到底层 C/C++ 库，从移动端到 PC 端，从第三方语言到原生仓颉语言，形成了完整的生态体系和适配规范。对于开发者而言，鸿蒙化适配不再是高成本的自研工作，而是基于官方标准的低成本复用与修改。

• Flutter-OH：https://atomgit.com/OpenHarmony-Flutter
• RN-OH：https://atomgit.com/openharmony-rn
• Cordova-OH：https://atomgit.com/OpenHarmony-Cordova
• Electron-OH：https://atomgit.com/OpenHarmony-electron
• C/C++ 库适配模板：https://gitcode.com/openharmony-sig/tpc_c_cplusplus
• 仓颉库合集：https://gitcode.com/cj-awesome