鸿蒙 PC 三方库移植实战 · 直播课件（详细教案）

特立独行的猫a2026-05-15 12:32

本课件为直播教案专用，含所有链接、脚本、命令和参考文档对应关系。

目录

0. 参考资料索引

0.1 本课件依赖的原始文档

编号 文档标题 对应章节
D01 鸿蒙PC命令行移植直播大纲 全文结构来源
D02 鸿蒙PC命令行移植直播课件（内部配套详细版） 详细技术点来源
D03 鸿蒙PC平台三方库移植，使 Lycium 移植 pngquant 的实践总结 §2.2, §3
D04 使用 vcpkg 为鸿蒙下载与安装三方库实践指南 §2.3
D05 使用 vcpkg 将 pngquant 命令行移植到鸿蒙 PC §2.3, §3
D06 HarmonyOS 鸿蒙三方库移植：选 vcpkg 还是 lycium_plusplus §2 方案对比
D07 build_in_harmonyos 介绍及使用 §2.5
D08 移植 FFmpeg 8.1 到鸿蒙 PC 完整指南 §2.1
D09 鸿蒙PC生态三方软件移植：开发环境搭建及三方库移植指南 §1.3, §4
D10 低成本搭建鸿蒙PC运行环境：基于 Docker 的 x86_64 服务器 §1.2
D11 鸿蒙PC命令行适配解决 configure 报错 §2.1 FAQ

0.2 社区与仓库链接汇总

链接 说明
https://harmonypc.csdn.net/ 鸿蒙 PC 开发者社区
https://www.openharmony.cn/ OpenHarmony 官网
https://gitcode.com/OpenHarmonyPCDeveloper OpenHarmonyPCDev 组织
https://atomgit.com/OpenHarmonyPCDeveloper/build_in_harmonyos build_in_harmonyos 仓库
https://gitcode.com/OpenHarmonyPCDeveloper/build_in_harmonyos （镜像）
https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs 预编译分发仓
https://gitcode.com/OpenHarmonyPCDeveloper/ohos_vcpkg vcpkg 鸿蒙仓（社区镜像）
https://git.qt.io/jobor/vcpkg Qt 官方 vcpkg fork
https://git.qt.io/jobor/vcpkg-tool Qt 官方 vcpkg-tool fork
https://www.qt.io/blog/building-libraries-for-harmonyos-with-vcpkg Qt 官方博文
https://ffmpeg.org/ FFmpeg 官网
https://ffmpeg.org/download.html FFmpeg 源码下载
https://github.com/FFmpeg/FFmpeg FFmpeg GitHub 仓库
https://gitcode.com/openharmony/startup_appspawn appspawn（HNP 说明）

一、开场与环境搭建（15min）

1.1 背景与目标（3min）

核心信息：

  • 鸿蒙 PC 生态需要大量三方库移植
  • 目标：让开发者能低成本、可复现地将 C/C++ 命令行工具移植到鸿蒙
  • 今天演示的案例：pngquant（PNG 图片压缩工具）
  • 今天的收获：掌握三种移植路径 + AI 自动化框架的使用

ppt/keynote 建议：展示一张"鸿蒙 PC 软件生态"的架构图，突出底层库层。

1.2 环境搭建（7min）

A. Windows 宿主
工具 说明
DevEco Studio 图形化管理 SDK 版本
WSL 推荐在 WSL 中执行编译脚本
Docker Desktop 可选，用于跑鸿蒙容器

注意：编译脚本建议在 WSL / Linux 执行，路径和脚本兼容性更好。

B. WSL（Ubuntu 22.04 / 24.04）

为什么选 WSL：与 Linux 服务器、CI 环境一致；cmake/make/git/pkg-config 文档最全。

Ubuntu 22.04 换源：

bash 复制代码 
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo vim /etc/apt/sources.list
# 将 jammy 源改为 mirrors.aliyun.com
sudo apt-get update && sudo apt-get upgrade

Ubuntu 24.04 换源（源文件位置变更）：

bash 复制代码 
# 官方源配置在 /etc/apt/sources.list.d/ubuntu.sources
# 可换清华/中科大/阿里/网易
sudo vim /etc/apt/sources.list.d/ubuntu.sources
# 修改后：
sudo apt-get update && sudo apt-get upgrade -y

安装基础包：

bash 复制代码 
sudo apt install -y python3 python3-pip git cmake ninja-build make pkg-config automake libtool
# 可选：将 python 默认指向 python3
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1
C. 云服务器 x86_64

推荐配置：

  • 系统：Ubuntu 24.04 LTS
  • 规格：2C4G 起（够用）
  • 价格：≈ ¥50-100/年

一年几十块钱，随时随地 SSH 上去干活，比 WSL 更稳定。

D. 鸿蒙 PC 本机（真机）

关键命令：

bash 复制代码 
# 查看系统信息
uname -a
# 检查 NDK/Toolchain
oh-sdk -v

