OpenHarmony Linux 命令行工具适配实战：基于 Cursor × WSL 的 tree 2.2.1 交叉编译与 HNP 打包全流程指南

前言

随着 OpenHarmony PC 生态不断完善，Linux 命令行工具适配成为生态拓展的关键环节，本文以经典目录可视化工具 tree 2.2.1 为案例，基于 Cursor/VS Code + WSL Ubuntu 24.04 技术栈，提供从环境搭建、SDK 配置到交叉编译、HNP 打包的完整可复现实操方案，帮助开发者快速掌握 Windows 侧鸿蒙交叉编译环境搭建核心流程，规避各类适配痛点，助力更多 Linux 开源软件高效融入 OpenHarmony PC 生态，为生态丰富与功能拓展提供实用技术支撑。

前提准备

通过 Microsoft Store 安装 WSL Ubuntu 24.04：打开微软应用商店，搜索 Ubuntu 并选择最新长期支持版本安装，完成后从开始菜单启动对应终端即可

WSL Ubuntu 24.04 系统迁移与重构全流程指南

1、管理员身份运行 Windows PowerShell 后，先通过 wsl --shutdown 关闭所有 WSL 实例，再强制终止 wslhost 和 wslservice 相关进程，忽略终止失败的错误，等待 30 秒确保进程完全停止，最后用 wsl -l -v 查看当前 WSL 分发版的列表及运行状态

# 以管理员身份运行Windows PowerShell，执行以下命令：

# 关闭所有正在运行的WSL实例
wsl --shutdown

# 强制终止wslhost进程，遇到错误时静默处理（不报错）
Stop-Process -Name "wslhost" -Force -ErrorAction SilentlyContinue

# 强制终止wslservice进程，遇到错误时静默处理（不报错）
Stop-Process -Name "wslservice" -Force -ErrorAction SilentlyContinue

# 等待30秒，确保相关进程完全停止
Start-Sleep -Seconds 30

# 列出所有已安装的WSL分发版，并显示其运行状态（名称、状态、WSL版本）
wsl -l -v

2、使用.tar格式备份系统

# 创建WSL备份目录（已存在则忽略）
New-Item -Path "D:\WSL" -ItemType Directory -Force

# 导出Ubuntu-24.04到指定备份文件
wsl --export Ubuntu-24.04 D:\WSL\Ubuntu2404_backup.tar

3、注销原系统释放C盘空间

# 彻底注销/删除 Ubuntu-24.04 WSL 发行版（所有数据会丢失）
wsl --unregister Ubuntu-24.04

4、导入系统到D盘

# 从备份文件导入并创建 Ubuntu-24.04 WSL 发行版（安装路径：D:\WSL\Ubuntu2404）
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu2404 D:\WSL\Ubuntu2404_backup.tar

5、恢复默认用户

# 设置 Ubuntu-24.04 WSL 的默认登录用户为 weishuo
ubuntu2404.exe config --default-user weishuo

6、验证迁移结果

# 列出所有已安装的 WSL 发行版及运行状态
wsl -l -v
# 启动并进入 Ubuntu-24.04 WSL 发行版
wsl -d Ubuntu-24.04

Linux 开发环境初始化与依赖配置

1、更换APT软件源

# 备份 Ubuntu 官方软件源配置文件（避免修改出错后无法恢复）
sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.backup

# 使用 vim 编辑器修改软件源配置文件（用于替换为国内源等操作）
sudo vim /etc/apt/sources.list.d/ubuntu.sources
  • 清华源
Types: deb
URIs: https://mirrors.tuna.tsinghua.edu.cn/ubuntu/
Suites: noble noble-updates noble-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

2、更新软件包

# 更新软件源索引（获取最新的软件包版本信息）
sudo apt update
# 自动升级所有可更新的软件包（-y 自动确认所有提示，无需手动输入y）
sudo apt upgrade -y

3、安装Python环境

# 安装 Python3 及 pip 包管理工具（-y 自动确认安装）
sudo apt install python3 python3-pip -y
# 配置 python 命令默认指向 python3（优先级 1，若有其他版本可调整优先级）
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1

