[鸿蒙PC命令行适配] 移植Aria2文件下载神器最新版到鸿蒙PC的完整教程 (附可运行程序)

aria2 超高速下载工具，它是一款文件下载工具。它支持 HTTP(S)、FTP、SFTP、BitTorrent 和 Metalink 等协议。aria2 可以从多个来源/协议下载文件，并尽可能利用您的最大下载带宽。它支持同时从 HTTP(S)/FTP/SFTP 和 BitTorrent 下载文件，同时将从 HTTP(S)/FTP/SFTP 下载的数据上传到 BitTorrent 服务器群。aria2 使用 Metalink 的数据块校验和，在下载类似 BitTorrent 的文件时自动验证数据块。

一、前言

随着鸿蒙生态（OpenHarmony）的迅速发展，越来越多的应用程序需要高效的文件下载和同步功能。Aria2，作为一款开源、轻量级的多协议、多线程命令行下载工具，其在处理大文件传输、镜像同步和自动化下载任务方面具有显著优势。本文将详细介绍如何将 Aria2 移植到鸿蒙 PC 平台（aarch64），并解决移植过程中可能遇到的技术挑战。

移植成功截图：

1.1 核心价值

Aria2 在多协议支持 、多线程分段下载 和低资源占用等方面表现出色。移植到鸿蒙 PC 平台（aarch64）将为文件传输、镜像同步和自动化下载等场景提供强大的处理能力。

Aria2 官网地址：https://aria2.github.io/

源码仓库：https://github.com/aria2/aria2

源码下载地址：https://github.com/aria2/aria2/releases

移植适配的仓库地址：https://gitcode.com/qq8864/aria2

1.2 项目信息

关键信息	技术参数
库名称	Aria2
开源协议	MIT
源码版本	1.37.0
目标平台	OpenHarmony PC (aarch64)
依赖项	鸿蒙NDK工具链、Musl库

二、适配设计

2.1 技术挑战

工具链兼容性：鸿蒙专用 Clang 工具链与标准 GCC 差异
系统库依赖：Musl C 库替代 glibc 的适配问题
复杂依赖链：精确配置所有依赖库路径
多线程处理：适配鸿蒙系统下的多线程支持

2.2 环境准备（Ubuntu 24.04）

安装基础开发工具：

bash 复制代码

sudo apt update
sudo apt install -y git curl cmake ninja-build gcc g++ make autoconf automake libtool yasm nasm

2.3 配置ohos-sdk

bash 复制代码

 mkdir ~/myprj && cd ~/myprj

下载ohos-sdk：

bash 复制代码

cd ~
wget https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/20250819_020817/version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz
tar -zvxf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz
#注，截止目前有新的SDK了，使用这个吧：
wget  https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-public_ohos/20251209_020142/version-Master_Version-ohos-sdk-public_ohos-20251209_020142-ohos-sdk-public_ohos.tar.gz
cd ~/ohos-sdk/linux
#解压工具链
unzip native-linux-x64-6.0.0.46-Beta1.zip
unzip toolchains-linux-x64-6.0.0.46-Beta1.zip

安装目录设定

bash 复制代码

sudo mkdir -p /data/service/hnp
sudo chmod 777  -R /data/service/hnp

2.4 适配策略

从其他仓库如github上找到aria2的源码，fork到自己的git项目上一份。然后clone到本地，执行以下命令自动生成configure文件。

bash 复制代码

autoreconf -i

接下来执行configure配置。configure配置举例：

bash 复制代码

./configure \
  --host=aarch64-linux-ohos \             # 指定目标平台
  --build=x86_64-linux-gnu \              # 构建平台
  --prefix=/data/service/hnp/aria2.org/aria2_1.36.0 \ # 安装路径
  --enable-static-linking \               # 静态链接
  --disable-shared \                      # 禁用动态链接
  --sysroot="$OHOS_SYSROOT" \             # 系统根目录
  --cc="$OHOS_CLANG" \                    # 鸿蒙专用 Clang
  --cxx="$OHOS_CLANG++" \                 # C++ 编译器
  --extra-cflags="-D__OHOS__ -fPIC" \     # 鸿蒙专属宏定义
  --extra-ldflags="-fuse-ld=lld" \        # 强制 LLD 链接器
  --with-openssl="$OHOS_SYSROOT/usr/include/openssl" \ # OpenSSL 路径
  --with-expat="$OHOS_SYSROOT/usr/include/expat" \     # Expat 路径
  --enable-cross-compile                  # 启用交叉编译