当前真机环境限制：

  • /tmp 可能只读 → 设置 TMPDIR=$HOME
  • 无 GCC → 必须用 Clang
  • 需要 ELF 签名才能执行
E. Docker 鸿蒙容器（重点推荐·低成本方案）

镜像提供者 ：社区大佬 hqzing
镜像名 ：hqzing/docker-mini-openharmony:latest

Windows Docker Desktop：

json 复制代码 
// Docker Engine 增加国内镜像
"registry-mirrors": ["https://docker.1ms.run"]

Linux x86_64 服务器完整步骤：

bash 复制代码 
# 第一步：安装 Docker（如果还没有）
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

# 第二步：注册 ARM64 仿真支持（只需一次）
docker run --rm --privileged docker.1ms.run/tonistiigi/binfmt --install arm64

# 验证注册成功
ls /proc/sys/fs/binfmt_misc/qemu-aarch64

# 第三步：拉取并运行鸿蒙容器
docker run --name=ohos -itd --platform linux/arm64 docker.1ms.run/hqzing/docker-mini-openharmony:latest

# 第四步：进入容器
docker exec -it ohos sh

# 宿主机 ↔ 容器文件拷贝
docker cp ./pngquant ohos:/root/
docker cp ohos:/root/log.txt ./

容器内可测试的内容：

  • 运行预编译的 ohos-neovim
  • 测试自行编译的 axel 命令行
  • 对比 curl 与 axel 下载耗时

1.3 脚手架与 HNP 标准化（5min）

SDK 下载与配置
bash 复制代码 
cd ~

# 下载 SDK（以 Daily 版本为例，请以官网实际包名为准）
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"
wget -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

验证点：确认以下路径存在

bash 复制代码 
ls ~/ohos-sdk/linux/native/build/cmake/ohos.toolchain.cmake
# 若不存在，后续 CMake 交叉编译会失败
HNP 安装目录（鸿蒙本机）
bash 复制代码 
sudo mkdir -p /data/service/hnp
sudo chmod 777 -R /data/service/hnp
下载构建脚手架 build
bash 复制代码 
cd ~
git clone git@gitcode.com:OpenHarmonyPCDeveloper/build.git
cd ~/build/code/
git clone git@gitcode.com:OpenHarmonyPCDeveloper/cmdtree.git -b master
HNP 部件路径规则
复制代码 
${HNP_PUBLIC_PATH}/<部件名>.org/<部件名>_<版本号>
# 示例：/data/service/hnp/tree.org/tree_2.2.1
hnp.json 最小示例
json 复制代码 
{
  "type": "hnp-config",
  "name": "tree",
  "version": "2.2.1",
  "install": {}
}

对于 FFmpeg 这类带动态库的部件，hnp.json 包含：

json 复制代码 
{
  "type": "hnp-config",
  "name": "ffmpeg",
  "version": "8.1",
  "install": {
    "bins": ["ffmpeg", "ffprobe"],
    "libs": ["libavcodec.so", "libavformat.so", ...]
  }
}
顶层 build.sh 执行入口
bash 复制代码 
cd ~/build
./build.sh --sdk /root/ohos-sdk/linux

build.sh 内部逻辑：

  • 解析 --sdk → 设置 OHOS_SDK
  • 根据 uname 判断：
    • OpenHarmony → 本机工具链
    • HarmonyOS → 本机 HMOS_TOOL_CHAIN_PATH
    • 其他（Linux）→ 交叉编译 ${OHOS_SDK}/native/llvm/bin/
  • 统一导出：CC/CXX/LD/AR、SYSROOT、PKG_CONFIG_*
  • 当 BUILD_BY_DEPENDENCY=true → 读 dependency.json 执行多仓构建
dependency.json 示例
json 复制代码 
{
  "name": "tree",
  "branch": "2.2.1_ohos",
  "url": "git@gitcode.com:OpenHarmonyPCDeveloper/cmdtree.git"
}
Native 分发链路（四步）
复制代码 
源码/二进制 → 装入目录 + hnp.json → hnpcli pack → .hnp → 打入 hap → 签名 hap

二、核心路径：三种方案详解（35min）

2.1 传统方式：直接交叉编译（8min）

适用场景：

  • 依赖极少的小项目（single .c 文件）
  • 需要逐项控制编译/链接参数的场景
  • 教学演示，理解交叉编译本质
FFmpeg 8.1 移植关键挑战
挑战 对照摘要
Clang 与 GCC 差异 全套换 llvm-* 工具 + lld 链接器
Musl 与 glibc 注入 -D__MUSL__=1、-D__OHOS__ 宏
缺失图形栈 --disable-vulkan、--disable-libdrm 先关闭
交叉路径配置 --sysroot、--target=aarch64-linux-ohos、PKG_CONFIG_*
环境变量模板
bash 复制代码 
export OHOS_SDK="/root/ohos-sdk/linux"
export COMPILER_TOOLCHAIN=${OHOS_SDK}/native/llvm/bin
export SYSROOT=${OHOS_SDK}/native/sysroot
export TARGET="aarch64-linux-ohos"
export LIB_PATH="$SYSROOT/usr/lib/$TARGET"