OpenHarmony SDK 获取、安装与环境配置指南

1、下载OpenHarmony SDK

# 下载 OpenHarmony Master 版本完整 SDK（20250819 构建版本）
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

在这里插入图片描述

2、解压SDK包

# 解压 OpenHarmony 完整 SDK 压缩包（z=gz格式，v=显示进度，x=解压，f=指定文件）
tar -zvxf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

在这里插入图片描述

3、解压核心组件

# 解压 native 工具包（Linux x64 架构，6.0.0.46 Beta1 版本）
unzip native-linux-x64-6.0.0.46-Beta1.zip
# 解压 toolchains 工具链包（Linux x64 架构，6.0.0.46 Beta1 版本）
unzip toolchains-linux-x64-6.0.0.46-Beta1.zip

在这里插入图片描述

4、创建鸿蒙软件包安装目录

# 递归创建 /data/service/hnp 目录（-p 自动创建父目录，不存在则新建）
sudo mkdir -p /data/service/hnp
# 递归设置该目录及所有子内容权限为 777（所有用户可读可写可执行，-R 递归应用）
sudo chmod 777 -R /data/service/hnp

在这里插入图片描述

5、获取构建工具，下载鸿蒙构建脚手架

# 切换到当前用户主目录（~ 等价于 /home/用户名）
cd ~
# 从 GitCode 克隆 OpenHarmony PC 开发版构建配置仓库
git clone https://gitcode.com/OpenHarmonyPCDeveloper/build.git

在这里插入图片描述

6、源码准备与适配，下载tree命令鸿蒙适配版源码

# 切换到 build 仓库的 code 子目录（需确保该目录已存在）
cd ~/build/code/
# 从 GitCode 克隆 cmdtree 仓库，指定拉取 master 分支
git clone https://gitcode.com/OpenHarmonyPCDeveloper/cmdtree.git -b master

在这里插入图片描述

7、创建适配配置文件，进入源码目录，添加两个关键适配文件

  • hnp.json 配置文件（）
{
  "name": "tree",
  "version": "2.2.1",
  "description": "递归目录列表显示工具",
  "license": "GPL-2.0",
  "arch": "aarch64",
  "target": "ohos-pc"
}

在这里插入图片描述

  • build_ohos.sh 编译脚本
#!/bin/bash

# 定义 tree 的安装路径
export TREE_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1

# 保存原始 PREFIX，编译后恢复
sys_perfix=${PREFIX}
export PREFIX=${TREE_INSTALL_HNP_PATH}
echo "安装路径：${PREFIX}"

# 清理旧编译产物，重新编译
make clean
make VERBOSE=1 prefix=${TREE_INSTALL_HNP_PATH}
make install prefix=${TREE_INSTALL_HNP_PATH}

# 复制配置文件到安装目录
cp hnp.json ${TREE_INSTALL_HNP_PATH}/

