鸿蒙PC开源软件迁移与多语言三方库移植实战课程讲稿（一、课程概述与环境准备）

特立独行的猫a

15人浏览 · 2026-07-08 21:26:01

特立独行的猫a · 2026-07-08 21:26:01 发布

第1节：课程介绍与开源共建理念（5分钟）

大家好，欢迎来到《鸿蒙PC开源软件迁移与多语言三方库移植实战》课程！我是本课程的主讲嘉宾——CSDN猫哥。

个人博客: blog.csdn.net/qq8864

视频课程地址：https://edu.csdn.net/course/detail/40818

首先做一下自我介绍。我一直活跃在鸿蒙PC生态开源社区，致力于解决实际项目中的三方库移植问题，总结了一套从环境搭建到部署验证的完整方法论。也是开源社区的活跃贡献者，希望通过这门课程，帮大家降低鸿蒙PC生态的开发门槛。

如果有任何问题，都欢迎到我的个人博客中留言交流。

在这里插入图片描述

好，我们先来看一下课程的核心设计。

一、课程目标与核心收获

本课程的目标非常明确：掌握鸿蒙PC平台开源命令行软件和三方库移植的完整流程，从环境搭建到最终部署验证的全链路能力。

通过5小时、18节课的系统学习，你将获得以下五大核心能力：

能力维度	具体内容
环境搭建能力	WSL/虚拟机/Docker+QEMU/真机五维环境独立搭建
C/C++移植能力	Autotools/CMake/Meson三大构建系统适配
命令行移植能力	OpenSSH实战、四种方案灵活选型
AI辅助实战能力	build_in_harmonyos AI框架+NAPI自动封装
社区共建能力	CI/CD集成、PR规范、知识沉淀

二、鸿蒙PC生态全景

核心技术栈：

鸿蒙PC基于Linux内核 + musl libc + NDK工具链。这意味着：

底层使用LLVM/Clang工具链，链接器使用lld
C标准库使用musl而非glibc——这是移植工作中最核心的挑战来源
强制ELF签名机制——所有可执行文件和.so都需要签名后才能运行

核心挑战：

musl/glibc ABI兼容差异：符号命名、线程本地存储布局、函数行为不同
软件依赖管理：开源软件默认假设Linux = glibc，需逐个适配
ELF签名机制：编译后的二进制必须签名才能部署

三、课程结构概览

课程设计为五大部分、18节课程：

部分	主题	时长	节数
Part 1	课程概述与环境准备	25分钟	3节
Part 2	C/C++三方库移植实战	90分钟	5节
Part 3	命令行工具移植实战	60分钟	4节
Part 4	多语言+AI辅助迁移	90分钟	3节
Part 5	总结与社区共建	35分钟	3节

课程特点：实战驱动、案例丰富。每个知识点都配有完整的可复现案例——从libmediainfo到OpenSSH，从pngquant到FFmpeg，从ujson到build_in_harmonyos。

四、开源共建理念

移植工作的最大价值不在于"一个人把所有库都编完"，而在于将经验、补丁、脚本沉淀下来，贡献回社区。

核心理念：

一个人移植一个库，能跑就行
一群人移植几百个库，生态就成了
移植的本质：交叉编译器 + libc适配 + 构建系统补丁
AI辅助通用范式：AI Agent + NAPI封装

好，第1节就到这里。短短5分钟，我们对课程和生态有了全景认识。下面进入第2节——多维度开发环境搭建。

第2节：多维度开发环境搭建（15分钟）

大家好，欢迎来到第2节。环境搭建是移植工作的基石，构建一个高效的开发和验证环境，能让你在后续的移植工作中事半功倍。

一、五位一体的开发环境体系

我们设计了一套五层开发环境体系，从开发、编译到验证形成一个完整的闭环：