三、实现细节

3.1 环境配置

exports.sh脚本，这个是通用的配置，所有库的编译都用到了。

使用前只需要执行一次：

bash 复制代码

source exports.sh

猫哥整理的exports.sh环境脚本内容如下：

bash 复制代码

echo "hello exports,交叉编译环境配置"

## SDK路径，你唯一需要根据实际的改的地方
SDK_PATH="/root/ohos-sdk/linux"

echo "SDK_PATH:$SDK_PATH"

export OHOS_SDK="$SDK_PATH"
export HNP_PERFIX=

export COMPILER_TOOLCHAIN=${OHOS_SDK}/native/llvm/bin/

BUILD_OS=$(uname)


PYTHON=$(python --version)
echo "python  : $PYTHON"

export CC=${COMPILER_TOOLCHAIN}clang             && echo "CC      : ${CC}"
export CXX=${COMPILER_TOOLCHAIN}clang++          && echo "CXX     : ${CXX}"
export HOSTCC=${CC}                              && echo "HOSTCC  : ${HOSTCC}"
export HOSTCXX=${CXX}                            && echo "HOSTCXX : ${HOSTCXX}"
export CPP="${CXX}  -E"                          && echo "CPP     : ${CPP}"
export AS=${COMPILER_TOOLCHAIN}llvm-as           && echo "AS      : ${AS}"
export LD=${COMPILER_TOOLCHAIN}ld.lld            && echo "LD      : ${LD}"
export STRIP=${COMPILER_TOOLCHAIN}llvm-strip     && echo "STRIP   : ${STRIP}"
export RANLIB=${COMPILER_TOOLCHAIN}llvm-ranlib   && echo "RANLIB  : ${RANLIB}"  
export OBJDUMP=${COMPILER_TOOLCHAIN}llvm-objdump && echo "OBJDUMP : ${OBJDUMP}"
export OBJCOPY=${COMPILER_TOOLCHAIN}llvm-objcopy && echo "OBJCOPY : ${OBJCOPY}"
export NM=${COMPILER_TOOLCHAIN}llvm-nm           && echo "NM      : ${NM}"
export AR=${COMPILER_TOOLCHAIN}llvm-ar           && echo "AR      : ${AR}"

export SYSROOT=${OHOS_SDK}/native/sysroot
export PKG_CONFIG_SYSROOT_DIR=${SYSROOT}/usr/lib/aarch64-linux-ohos
export PKG_CONFIG_PATH=${PKG_CONFIG_SYSROOT_DIR}
export PKG_CONFIG_EXECUTABLE=${PKG_CONFIG_SYSROOT_DIR}

export HNP_TOOL=${OHOS_SDK}/toolchains/hnpcli
export CMAKE=${OHOS_SDK}/native/build-tools/cmake/bin/cmake
export TOOLCHAIN_FILE=${OHOS_SDK}/native/build/cmake/ohos.toolchain.cmake

export WORK_ROOT=${PWD}
export ARCHIVE_PATH=${WORK_ROOT}/output
export COMM_DEP_PATH=${WORK_ROOT}/deps_install

export HNP_PUBLIC_PATH=${HNP_PERFIX}/data/service/hnp/
export MAKE_QUITE_PARAM=" -s "
export CONFIGURE_QUITE_PARAM=" --quiet "

export TARGET_PLATFORM=aarch64-linux-ohos
export TARGET=aarch64-linux-ohos

export CFLAGS="-fPIC -D__MUSL__=1 -D__OHOS__  -fstack-protector-strong --target=${TARGET_PLATFORM} --ld-path=${LD} --sysroot=${SYSROOT} -stdlib=libc++ "
export CXXFLAGS="${CFLAGS} "
export LD_LIBRARY_PATH=${SYSROOT}/usr/lib:${LD_LIBRARY_PATH}
export LDFLAGS="--ld-path=${LD} -Wc,--target=${TARGET_PLATFORM} --sysroot=${SYSROOT} -fuse-ld=lld "
export HOST_TYPE="--host=aarch64-linux --build=aarch64-linux"

#export NCURSES_INSTALL_HNP_PATH="${HNP_PUBLIC_PATH}/ncurses.org/ncurses_v6.4"
mkdir -p ${HNP_PUBLIC_PATH}
mkdir -p ${ARCHIVE_PATH}