# 切换到上级目录，用 hnpcli 工具打包
pushd ${TREE_INSTALL_HNP_PATH}/../
    ${HNP_TOOL} pack -i ${TREE_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
    tar -zvcf ${ARCHIVE_PATH}/ohos_tree_2.2.1.tar.gz tree_2.2.1/
popd

# 恢复原始 PREFIX
export PREFIX=${sys_perfix}

在这里插入图片描述

8、赋予脚本执行权限，这样就是完整的基于windows的wsl适配鸿蒙pc的linux命令行环境配置流程

chmod +x build_ohos.sh

OpenHarmony 工具链验证与编译测试

1、环境验证，在开始编译前，需要验证鸿蒙工具链的完整性

# 1. 验证 clang 编译器
/home/weishuo/ohos-sdk/linux/native/llvm/bin/clang --version

# 2. 验证 hnpcli 打包工具
/home/weishuo/ohos-sdk/linux/toolchains/hnpcli --help

# 3. 验证 ld.lld 链接器
/home/weishuo/ohos-sdk/linux/native/llvm/bin/ld.lld --version

在这里插入图片描述

2、编译环境测试，创建测试程序验证交叉编译环境

  • hello_ohos.c
#include <stdio.h>

int main() {
#ifdef __OHOS__
    printf("✅ 鸿蒙编译环境正常！已识别 __OHOS__ 系统宏\n");
#else
    printf("❌ 未识别鸿蒙系统宏，编译环境异常\n");
#endif
    return 0;
}

在这里插入图片描述

3、使用鸿蒙工具链编译（用 OpenHarmony SDK 的 clang 交叉编译 hello_ohos.c，指定 aarch64-OHOS 目标平台、SDK sysroot 路径及 OHOS 宏，生成适配 OpenHarmony 的可执行文件）

/home/weishuo/ohos-sdk/linux/native/llvm/bin/clang -o hello_ohos hello_ohos.c --target=aarch64-linux-ohos --sysroot=/home/weishuo/ohos-sdk/linux/native/sysroot -D__OHOS__

4、验证生成文件

# 查看 hello_ohos 可执行文件的类型、架构、目标系统等详细信息
file hello_ohos

在这里插入图片描述

5、环境验证成功：输出显示为 ARM aarch64 架构的鸿蒙可执行文件，证明交叉编译环境已正确配置

  • 开始编译，回到 build 根目录，执行编译命令
# 切换到 build 构建目录
cd ~/build
# 执行构建脚本，指定 OpenHarmony SDK 的 Linux 平台路径（用于编译依赖 SDK 工具链/头文件）
./build.sh --sdk /home/weishuo/ohos-sdk/linux

基于 Cursor / VS Code 的鸿蒙适配开发实践

1、在 WSL 终端中快速在 Windows 中打开 build 文件夹

# 在 WSL 中调用 Windows 资源管理器打开当前目录（. 表示当前工作目录）
explorer.exe .

在这里插入图片描述

2、Cusor集成开发环境配置

  • 在 VS Code 中打开脚手架文件夹
  • 选择终端为 WSL: Ubuntu-24.04
  • 切换到 WSL 终端进行开发

在这里插入图片描述

在这里插入图片描述

OpenHarmony PC 适配：tree 2.2.1 交叉编译与 HNP 打包

1、修改 build.sh 需要构建的命令行组件名称（OpenHarmony 组件构建初始化脚本，需通过 --sdk 指定 SDK 路径并校验有效性，根据运行系统配置编译工具链与 HNP 相关目录，检查 Python 环境并提供安装指引，导出编译工具、编译选项及构建相关路径等环境变量，创建必要目录后，默认执行 code/cmdtree 目录下的 build_ohos.sh 构建组件，也可通过 BUILD_BY_DEPENDENCY=true 按 dependency.json 构建依赖组件）

#!/bin/bash

SDK_PATH=""
while [[ $# -gt 0 ]]; do
    case "$1" in
        --sdk)
            SDK_PATH="$2"
            shift 2
            ;;
        *)
            echo "Error: unknow param $1"
            echo "Usage: $0 --sdk <SDK path>"
            exit 1
            ;;
    esac
done

if [ -z "$SDK_PATH" ]; then
    echo "Error: SDK path must be specified with the \"--sdk\" option"
    echo "Usage: $0 --sdk <SDK path>"
    exit 1
fi

if [ ! -d "$SDK_PATH" ]; then
    echo "Error: SDK path is not exist or no permossion: [$SDK_PATH]"
    exit 2
fi

export OHOS_SDK="$SDK_PATH"
export HNP_PERFIX=

BUILD_OS=$(uname)
case $BUILD_OS in
    'OpenHarmony')
        echo "Build in: <$(uname -a)> by local tool chains."
        export COMPILER_TOOLCHAIN=${OHOS_TOOL_CHAIN_PATH}
    ;;
    'HarmonyOS')
        echo "Build in: <$(uname -a)> by local tool chains."
        export COMPILER_TOOLCHAIN=${HMOS_TOOL_CHAIN_PATH}
        export HNP_PERFIX=${PWD}/hnp
    ;;
    *)
        echo "Build in: <$(uname -a)> by cross tool chains."
        export COMPILER_TOOLCHAIN=${OHOS_SDK}/native/llvm/bin/
    ;;
