OpenHarmony 跨端生态适配指南 Flutter RN C/C++ 仓颉鸿蒙化

鸿蒙不仅覆盖移动端，也完成了 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++ 库鸿蒙化」的编译方案完成构建。

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

核心结论：任何一款 C/C++ 三方库，仅需 6 个文件即可完成完整的鸿蒙化适配，无多余文件，标准化程度拉满。

适配核心：鸿蒙官方提供了标准化的 C/C++ 库适配模板 + 编译规范，统一采用「交叉编译」+「GN 编译」的方式完成移植，所有开源 C/C++ 库均遵循此标准，适配成本极低。

参考规范：https://gitcode.com/openharmony-tpc/tpc_resource#cc%E8%AF%AD%E8%A8%80

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

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

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

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

3.2 官方标准模板地址（直接复用）

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

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

3.3 核心文件详解 & 实战案例（重点）

3.3.1 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: 小肉头君 <[email protected]>
# 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>$buildlog2>&1
    $MAKEVERBOSE=1>>$buildlog2>&1
    ret=$?
    cd $OLDPWD
    return $ret
}

package(){
    cd $builddir/$ARCH-build 
    $MAKEVERBOSE=1install>>$buildlog2>&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 $OLDPWD
    echo "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: Jeff Han <[email protected]> ,Tao Han <[email protected]> 
# Maintainer: Jeff Han <[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 >>$publicbuildlog2>&1
        patchflag=false 
        cd $OLDPWD
    fi
    cp $builddir${builddir}-${ARCH}-build -rf 
    if [$ARCH=="armeabi-v7a"];then setarm32ENV;
elif [$ARCH=="arm64-v8a"];then setarm64ENV;
elseecho"${ARCH} not support";return -1;fi
}

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

package(){
    cd $builddir-$ARCH-build 
    mkdir -p ${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/ 
    $MAKEinstall>>$buildlog2>&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>>$buildlog2>&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
}

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

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

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

3.4 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 的开发场景，生态正在快速建设中。

4.1 仓颉三方库核心资源

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

4.2 仓颉库适配特点

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_plusplus
• 仓颉库合集：https://gitcode.com/cj-awesome