# 工具链别名
export CC="${COMPILER_TOOLCHAIN}/clang"
export CXX="${COMPILER_TOOLCHAIN}/clang++"
export AR="${COMPILER_TOOLCHAIN}/llvm-ar"
export LD="${COMPILER_TOOLCHAIN}/ld.lld"
export NM="${COMPILER_TOOLCHAIN}/llvm-nm"
export RANLIB="${COMPILER_TOOLCHAIN}/llvm-ranlib"
export STRIP="${COMPILER_TOOLCHAIN}/llvm-strip"
FFmpeg configure 关键参数
bash 复制代码 
./configure \
  --target-os=linux \
  --arch=aarch64 \
  --enable-cross-compile \
  --cc="$COMPILER_TOOLCHAIN/clang" \
  --cxx="$COMPILER_TOOLCHAIN/clang++" \
  --sysroot="$SYSROOT" \
  --extra-cflags="--target=aarch64-linux-ohos -fPIC -D__MUSL__=1 -D__OHOS__ -fstack-protector-strong" \
  --extra-ldflags="--target=aarch64-linux-ohos --sysroot=$SYSROOT -fuse-ld=lld -L$LIB_PATH" \
  --enable-shared --disable-static \
  --disable-vulkan --disable-libdrm \
  --disable-doc --disable-ffplay
完整编译脚本（FFmpeg 8.1）
bash 复制代码 
#!/bin/bash
# file: build_ohos.sh
# FFmpeg 8.1 鸿蒙交叉编译脚本

# --- SDK路径配置（根据实际修改） ---
OHOS_SDK="/root/ohos-sdk/linux"
COMPILER_TOOLCHAIN=${OHOS_SDK}/native/llvm/bin/
SYSROOT=${OHOS_SDK}/native/sysroot
TARGET="aarch64-linux-ohos"
LIB_PATH="$SYSROOT/usr/lib/$TARGET"

# --- HNP 路径配置 ---
HNP_PUBLIC_PATH=/data/service/hnp/
FFMPEG_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/ffmpeg.org/ffmpeg_8.1
ARCHIVE_PATH=${PWD}/output
HNP_TOOL=${OHOS_SDK}/toolchains/hnpcli

make clean
mkdir -p ${HNP_PUBLIC_PATH} ${FFMPEG_INSTALL_HNP_PATH} ${ARCHIVE_PATH}
chmod 777 -R ${HNP_PUBLIC_PATH}

# configure
./configure \
  --prefix=${FFMPEG_INSTALL_HNP_PATH} \
  --enable-cross-compile \
  --target-os=linux \
  --arch=aarch64 \
  --cpu=armv8-a \
  --host-cc=gcc \
  --cc="$COMPILER_TOOLCHAIN/clang" \
  --cxx="$COMPILER_TOOLCHAIN/clang++" \
  --as="$COMPILER_TOOLCHAIN/clang" \
  --nm="$COMPILER_TOOLCHAIN/llvm-nm" \
  --ar="$COMPILER_TOOLCHAIN/llvm-ar" \
  --ranlib="$COMPILER_TOOLCHAIN/llvm-ranlib" \
  --strip="$COMPILER_TOOLCHAIN/llvm-strip" \
  --sysroot="$SYSROOT" \
  --extra-cflags="--target=$TARGET -fPIC -D__MUSL__=1 -D__OHOS__ -fstack-protector-strong" \
  --extra-ldflags="--target=$TARGET --sysroot=$SYSROOT -fuse-ld=lld -L$LIB_PATH" \
  --enable-shared --disable-static --disable-asm --disable-doc \
  --enable-ffmpeg --disable-ffplay --disable-ffprobe \
  --enable-pic --enable-gpl --enable-nonfree \
  --disable-logging --disable-vulkan --disable-libdrm

make VERBOSE=1 -j$(nproc)
make install