esac

if [ -z "${HNP_PERFIX}" ]; then
    export HNP_PERFIX="${PWD}/hnp"
fi

if [ -n "${HNP_PERFIX}" ]; then
    mkdir -p "${HNP_PERFIX}"
fi

PYTHON=$(python --version)
echo "python  : $PYTHON"
if [ -z "$PYTHON" ]; then
    echo "You need install python in your system"
    case "$BUILD_OS" in
        OpenHarmony|HarmonyOS)
            echo "${BUILD_OS} install by url://www.xxx.xxx.com"
            ;;
        Linux* )
            if command -v apt-get &> /dev/null; then
                echo "1. sudo apt update"
                echo "2. sudo apt install python3 python3-pip"
            elif command -v yum &> /dev/null; then
                echo "1. sudo yum install python3 python3-pip"
            else
                echo "Please install python3 and pip using your system's package manager."
            fi
            ;;
        Darwin*)
            echo "1. Use Homebrew: brew install python"
            echo "or"
            echo "2. Download by python org: https://www.python.org/downloads/macos/"
            ;;
        CYGWIN*|MINGW32*|MSYS*|MINGW*)
            echo "1. Download by python org: https://www.python.org/downloads/windows/"
            echo "2. Check the \"Add Python to PATH\" option during installation."
            ;;
        *)
            echo "Unable to determine the appropriate Python installation method for your system."
            ;;
    esac
    exit 1
fi

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}                                && 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 CFLAGS="-fPIC -D__MUSL__=1 -D__OHOS__ -fstack-protector-strong --target=${TARGET_PLATFORM} -fuse-ld=${LD} --sysroot=${SYSROOT}"
export CXXFLAGS="${CFLAGS} "
export LD_LIBRARY_PATH=${SYSROOT}/usr/lib:${LD_LIBRARY_PATH}
export LDFLAGS="${LDFLAGS} -fuse-ld=${LD} --target=${TARGET_PLATFORM} --sysroot=${SYSROOT}"
export HOST_TYPE="--host=aarch64-linux --build=aarch64-linux"

mkdir -p ${HNP_PUBLIC_PATH}
mkdir -p ${ARCHIVE_PATH}

mkdir -p code


# 默认直接构建指定目录，除非显式要求按 dependency.json 走
BUILD_BY_DEPENDENCY="${BUILD_BY_DEPENDENCY:-false}"
# 需要构建的组件名称
SPECIFIC_DIR="${SPECIFIC_DIR:-cmdtree}"

if [[ "${BUILD_BY_DEPENDENCY}" == "true" ]]; then
    python build_dependency.py
else
    pushd "code/${SPECIFIC_DIR}"
        chmod +x build_ohos.sh
        ./build_ohos.sh
    popd
fi

在这里插入图片描述

2、code/cmdtree/hnp.json 鸿蒙原生包配置（tree 组件的 HNP 配置文件，指定配置类型为 hnp-config，组件名称为 tree、版本 2.2.1，安装配置留空）

{
"type":"hnp-config",
"name":"tree",
"version":"2.2.1",
"install":{}
}

在这里插入图片描述

3、code/cmdtree/build_ohos.sh 构建与打包脚本（脚本定义 tree 组件相关参数，清理旧构建、编译安装组件，拷贝文档与 hnp.json，通过 HNP 工具打包并生成对应版本的 tar.gz 压缩包）

#!/bin/bash
set -euo pipefail

component_name="tree"
component_version="2.2.1"
install_prefix="/usr"

export TREE_INSTALL_HNP_PATH="${HNP_PUBLIC_PATH}/${component_name}.org/${component_name}_${component_version}"
echo "Install root: ${TREE_INSTALL_HNP_PATH}"

mkdir -p "${TREE_INSTALL_HNP_PATH}"

make clean
make VERBOSE=1 PREFIX="${install_prefix}" MANDIR="${install_prefix}/share/man"
make install PREFIX="${install_prefix}" DESTDIR="${TREE_INSTALL_HNP_PATH}" MANDIR="${install_prefix}/share/man"