Windows宿主（DevEco Studio）
    │
    ├── WSL2 (Ubuntu 24.04) ── 本地编译主力
    ├── 虚拟机Linux (Ubuntu)  ── 环境一致
    ├── 云服务器 (Ubuntu)      ── 7x24持续编译
    ├── 鸿蒙PC 真机             ── 最终验证
    └── Docker 容器             ── 低成本沙盒

二、环境选型建议

最佳推荐组合：

VS Code (Remote-WSL) + Ubuntu 24.04 LTS → 本地编译
Docker + QEMU                            → 快速验证
鸿蒙PC 真机                              → 最终部署

这个组合兼顾了开发效率、验证成本和部署可靠性。

三、Windows宿主环境（WSL）

Windows下强力推荐WSL2作为编译环境。它让你在Windows电脑上拥有完整的Linux终端体验，且与VS Code无缝集成。

关于WSL的安装，详细步骤参见我的个人博客：在 Windows 10 上安装和使用 WSL 2 安装 Ubuntu24详细指南

安装步骤：

第一步：安装WSL2

# 以管理员身份在PowerShell中执行
wsl --install -d Ubuntu-24.04

第二步：配置国内镜像源

# 替换apt源为国内镜像，加速后续软件安装
sudo sed -i 's/archive.ubuntu.com/mirrors.ustc.edu.cn/g' /etc/apt/sources.list
sudo apt update && sudo apt upgrade -y

第三步：安装基础编译工具链

sudo apt install -y \
  python3 python3-pip \
  git curl cmake ninja-build \
  make pkg-config automake libtool \
  gettext autopoint yasm nasm

第四步：安装VS Code Remote-WSL插件
在VS Code中安装"Remote - WSL"插件，然后在WSL终端中输入code .即可打开远程开发窗口。

WSL的独有优势：

与Windows文件系统互访（/mnt/c/）
性能接近原生Linux
无需虚拟机开销
Docker Desktop可直接使用WSL2后端

四、虚拟机Linux环境（Ubuntu）

如果你不使用Windows，或者需要独立的编译环境，虚拟机是最直接的选择。

虚拟机选型建议：

推荐使用VMware Workstation Pro或VirtualBox
Ubuntu 22.04 LTS或24.04 LTS
分配至少4核CPU、8GB内存、40GB磁盘

与WSL的对比：

对比项	WSL2	虚拟机
启动速度	秒级	分钟级
内存占用	动态分配	固定分配
图形界面	仅终端	完整桌面
文件系统	跨Windows访问	独立
适用场景	日常开发编译	全量构建测试

五、云服务器环境（Ubuntu）

对于需要长时间编译、或者本地资源不足的场景，云服务器是最佳选择。

推荐配置：

腾讯云/华为云轻量应用服务器
2核4GB起步
Ubuntu 24.04 LTS
包年费用约38元（新用户优惠）

优势：

7x24小时持续运行，编译任务不中断
性能稳定，资源可弹性扩展
不占用本地电脑资源
随时随地SSH远程登录操作

六、Docker+QEMU低成本容器验证

这是最推荐的验证方案。在没有鸿蒙PC真机的情况下，通过Docker+QEMU在x86_64服务器上模拟ARM64鸿蒙环境。

详细操作步骤参见我的这篇：低成本搭建鸿蒙PC运行环境：基于 Docker 的 x86_64 服务器

关于Ubuntu 系统下docker的安装，这里网上有很多资料，就不多介绍了。在Ubuntu下只需几条简单安装命令。

详细介绍也可以在我的个人博客中搜索到相关内容，如：Windows10下使用WSL安装 Docker和docker compose完整教程

非常不建议直接使用apt get install docker的方式安装。那样安装的是很老的1.x的版本且很可能安装不成功。推荐按猫哥的教程一步步成功安装最新版docker

猫哥的博客是平常的实践总结，并没有刻意写博，都是日常的笔记，自己也经常查阅。