# 生成 HNP 包
cp hnp.json ${FFMPEG_INSTALL_HNP_PATH}/
pushd ${FFMPEG_INSTALL_HNP_PATH}/../
    ${HNP_TOOL} pack -i ${FFMPEG_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
    tar -zvcf ${ARCHIVE_PATH}/ohos_ffmpeg_8.1.tar.gz ffmpeg_8.1/
popd

执行 ：./build_ohos.sh

术语一览
参数 含义
--target-os=linux 目标 OS 类型（FFmpeg 识别）
--arch=aarch64 目标架构（ARMv8 64位）
--cc="$COMPILER_TOOLCHAIN/clang" 指定交叉编译器
--sysroot="$SYSROOT" 系统根目录（含 musl libc）
-fuse-ld=lld 强制使用 LLVM lld 链接器
-D__OHOS__ 鸿蒙平台宏定义
常见问题：configure 报错

现象 ：configure: error: C compiler cannot create executables

排查步骤：

bash 复制代码 
# 1. 确认编译器路径
which clang
$CC --target=aarch64-linux-ohos --sysroot=$SYSROOT hello.c -o hello

# 2. 确认 sysroot 存在
ls $SYSROOT/usr/lib/aarch64-linux-ohos/

# 3. 确认 crti.o 存在
find $SYSROOT -name "crti.o"

# 4. 如果 OS 不被识别，换用
--host=aarch64-unknown-linux-musl
# 或更新 config.sub：
wget -O build-aux/config.sub https://git.savannah.gnu.org/cgit/config.git/plain/config.sub

2.2 Lycium / lycium_plusplus 方案（8min）

框架定位
  • Lycium 是 OpenHarmony 社区主推的三方库编译框架
  • 核心抽象：HPKBUILD 脚本（类似 Arch Linux 的 PKGBUILD）
  • 自动处理：依赖树解析、prepare→build→package→archive、多架构循环、HNP 打包

仓库结构：

复制代码 
lycium/
├── lycium/          # 框架核心
├── thirdparty/      # 三方库
├── community/       # 社区贡献
└── external_deps/
    └── module.json  # 外仓拉取
入口对照
脚本 场景
./build.sh Linux/macOS/Cygwin 上交叉编译为主
./build_local.sh 鸿蒙 PC 本机编译（uname 以 Harmo 开头时走本机 clang）
pngquant 适配要点
项 内容
版本 2.18.0（示例）
协议 GPL-3.0-or-later
依赖链 zlib → libpng → pngquant (+ lcms2 可选)
子模块 git clone --recursive（包含 libimagequant）
buildtools configure（勿误设为 cmake）
关键 export export PKG_CONFIG_LIBDIR="${pkgconfigpath}"
编译命令 ./build.sh zlib libpng lcms2 pngquant
产物路径 lycium/usr/pngquant/<ARCH>/bin/pngquant
HPKBUILD 核心逻辑
bash 复制代码 
pkgname=pngquant
pkgver=2.18.0
depends=("libpng" "zlib" "lcms2")

source=("github.com/kornelski/pngquant.git")

build() {
    # 关键：让 pkg-config 找到交叉编译的依赖
    export PKG_CONFIG_LIBDIR="${pkgconfigpath}"
    
    ./configure "$@" \
        --with-libpng="${pngroot}" \
        --with-lcms2 \
        --disable-sse \
        --extra-cflags="${extra_cflags}" \
        --extra-ldflags="${extra_ldflags}"
    
    make -j$(nproc)
}

package() {
    make DESTDIR="${pkgdir}" install
}

关键注意点：

  1. PKG_CONFIG_LIBDIR 必须 export（不是普通变量）
  2. --disable-sse：交叉编译时必须关掉 SSE 检测，否则在 ARM 上误检
  3. "$@"：承接框架传入的 --prefix 等参数
  4. depends 写库名（框架自动找依赖），makedepends 才写命令
常见问题 FAQ
现象 原因 处理
libpng not found PKG_CONFIG_LIBDIR 未 export 按上节修正
路径不一致 pngroot 与实际 usr/<pkgname>/<ARCH> 不符 改 HPKBUILD 中路径变量
makedepends 填库名 Lycium 用 which 查命令 库只放 depends，命令放 makedepends
configure 报 OS 不识 config.sub 太旧 更新到最新版

2.3 vcpkg-ohos 方案（8min）

背景

Qt 团队官方博文（2026年4月10日）：

"我们目前正在将 Qt 移植到 HarmonyOS。我们的 CI 需要一些专为 HarmonyOS 构建的第三方库。之前我们维护了一个手写的 shell 脚本逐个构建库。现在，借助我们修改后的 vcpkg 分支，该脚本只需一条命令即可完成。"

文档链接：https://www.qt.io/blog/building-libraries-for-harmonyos-with-vcpkg

从零搭建

Step 1：编译 vcpkg-tool（Qt fork 的 ohos 分支）

bash 复制代码 
# 方式 A：Qt 官方源
git clone https://git.qt.io/jobor/vcpkg-tool.git -b ohos ~/vcpkg-tool

# 方式 B：GitCode 镜像（推荐，国内快）
git clone https://gitcode.com/qq8864/vcpkg-tool.git -b ohos ~/vcpkg-tool

cd ~/vcpkg-tool
cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
ninja -C build
# 产物：build/vcpkg 可执行文件

Step 2：准备 registry

bash 复制代码 
# 方式 A：Qt 官方
git clone https://git.qt.io/jobor/vcpkg.git -b ohos ~/vcpkg

# 方式 B：GitCode 镜像（推荐）
git clone https://gitcode.com/qq8864/vcpkg.git -b ohos ~/vcpkg

# 放入 vcpkg 可执行文件
cd ~/vcpkg
cp ~/vcpkg-tool/build/vcpkg ./
export VCPKG_ROOT=~/vcpkg

Step 3：设置 SDK 路径

bash 复制代码 
export OHOS_SDK_ROOT=/root/ohos-sdk/linux/
# 验证点：该目录下应有 native/build/cmake/ohos.toolchain.cmake
ls $OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake
Triplet 表
Triplet ABI 说明
arm64-ohos arm64-v8a 主要目标（鸿蒙 PC / 手机）
arm-ohos armeabi-v7a 32位 ARM 设备
x64-ohos x86_64 x86_64 模拟器

注意：产物为动态库，无版本后缀 soname → 打包与升级需团队约定。

安装三方库
bash 复制代码 
# 基本用法（--triplet 简写）
vcpkg install --triplet arm64-ohos libpng zlib

# 安装 pngquant
vcpkg install pngquant:arm64-ohos

# 裁剪特性（去掉 lcms2）
vcpkg install 'pngquant[core]:arm64-ohos'

# 安装 curl（含工具）
vcpkg install curl[core,tool]:arm64-ohos
CMake 工程集成
bash 复制代码 
cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
  -DVCPKG_TARGET_TRIPLET=arm64-ohos
cmake 复制代码 
# CMakeLists.txt
find_package(PNG CONFIG REQUIRED)
target_link_libraries(myapp PRIVATE PNG::PNG)
常见问题 FAQ
问题 解决方案
GitHub 下载超时 预置 tarball 到 downloads/；使用 ghfast.top 等镜像
zip: not found sudo apt install zip（不影响已安装库）
Could not find OHOS SDK 检查 OHOS_SDK_ROOT 环境变量
OpenSSL x86 asm 混进 OHOS portfile 加 no-asm + no-sse2，同步 --target
真机运行报错 .so 和可执行文件都需要用 binary-sign-tool 签名
pngquant port 技术细节
主题 结论
REF vs tag REF 用 commit SHA ；annotated tag 用 FETCH_REF
submodule 处理 vcpkg 无 .git → 第二次 vcpkg_from_git 拉 libimagequant 再 RENAME 到 lib/
CMake 坑 禁止 $ENV{ProgramFiles(x86)} 破坏 Linux 解析
SSE 处理 VCPKG_CROSSCOMPILING 时传 --disable-sse
Rust 3.x port 多为 native，OHOS 交叉首选 C 2.18.0 port

2.4 AI 辅助排错实践（3min）

建议做法

向 AI 工具提交问题时，附上以下信息：

text 复制代码 
1. 完整编译/链接报错日志（从开始到错误结束）
2. 当前使用的脚本或 port 片段
3. OHOS_SDK_ROOT / VCPKG_ROOT 路径
4. 目标 triplet 与架构名
适合 AI 辅助的环节
环节 说明
交叉参数对齐 让 AI 生成 configure flags
portfile / HPKBUILD 差异草稿 参考现有模板生成
签名命令路径占位符填充 自动适配 SDK 路径
错误日志分析 粘贴报错，AI 定位根因
注意：合并前须人工核对
  • DESTDIR 与安装前缀是否正确
  • 是否误链到宿主机的 /usr/lib
  • PKG_CONFIG_* 是否指向 sysroot 或 Lycium 前缀
  • AI 输出不能替代本地一次干净构建验证

2.5 build_in_harmonyos 自动化框架（8min）

项目定位

"把「编一次、记一次、下次更快」变成一条可重复的流水线，并把经验写成机器和人都能用的档案。"

核心公式：

复制代码 
AI (逻辑推理) + 结构化约束 (SKILL/铁律) + 经验闭环 (错误模式匹配)
= 会成长的自动化工具

当前数据：

  • 已归档：394 个软件
  • 知识图谱：99 条错误模式
  • CLI 子命令：25 个
  • 运维文档：13 篇
双仓架构
仓库 作用 地址
build_in_harmonyos 编译框架 + 知识图谱 + 档案 https://atomgit.com/OpenHarmonyPCDeveloper/build_in_harmonyos
cmd-pkgs 预编译 .tar.gz 分发 https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs
安装部署（鸿蒙本机）

先决条件：

  • OpenHarmony aarch64 设备/模拟器/鸿蒙 PC
  • Python 3.12+（鸿蒙自带）
  • git（鸿蒙自带）
  • clang（鸿蒙自带）

一行命令安装：

bash 复制代码 
wget https://gitcode.com/OpenHarmonyPCDeveloper/build_in_harmonyos/releases/download/init/setup_wizard.sh && \
  chmod 777 ./setup_wizard.sh && \
  ./setup_wizard.sh

安装过程中需要配置：

  1. Git 用户信息（用于自动提交 PR）
  2. AI 大模型 API（推荐 DeepSeek，性价比高）
安装预编译包（无需自己编译）
bash 复制代码 
# 安装 tree 工具
curl -fsSL "https://gitcode.com/goblinrs/cmd-pkgs/releases/download/pkgs/install.sh" | \
  sh -s -- tree 2.1.3

# 装完直接用
tree --version
编译一个新软件
bash 复制代码 
# 初始化（下载源码、创建骨架、检查依赖）
ohc-run.py init pngquant

# 手动编译（框架自动配置交叉参数）
ohc-run.py build pngquant

# 打包
ohc-run.py package pngquant

# 收尾（补丁生成 + 质量门禁 + 归档）
ohc-run.py finish pngquant
从失败中恢复
bash 复制代码 
# 看当前状态
ohc-run.py status

# 从指定步骤继续
ohc-run.py build pngquant --resume-from=3
13 步编译管线
复制代码 
初始化 → 补丁 → 预扫描 → configure → make → make install DESTDIR
→ 安全弹窗测试 → make check(可超时跳过) → staging
→ package(含签名等) → 安装到 ~/usr/local → 用户验证 → finish + G0-G4门禁
质量门禁 G0-G4
等级 要求
G0 干净构建成功
G1 产物完整（bin/lib/include 齐全）
G2 功能验证通过（基本功能正常）
G3 可移植性：已签名、rpath 正确
G4 档案闭合：notes、patches、reports 归档完成
鸿蒙特有问题速查
问题 对策
/tmp 只读 TMPDIR 指到 $HOME
软链覆盖 rm -f && ln -s
ELF 未签名 ohc-run.py sign-elf / binary-sign-tool
无 gcc CC=clang
ncurses .so 崩溃 考虑 --without-shared 静态化

三、深度实操：pngquant 全过程（20min）

3.1 源码与构建系统认知

基本档案：

依赖关系：

复制代码 
pngquant
  ├── libpng → zlib
  └── lcms2 (可选，颜色管理)

3.2 路径一：Lycium 方案实操

bash 复制代码 
# Step 1：克隆 Lycium
git clone https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus.git
cd lycium_plusplus

# Step 2：编译依赖（框架自动解析依赖顺序）
./build.sh zlib libpng lcms2

# Step 3：编译 pngquant
./build.sh pngquant

# Step 4：产物位置
find lycium/usr -name "pngquant"
# 通常在 lycium/usr/pngquant/<ARCH>/bin/pngquant

HPKBUILD 完整参考 （位于 thirdparty/pngquant/HPKBUILD）：

bash 复制代码 
# 元数据
pkgname="pngquant"
pkgver="2.18.0"
pkgdesc="PNG image compression tool"
url="https://github.com/kornelski/pngquant"
license="GPL-3.0-or-later"
depends=("libpng" "zlib" "lcms2")
makedepends=("git")

source=("https://github.com/kornelski/pngquant.git")

# 构建
build() {
    cd "${srcdir}"
    # pkgconfig 路径必须 export
    export PKG_CONFIG_LIBDIR="${pkgconfigpath}"
    
    ./configure "$@" \
        --with-libpng="${pngroot}" \
        --with-lcms2="${lcms2root}" \
        --disable-sse \
        --extra-cflags="${extra_cflags}" \
        --extra-ldflags="${extra_ldflags}"
    
    make -j$(nproc) V=1
}

# 打包
package() {
    make DESTDIR="${pkgdir}" install
}

3.3 路径二：vcpkg 方案实操

bash 复制代码 
# Step 1：确保环境变量
export VCPKG_ROOT=~/vcpkg
export OHOS_SDK_ROOT=/root/ohos-sdk/linux/

# Step 2：一行命令安装
$VCPKG_ROOT/vcpkg install pngquant:arm64-ohos

# 或精简版（去掉 lcms2）
$VCPKG_ROOT/vcpkg install 'pngquant[core]:arm64-ohos'

# Step 3：产物位置（已安装到 vcpkg 目录）
find $VCPKG_ROOT/installed -name "pngquant"
# 约在 $VCPKG_ROOT/installed/arm64-ohos/tools/pngquant/pngquant

3.4 文件签名（关键步骤）

为什么需要签名 ：鸿蒙 PC 真机有安全策略，可执行文件和动态库必须签名才能运行。

签名工具位置 ：${OHOS_SDK}/toolchains/lib/binary-sign-tool

bash 复制代码 
# 签名单个可执行文件
${OHOS_SDK}/toolchains/lib/binary-sign-tool sign \
  -inFile "pngquant" \
  -outFile "pngquant.signed" \
  -selfSign "1"

# 或原地签名（随出随签）
${OHOS_SDK}/toolchains/lib/binary-sign-tool sign \
  -inFile "pngquant" \
  -outFile "pngquant" \
  -selfSign "1"
chmod +x pngquant

# 动态库也要签名！
binary-sign-tool sign -inFile libpng16.so -outFile libpng16.so -selfSign "1"
binary-sign-tool sign -inFile libz.so -outFile libz.so -selfSign "1"

多文件批量签名示例（vcpkg 编译的 curl）：

bash 复制代码 
binary-sign-tool sign -inFile libz.so -outFile libz.so -selfSign "1"
binary-sign-tool sign -inFile libcrypto.so.3 -outFile libcrypto.so.3 -selfSign "1"
binary-sign-tool sign -inFile libssl.so.3 -outFile libssl.so.3 -selfSign "1"
binary-sign-tool sign -inFile libcurl.so -outFile libcurl.so -selfSign "1"
binary-sign-tool sign -inFile curl -outFile curl -selfSign "1"
chmod +x curl

要点：

  • 可执行文件和它依赖的 .so 都要签名
  • 签名后仍须核对 LD_LIBRARY_PATH、工作目录与 rpath 是否一致
  • 未签名时常见表现：Permission denied 或无声退出

四、结果验证与代码提交（15min）

4.1 真机验证（hdc）

bash 复制代码 
# 推送文件
hdc file send ./pngquant /data/local/tmp/
hdc file send ./libpng16.so /data/local/tmp/
hdc file send ./libz.so /data/local/tmp/

# 进入 shell
hdc shell

# 设置环境变量并运行
cd /data/local/tmp
export LD_LIBRARY_PATH=/data/local/tmp
./pngquant --version

# 压缩样张测试
./pngquant --quality=60-80 sample.png --output=compressed.png
ls -lh sample.png compressed.png  # 对比文件大小

验证清单：

  • ./pngquant --version 正常输出版本号
  • 压缩前后图片体积缩小 60%+
  • 肉眼对比图片质量无明显损失
  • 签名前报错 vs 签名后正常运行的对比

4.2 Docker 容器验证（无真机替代方案）

bash 复制代码 
# 将编译产物拷贝进容器
docker cp ./pngquant ohos:/root/
docker cp ./libpng16.so ohos:/root/
docker cp ./libz.so ohos:/root/

# 进入容器
docker exec -it ohos sh

# 运行测试
cd /root
export LD_LIBRARY_PATH=/root
./pngquant --version

4.3 提交代码到社区

不同路线的提交物
路线 提交物 目标仓库
Lycium HPKBUILD、补丁、README.OpenSource、校验文件、构建日志 OpenHarmonyPCDeveloper/lycium_plusplus
vcpkg fork portfile.cmake、triplet 配置、上游友好补丁说明 OpenHarmonyPCDeveloper/ohos_vcpkg
生态脚手架 dependency.json（登记 url/branch）、build_ohos.sh + hnp.json OpenHarmonyPCDeveloper/build
build_in_harmonyos manifest、notes、patches、reports；PR 分区审核 OpenHarmonyPCDeveloper/build_in_harmonyos
提交流程
bash 复制代码 
# 1. Fork 目标仓库
# 2. 创建分支
git checkout -b feat/add-pngquant-port

# 3. 添加适配文件
git add HPKBUILD patches/* README.OpenSource

# 4. 提交
git commit -m "feat: add pngquant 2.18.0 port for arm64-ohos

- cross-compile with lycium_plusplus
- disable SSE for ARM target
- tested on OHOS 6.1.0.27"

# 5. 推送并发起 PR
git push origin feat/add-pngquant-port
提交规范
要求 说明
补丁注释 说明改了什么、为什么改
测试结果 最好附加截图或日志
踩坑记录 写进 notes.md
大二进制 不进源码仓，只交配方与脚本；制品走 release/制品库

五、总结与 Q&A（5min）

5.1 方案总览对照表

方式 核心抽象 适合场景 长处 短处
直接交叉编译 手搓 flags 极简项目 / 教学演示 掌控力强 依赖多时脚本难维护
Lycium++ HPKBUILD + HNP + 设备测 鸿蒙生态原生项目 贴近 OHOS 分发链 学习成本、仓库治理
vcpkg-ohos triplet + port CMake 工程 / Qt 开发者 生态庞大、一行命令 fork 过渡期；签名和 HNP 自建
build 脚手架 dependency.json + build_ohos 团队协作 统一出 HNP/tar 与上游 port 生态并行
build_in_harmonyos OpenDesk Skill + 知识图谱 批量移植 / 规模化 AI 加持、自动沉淀经验 依赖本机/网络环境

5.2 核心教训

  1. 能编译通过 ≠ 能交付运行：签名、库加载路径、HNP/HAP 规范往往占同样多精力
  2. 工程上应以可复现构建为验收标准：固定 SDK 版本、固定 triplet、记录脚本与补丁
  3. 拥抱 AI 但不迷信 AI：自动化输出不能替代本地一次干净构建验证

5.3 社区引导

复制代码 
📢 欢迎加入开源鸿蒙 PC 社区！
🌐 社区地址：https://harmonypc.csdn.net/
📦 三方库仓库：https://gitcode.com/OpenHarmonyPCDeveloper
🤖 AI 编译框架：https://atomgit.com/OpenHarmonyPCDeveloper/build_in_harmonyos

一个人移植一个库，能跑就行；
一群人移植几百个库，生态就成了。

附录 A：开讲环境检查清单

主持人直播前检查

  • WSL 或云机：cmake make git python3 已安装
  • OHOS_SDK_ROOT / OHOS_SDK 路径正确，ohos.toolchain.cmake 存在
  • vcpkg 二进制为 ohos 分支编译产物
  • Lycium：./build.sh zlib 已通过或缓存产物存在
  • Docker 容器：镜像可拉取、binfmt 已注册
  • 真机（如果使用）：hdc 可用、binary-sign-tool 路径确认
  • 演示用 PNG 样张 1~2 张（建议选一张细节丰富的照片）
  • 屏幕共享 / OBS 推流测试正常
  • 终端字体大小适合直播观看（建议 16pt+）

附录 B：常用命令速查表

Lycium 系列

bash 复制代码 
# 编译依赖链
cd lycium && ./build.sh zlib libpng lcms2 pngquant

# 本机构建
./build_local.sh pngquant

# 查看构建产物
find lycium/usr -name "pngquant"

vcpkg 系列

bash 复制代码 
# 设置环境
export OHOS_SDK_ROOT=/root/ohos-sdk/linux/
export VCPKG_ROOT=~/vcpkg

# 安装库
$VCPKG_ROOT/vcpkg install pngquant:arm64-ohos
$VCPKG_ROOT/vcpkg install curl[core,tool]:arm64-ohos

# CMake 接入
cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
  -DVCPKG_TARGET_TRIPLET=arm64-ohos

Docker 系列

bash 复制代码 
# 注册 ARM64 仿真
docker run --rm --privileged docker.1ms.run/tonistiigi/binfmt --install arm64

# 启动容器
docker run --name=ohos -itd --platform linux/arm64 docker.1ms.run/hqzing/docker-mini-openharmony:latest

# 进入容器
docker exec -it ohos sh

# 文件拷贝
docker cp ./pngquant ohos:/root/
docker cp ohos:/root/log.txt ./

脚手架系列

bash 复制代码 
# 构建
cd ~/build && ./build.sh --sdk /root/ohos-sdk/linux

# 查看 ELF 头
$OHOS_SDK_ROOT/native/llvm/bin/llvm-readelf -h ./libpng16.so

# 签名
$OHOS_SDK/toolchains/lib/binary-sign-tool sign \
  -inFile pngquant -outFile pngquant -selfSign "1"

build_in_harmonyos 系列

bash 复制代码 
# 初始化
ohc-run.py init pngquant

# 编译
ohc-run.py build pngquant

# 从失败恢复
ohc-run.py status
ohc-run.py build pngquant --resume-from=3

# 质量检查
ohc-run.py check pngquant

附录 C：SDK 包体来源对照

参考文档 SDK 包类型 说明
FFmpeg 指南 Daily 版本 URL（cidownload.openharmony.cn） 示例：OpenHarmony_6.1.0.27
vcpkg 指南 同域；校验 ohos.toolchain.cmake 是否存在 native + toolchains 两个 zip
鸿蒙 PC 生态指南 Master 全量 ohos-sdk-full 文件名和日期以当时下载页为准
Docker 容器 无需 SDK 容器内已预置
相关推荐
xmdy58663 小时前
Flutter+开源鸿蒙实战｜企业级工具APP Day2 全局网络封装与 Dio 拦截器实战（鸿蒙兼容版）
flutter·开源·harmonyos
xmdy58663 小时前
Flutter+开源鸿蒙实战：企业级工具类APP开发教程（含第三方库适配）
flutter·开源·harmonyos
richard_yuu3 小时前
鸿蒙Stage模型实战｜心晴驿站分层架构与隐私安全设计
安全·架构·harmonyos
Swift社区4 小时前
Flutter / React / ArkUI：在鸿蒙 PC 上怎么选？
flutter·react.js·harmonyos
ZHW_AI课题组4 小时前
调用华为智能云API实现手写图片识别
图像处理·python·机器学习·华为·分类
leon_teacher4 小时前
HarmonyOS 6 鸿蒙APP应用实战：基于 ArkUI V2 打造儿童古诗学习宝 App 从 0 到 1
学习·华为·harmonyos
想你依然心痛5 小时前
HarmonyOS 6（API 23）实战：基于Face AR数字人驱动与Body AR手势控制的“星播工坊“——PC端沉浸式虚拟直播系统
华为·ar·harmonyos·悬浮导航·沉浸光感
哦***75 小时前
真实评测 | FreeBuds Pro 5独立空间音频
华为·音频·harmonyos
前端不太难5 小时前
一个电商鸿蒙 App 的架构设计实战
华为·状态模式·harmonyos
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04【AI】2026 年具身智能模型和世界模型总结05零基础教你claude code 接入 deepseek V406AI科技热点日报 | 2026年5月11日07Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓08人工智能最新动态 AI 日报 · 2026年5月10日09codex app每次打开重连5次Reconnecting问题解决10Cursor 接入 DeepSeek‑V4‑Pro 完整指南（2026 实测）