doc_dir="${TREE_INSTALL_HNP_PATH}/usr/share/doc/${component_name}"
mkdir -p "${doc_dir}"
install -m 644 README README.md CHANGES LICENSE INSTALL TODO "${doc_dir}/"

install -m 644 hnp.json "${TREE_INSTALL_HNP_PATH}/"

pushd "${TREE_INSTALL_HNP_PATH}/../"
    ${HNP_TOOL} pack -i "${TREE_INSTALL_HNP_PATH}" -o "${ARCHIVE_PATH}/"
    tar -zvcf "${ARCHIVE_PATH}/ohos_${component_name}_${component_version}.tar.gz" "${component_name}_${component_version}/"
popd

在这里插入图片描述

4、配置 dependency.json 依赖配置文件（配置文件定义项目依赖组件，明确指定需引入 tree 工具，其源码来源）

{
    "dependency": [
        {
            "name" : "tree",
            "branch" : "2.2.1_ohos",
            "url" : "git@gitcode.com:OpenHarmonyPCDeveloper/cmdtree.git"
        }
    ]
}

在这里插入图片描述

5、成功在鸿蒙 OpenHarmony 环境中交叉编译并打包了 tree 工具 版本 2.2.1 ，整个流程从编译、安装到 HNP 打包完全顺畅，没有报错 ret=0 表示执行成功（成功执行两次构建命令，完成 zoxide 和 tree 的 HNP 打包，重新编译 tree 并输出对应产物，忽略无关编译警告，确保产物包含必要目录与文件）

cd ~/build
./build.sh --sdk ~/ohos-sdk/linux

在这里插入图片描述

6、检查构建产物

ls -lh output/

在这里插入图片描述

总结

本次实践不仅为 tree 工具融入 OpenHarmony PC 生态提供了完整方案，更提炼出一套通用的 Linux 开源软件鸿蒙适配方法论，从环境迁移、依赖配置到打包发布的标准化流程，可为后续更多命令行工具的生态适配提供参考，助力 OpenHarmony PC 端工具链的丰富与完善，进一步降低开源软件融入鸿蒙生态的技术门槛，推动生态功能多元化拓展。

Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

深耕鸿蒙技术栈：从认证备考到实战开发的进阶之路

从HCIA到HCIP，再到鸿蒙高级认证的进阶，从基础组件开发到分布式应用实践，这段学习经历让我对鸿蒙技术体系有了更深刻的理解，也为未来的实习与职业发展筑牢了根基。而鸿蒙高级认证的备考，则更注重综合技术的融合与创新应用。对于即将进入实习阶段的我来说，深耕鸿蒙技术栈，不仅是顺应技术发展的趋势，更是为了在万物互联的时代浪潮中，抓住属于开发者的机遇。鸿蒙认证体系是检验开发者技术水平的重要标尺，从HCIA的

avatar HarmonyOS开发者社区

鸿蒙开发之：应用上架全流程指南

前期准备：账号认证、材料准备、签名证书打包构建：优化配置、版本管理、多设备适配市场提交：元数据优化、ASO策略、合规检查审核应对：问题定位、快速响应、重新提交发布后管理：版本更新、用户反馈、数据统计长期运营：持续优化、技术维护、生态建设终极挑战：从0到1发布一个鸿蒙应用要求：基于本系列知识，开发一个有价值的应用完成所有测试和质量检查提交到华为应用市场并通过审核收集用户反馈并持续优化将你的成功经验分

avatar HarmonyOS开发者社区

智能家居应用HarmonyOS开发实践：海信爱家基于ArkTS的技术栈转型探索

海信爱家App通过集成Cast Engine，实现手机与大屏类设备间的快速连接，用户可以一键调取手机相册，实现图片内容的高清、流畅投射，感受自然连贯的跨屏体验。此外，HarmonyOS的分布式架构通过统一的API抽象层，将扫码、投屏、账户授权等系统级能力以标准化服务的形式开放给App层，为App在跨设备协同场景下的体验优化提供支持。通过系统化的响应式布局实施方案，海信爱家App成功解决了折叠屏设备

avatar HarmonyOS开发者社区