chmod 777  -R  ${HNP_PUBLIC_PATH}

mkdir -p code

echo "LDFLAGS:${LDFLAGS}"
#export PKG_CONFIG_PATH="${CUSTOM_PREFIX}/lib/pkgconfig:$PKG_CONFIG_PATH"

3.2 编译脚本 (build_ohos.sh)

bash 复制代码

#!/bin/bash
export ARIA2_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/aria2.org/aria2_1.37.0

make clean
# 设置依赖的OpenSSL路径(注，编译该库前确保openssl已编译)
OPENSSL_PATH=${HNP_PUBLIC_PATH}/openssl.org/openssl_4.0.0

# 编译安装aria2
mkdir -p ${ARIA2_INSTALL_HNP_PATH}

#增加链接依赖的库
CFLAGS="${CFLAGS:-} -I${OPENSSL_PATH}/include"
LDFLAGS="${LDFLAGS:-} -L${OPENSSL_PATH}/lib"
CXXFLAGS="${CFLAGS} "

./configure  --host=aarch64-linux-musl \
               --disable-nls \
               --without-libxml2 \
               --with-openssl \
               #--with-libssl-prefix=${HNP_PUBLIC_PATH}/openssl.org/openssl_4.0.0
               ARIA2_STATIC=yes  \
               --prefix=${ARIA2_INSTALL_HNP_PATH} 

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

# 生成鸿蒙HNP软件包
cp hnp.json ${ARIA2_INSTALL_HNP_PATH}/
pushd ${ARIA2_INSTALL_HNP_PATH}/../
    ${HNP_TOOL} pack -i ${ARIA2_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
    tar -zvcf ${ARCHIVE_PATH}/ohos_aria2_1.37.0.tar.gz aria2_1.37.0/
popd

注意：由于启用了openssl的支持，编译前请先编译openssl库。如果你已有该库，需指定下它的头文件和库文件路径。

bash 复制代码

# 设置依赖的OpenSSL路径(注，编译该库前确保openssl已编译)
OPENSSL_PATH=${HNP_PUBLIC_PATH}/openssl.org/openssl_4.0.0

#增加链接依赖的openssl库
CFLAGS="${CFLAGS:-} -I${OPENSSL_PATH}/include"
LDFLAGS="${LDFLAGS:-} -L${OPENSSL_PATH}/lib"
CXXFLAGS="${CFLAGS} "

执行configure后的配置输出信息如下图所示：

四、关键配置解析

配置项	作用说明	必要性
`--sysroot`	指定鸿蒙系统库和头文件路径	关键
`-fuse-ld=lld`	强制使用 LLVM 链接器避免 GNU 兼容问题	必需
`--disable-shared`	禁用动态链接，只生成静态链接的 Aria2	临时方案
`--extra-cflags`	注入鸿蒙平台标识和位置无关代码参数	必需
`VERBOSE=1`	输出详细编译日志便于排错	建议

五、部署验证

5.1 文件结构

复制代码

aria2_1.37.0/
├── bin/               # 可执行工具
│   └── aria2c         # 主程序
└── hnp.json           # 包描述文件
``

#### 5.2 HNP配置文件示例
```json
{
  "type": "hnp-config",
  "name": "aria2",
  "version": "1.37.0",
  "install": {
  }
}

六、常见使用示例

简单下载：
bash 复制代码
```
aria2c "http://host/file.zip"
```
分 10 个线程提速下载：
bash 复制代码
```
aria2c -s 10 -x 10 "http://host/file.zip"
```
下载 BT 种子：
bash 复制代码
```
aria2c "/path/to/seed.torrent"
```

限制下载速度：

bash 复制代码

aria2c --max-download-limit=500K "http://host/file.zip"

七、优化方向

静态链接：使用静态链接以减少依赖问题和提高移植性。
性能优化：针对鸿蒙系统进行性能调优，提升下载速度。
远程操控：集成 JSON-RPC 和 XML-RPC 接口，实现远程控制。
分布式能力：利用鸿蒙分布式软总线实现跨设备下载任务管理。

移植经验 ：通过 --sysroot 精确指向鸿蒙 NDK 系统库目录是成功关键，禁用动态链接可快速通过编译阶段，性能优化需分阶段实施。

附件资源：

最后，欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/，共同交流进步！