原理： 利用Linux内核的binfmt_misc机制，将QEMU用户态仿真器注册为ARM64程序的处理程序。当系统尝试执行ARM64格式的程序时，内核自动调用QEMU翻译ARM64指令。

4步快速搭建：

步骤1：安装Docker（可选国内镜像源）

# 使用国内镜像源脚本安装
bash <(curl -sSL https://linuxmirrors.cn/docker.sh)
# 配置华为云源 + 毫秒镜像registry

步骤2：注册QEMU多架构支持

# 注册ARM64解释器（使用国内镜像源加速）
docker run --rm --privileged docker.1ms.run/tonistiigi/binfmt --install arm64

注：服务器重启后需要重新执行此命令。注册成功后，宿主机和Docker均可直接运行ARM64二进制程序。

步骤3：拉取并运行鸿蒙容器

# 拉取鸿蒙容器镜像（国内镜像加速）
docker run --name=ohos -itd --platform linux/arm64 \
  docker.1ms.run/hqzing/dockerharmony:latest

步骤4：进入容器体验

docker exec -it ohos sh

# 验证鸿蒙环境
uname -a
# 输出: OpenHarmony aarch64

宿主与容器文件交互：

# 宿主机→容器
docker cp ./编译产物 ohos:/root/

# 容器→宿主机
docker cp ohos:/root/验证结果 ./

验证演示——运行移植好的二进制：

# 在Docker容器中测试axel多线程下载工具
cd /root
./axel -k -n 50 https://github.com/Harmonybrew/ohos-neovim/releases/download/0.11.4/neovim-0.11.4-ohos-arm64.tar.gz

环境优势总结：

✅ 极低成本：复用现有x86_64服务器，无需购置ARM64硬件
✅ 最小可用：提供基础的鸿蒙运行环境
✅ 国内网络优化：全程采用国内镜像源加速
✅ 灵活便捷：Docker容器易于创建、销毁和复用

七、鸿蒙PC真机调试环境

最终验证必须在真机上进行。真机调试需要：

1. 设备连接
通过USB线缆或局域网连接鸿蒙PC与开发机。

2. hdc调试工具
hdc（HarmonyOS Device Connector）是官方调试工具，功能包括：

# 设备管理
hdc list targets          # 列出已连接的设备

# 文件传输
hdc file send 本地文件  目标路径    # 推送到设备
hdc file recv 目标路径  本地文件    # 从设备拉取

# 命令行执行
hdc shell                 # 进入设备终端

# 应用安装
hdc install app.hap       # 安装HAP包

3. 权限配置

设备端：设置→系统→开发者选项→开启开发者模式
隐私和安全→高级→开启"运行来自非应用市场的扩展程序"
开发机：首次连接需确认设备授权

鸿蒙PC关键特性与约束：

特性	说明
工具链	SDK内置LLVM/Clang，链接器使用lld
C库兼容	musl libc，与glibc有差异
安全校验	强制ELF签名，未签名不可执行
调试工具	hdc统一管理设备连接与文件交互
包管理	推荐使用Harmonybrew

好，以上就是第2节的内容。我们完成了五维环境的搭建方法。最后一节，我们来学习SDK配置和HNP标准化。

第3节：SDK配置与HNP标准化（5分钟）

大家好，欢迎来到第3节。环境搭建完成后，我们需要配置SDK工具链。本节虽然只有5分钟，但这是整个课程的技术起点——之后所有编译工作都建立在SDK正确配置的基础上。

一、SDK的获取

OpenHarmony SDK的官方获取渠道有两处：

渠道一：OpenHarmony社区Release文档

https://atomgit.com/openharmony/docs/blob/master/zh-cn/release-notes/OpenHarmony-v6.1-release.md

每当OpenHarmony发布新版本，Release文档中会附带成套的SDK下载链接。

渠道二：OpenHarmony社区流水线

https://dcp.openharmony.cn/workbench/cicd/dailybuild/dailylist

可以下载到任意一天的日构建产物。推荐的下载方式：

交叉编译：选ohos-sdk-full
原生编译：选ohos-sdk-public

二、SDK的下载与解压

# 下载SDK（以日构建版本为例）
sdk_download_url="https://cidownload.openharmony.cn/version/Daily_Version/\
OpenHarmony_6.1.0.27/20260111_020523/version-Daily_Version-\
OpenHarmony_6.1.0.27-20260111_020523-ohos-sdk-public.tar.gz"

curl -o ohos-sdk-public.tar.gz $sdk_download_url
mkdir ohos-sdk
tar -zxf ohos-sdk-public.tar.gz -C ohos-sdk

# 解压工具链
cd ~/ohos-sdk/linux
unzip native-linux-x64-6.1.0.27-Beta1.zip
unzip toolchains-linux-x64-6.1.0.27-Beta1.zip

三、环境变量配置——OHOS_SDK_ROOT

这是最重要的配置步骤。在编译脚本中，我们需要设置OHOS_SDK_ROOT并导出所有工具链路径：

export OHOS_SDK_ROOT="/root/ohos-sdk/linux"

# 编译器路径
export COMPILER_TOOLCHAIN=${OHOS_SDK_ROOT}/native/llvm/bin/
export CC=${COMPILER_TOOLCHAIN}clang
export CXX=${COMPILER_TOOLCHAIN}clang++
export LD=${COMPILER_TOOLCHAIN}ld.lld
export AR=${COMPILER_TOOLCHAIN}llvm-ar
export STRIP=${COMPILER_TOOLCHAIN}llvm-strip

# 系统根目录
export SYSROOT=${OHOS_SDK_ROOT}/native/sysroot

# pkg-config配置
export PKG_CONFIG_SYSROOT_DIR=${SYSROOT}/usr/lib/aarch64-linux-ohos

# 目标平台
export TARGET_PLATFORM=aarch64-linux-ohos

# 编译选项
export CFLAGS="-fPIC -D__MUSL__=1 -D__OHOS__ --target=${TARGET_PLATFORM} --sysroot=${SYSROOT}"

四、SDK工具链全家桶

工具	用途
clang / clang++	交叉编译器（musl-clang变体）
ld.lld	ELF链接器，支持`--code-sign`参数
llvm-strip / llvm-ar	符号裁剪与静态库管理
binary-sign-tool	二进制签名工具
hnpcli	HNP包构建工具
cmake / ninja	构建系统（含ohos.toolchain.cmake）

五、二进制自动签名技术

鸿蒙系统要求所有ELF文件和共享库必须经过签名才能在设备上运行。传统方式使用binary-sign-tool逐个签名：

binary-sign-tool sign -selfSign 1 -inFile my_program -outFile my_program

但逐个签名在复杂项目中极为繁琐。最新技术栈提供了编译时自动签名——通过封装ld.lld链接器实现：

# 替换ld.lld为封装脚本
cd ohos-sdk/linux/native/llvm/bin
rm ld.lld  # 移除原始软链接

lld_absolute_path=$(realpath lld)

# 创建封装脚本：在链接时自动注入--code-sign参数
printf '#!/bin/bash\nexec -a "$0" %s --code-sign "$@"\n' "$lld_absolute_path" > ld.lld
chmod 0755 ld.lld

# 验证签名
clang --target=aarch64-linux-ohos hello.c -o hello
llvm-readelf -S hello | grep codesign
# 应输出：.codesign PROGBITS ...（签名段存在）

签名信息存储在ELF文件的.codesign段中。使用llvm-readelf -S可查看。

关于自动签名的详细介绍，参考猫哥的博文：鸿蒙PC生态三方软件移植：ohos-sdk 生成的库或二进制的自动签名实现

六、HNP（鸿蒙原生包）标准化体系

HNP 是 OpenHarmony 的原生包格式，本质就是一个 ZIP 包，内含二进制、库和 hnp.json 元数据。类比一下就懂了：HNP 之于鸿蒙 ≈ DEB 之于 Debian、MSI 之于 Windows——它是一套标准化的软件打包规范。

但有个关键认知要澄清：HNP 不是必须的。 已签名的二进制直接拷贝到鸿蒙 PC 上也能跑，就像 Linux 程序不以 .deb 形式存在、直接 ./binary 也行一样。HNP 是"锦上添花"的规范格式，不是"离了它不行"的铁律。

那什么时候需要 HNP？当你要通过 HAP 应用分发、走应用市场生命周期管理时，才必须打包为 HNP。 因为 HNP 嵌入 HAP 后，系统能自动完成安装卸载、权限隔离和 PATH 集成，带来三个核心能力：

原子化安装卸载：随 HAP 同生命周期，卸载 HAP 时 HNP 自动清理
权限隔离：公有 HNP（全局可调）vs 私有 HNP（仅宿主可调）
环境自动集成：公有 HNP 的软链接自动加入 PATH

hnp.json 示例——包的"身份证"：

{
  "type": "hnp-config",
  "name": "pngquant",
  "version": "2.18.0",
  "install": { "bins": ["bin/pngquant"], "libs": ["lib/*.so*"] }
}

后续在 lycium 移植案例中，编译完成后框架会自动调用 hnpcli 工具将产物打包为 HNP。更多细节到具体案例中再展开，这里先建立概念。

参考官方文档：https://gitcode.com/openharmony/startup_appspawn/blob/master/service/hnp/README_zh.md

拓展内容：

什么是 HNP？
HNP（OpenHarmony Native Package）是 OpenHarmony 的原生包格式，用于打包原生程序和库。HNP 包本质上是一个 ZIP 文件，包含可执行文件、共享库、配置文件和元数据。

HNP是鸿蒙系统为原生应用与库设计的标准化软件包格式。
关于HNP包的详细介绍，官方文档地址：
https://gitcode.com/openharmony/startup_appspawn/blob/master/service/hnp/README_zh.md
https://gitcode.com/openharmony/startup_appspawn/blob/master/service/hnp/pack/README_zh.md

hnp.json——HNP包的核心元数据：

位于包根目录，定义软件包的身份、依赖关系及安装行为。

{
  "type": "hnp-config",
  "name": "pngquant",
  "version": "2.18.0",
  "arch": "arm64",
  "os": "ohos",
  "summary": "A lossy PNG compressor",
  "depends": ["libpng >= 1.6", "zlib >= 1.2"],
  "install": {
    "bins": ["bin/pngquant"],
    "libs": ["lib/*.so*"]
  }
}

HNP的关键价值：

维度	说明
统一分发标准	简化跨设备、跨架构的依赖管理逻辑
提升兼容性	降低原生应用与系统的开发和部署成本
自动化管控	标准化元数据实现安装、升级、卸载全自动化
规模化基础	为鸿蒙原生生态的规模化发展奠定基础

在使用lycium框架时，HNP是个基础设施。在后续每个移植案例中，编译完成后框架默认会使用hnpcli工具将产物打包为HNP包：

# 打包HNP
hnpcli pack -i package_dir/ -o output.hnp

# 打包tar.gz
tar -zvcf ohos_package.tar.gz package_dir/

但初学者肯定有个疑问,hnp包是必须的吗？必须有它吗？不打成这个包没法用吗？如何安装它？其实也非必须打包成它，看你的用途了。比如vcpkg移植中就没有提到它。你需要清楚的是，啥时候需要用它。

直接拷贝一个命令行到鸿蒙PC上，如果经过了签名，直接运行也是没问题的。HNP包安装使用:可参考下DevBox这个应用。hnp包其实就是个压缩包。可以用zip软件打开查看。系统会将hap包校验解压到对应目录下。

我觉得当前它的主要作用是方便app包对其进行生命周期管理。但是这个包呢，截至目前我没找到有啥命令可以直接安装它，网上你看到的文章中的说可以命令行安装，这个描述是错的。

如果你知道有啥命令行可以安装hnp包？可以告诉我下，据我所知当前的HNP不能单独装，都必须打包成HAP或APP的应用包才行。

关于HNP包的一个更好的理解，其实就记住一句话：就是对比一下windows或linux系统，windows系统下有msi的安装包，linux系统下有deb的安装包，你说我的三方库或命令行，必须打包为HNP吗？

当然你可以打包，也可以以文件的形式也行，这跟应用运行是否依赖它无关系。对比了下其他系统，你是不一下子就豁然开朗了？

注意只是类似，帮助你理解。其实HNP包有它都有的特色功能：

HNP包本质上是一种特殊的鸿蒙原生软件包格式，它允许开发者将编译好的二进制文件、依赖库和配置文件打包成标准化容器。与传统的软件分发方式不同，HNP包具有以下核心优势：

原子化安装卸载：HNP包作为HAP应用的组成部分，支持与宿主应用同生命周期管理
权限隔离机制：通过public/private类型区分，实现精细化的命令访问控制
环境自动集成：安装后自动创建软链接，无需手动配置PATH环境变量

参考链接：https://blog.csdn.net/transformer2023/article/details/155594592 https://blog.csdn.net/m0_57525346/article/details/154846430 https://blog.csdn.net/qq8864/article/details/157426019

也可以在在hap应用中访问Native二进制，以c++语言为例，可以在hap应用代码中通过execv、execve等函数执行二进制。默认公有hnp包软链接路径为/data/service/hnp/bin，默认软链接路径已加入环境变量中。

私有hnp请使用实际路径：/data/app/xxx.org/xxx_yyy/{二进制文件在hnp包中的相对路径如：bin/hnpsample}，其中xxx对应hnp.json中“name”，yyy对应hnp.json中“version”。

示例代码如下：

    pid_t child = fork();
    if (child < 0) {
      OH_LOG_ERROR(LOG_APP, "fork for child process failed %d", errno);
      return;
    }
    if (child == 0) {
        // do execv
        int ret = execv("/data/app/test.org/test_1.1/bin/testBin", NULL);
        OH_LOG_ERROR(LOG_APP, "execv failed errno %d", errno);
        exit(errno);
    } else {
        int status;
        if (waitpid(child, &status, 0) == -1) {
          OH_LOG_ERROR(LOG_APP, "waitpid failed errno %d", errno);
          return;
        }
        // process child exit
        ...
    }

hdc shell执行方法
操作步骤：

从应用市场下载Native软件包hap应用并安装。
通过数据线连接设备，执行hdc shell访问设备。
公有hnp包安装后的物理路径为/data/app/el1/bundle//hnppublic，私有hnp包安装后的物理路径为/data/app/el1/bundle//hnp，userid默认为100。可以进入这些目录下找到安装的Native包文件目录，执行相关二进制。

想了解更多细节，可以到https://gitcode.com/openharmony仓，查阅感兴趣的文档。

更详细的关于HNP包的介绍，参见猫哥的博客：HarmonyOS鸿蒙原生HNP包全解析：从规范到实战的完整指南

好，以上就是第3节的内容。我们完成了SDK的获取配置、工具链全家桶的学习、二进制自动签名技术和HNP标准化体系。至此，第一部分课程结束，后续我们将正式进入第二部分——C/C++三方库移植实战。

第1节回顾： 课程目标、鸿蒙PC生态全景、五大部分结构、开源共建理念

第2节回顾： 五位一体环境（WSL/虚拟机/云服务器/真机/Docker容器）、Docker+QEMU低成本方案、hdc真机调试

第3节回顾： SDK获取配置、OHOS_SDK_ROOT环境变量、工具链全家桶、二进制自动签名、HNP标准化

欢迎进入第二部分——C/C++三方库移植实战！