欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

本文整理既有 Rust 命令行项目在鸿蒙 PC 上的原生交付经验，重点介绍目标工具链、HNP 打包、签名前注入和终端验收。文中的环境版本来自本次工程记录；不同 SDK 与 Hvigor 版本需要根据实际环境调整。

一、为什么要把 Rust 命令行程序带到鸿蒙 PC

鸿蒙 PC 的开发环境除了图形化应用，也需要能够在终端中直接运行的原生工具。对于已经拥有 Rust 核心代码的项目，适配工作的关键在于打通从源码构建到设备执行的完整流程。

这条流程需要回答几个具体问题：Rust 代码及其 C/C++ 依赖能否使用一致的 OpenHarmony 工具链完成编译？生成的 ARM64 ELF 能否在目标设备上加载？原生程序如何随应用安装，并通过 HNP 向系统终端提供命令入口？

本次工程记录使用 HarmonyOS PC 2in1 真机、HarmonyOS SDK 6.0.2（API 22）和 Hvigor 6.22.3。Rust 目标三元组为 aarch64-unknown-linux-ohos，HNP 按 arm64-v8a 目录组织。两者分别描述编译目标与包内架构目录，配置时需要保持对应。

最终采用“ArkUI 使用说明页 + 公共 HNP”的交付方式：应用页面提供安装后的说明与操作指引，原生命令由系统终端执行。本文围绕这条交付链路展开。

二、交付边界：应用承载安装，终端执行命令

对于以命令行为主要入口的项目，桌面页面可以先承担清晰、有限的职责：展示组件说明、版本信息和终端使用方法。

当前实现没有把命令进程与页面前后台生命周期绑定，也没有在页面中展示未经进程状态验证的运行结果。用户安装应用后，在 HarmonyOS PC 自带的 HiShell 中检查和执行 HNP 注册的命令。

层次	解决的问题	本次实现方式
核心代码层	保留已有命令行入口和参数解析	Rust Cargo 工作区
交叉编译层	生成目标设备可执行的 ARM64 程序	OpenHarmony Rust 目标与 Clang、sysroot
HNP 交付层	随应用安装原生程序并提供终端入口	公共 HNP 与命令链接
应用承载层	完成签名安装和使用引导	Stage 模型、EntryAbility 与 ArkUI 页面
验收层	确认安装、命令发现和基础执行结果	真机 HiShell

一次基础验收的顺序如下：

构建 Rust 原生程序
  → 生成 HNP
  → 将 HNP 纳入未签名 HAP
  → 完成 HAP / APP 签名
  → 真机安装
  → 在 HiShell 检查命令路径、版本和帮助信息

三、鸿蒙适配需要增加哪些工程内容

仓库继续保留 Rust Cargo 工作区，在其外围增加构建脚本和鸿蒙应用工程。下面展示本文涉及的关键部分，省略业务源码与项目专用文件名：

项目根目录/
├── Cargo.toml / Cargo.lock      # Rust 工作区与依赖锁定
├── build_hnp.sh                 # 原生编译、HNP 打包和应用构建
├── prepare_hvigor_sdk.sh        # 准备 Hvigor 所需 SDK 目录结构
├── HNP_BUILD_GUIDE.md           # 构建、签名与安装说明
└── ohos/
    ├── AppScope/                # 应用名称、版本与图标
    ├── build-profile.json5      # 产品和签名配置
    ├── hnp/arm64-v8a/           # 生成的 HNP 文件
    └── entry/
        ├── hvigorfile.ts        # 本项目的 HNP 注入逻辑
        └── src/main/
            ├── ets/entryability/
            ├── ets/pages/Index.ets
            └── module.json5    # 设备类型与 HNP 等模块声明

构建脚本按项目需要选择 Cargo feature，收集编译产物，再调用 hnpcli 生成 HNP。包内程序和公共命令链接的对应关系由实际 hnp.json 配置决定。

本项目安装后的公共命令入口位于 /data/service/hnp/bin/。用户通过入口执行程序，具体版本目录与应用安装路径由 HNP 服务管理。

命令名、HNP 文件名和 BundleName 都属于真实工程配置。编写文档时应与产物保持一致；如果使用占位示例，应明确注明，不能把另起的说明名称写成真机已经注册的命令。

四、真机验收应如何拆分

原工程记录包含应用启动、HNP 命令发现、版本查询与帮助输出。将这些步骤分开记录，可以更准确地定位问题。以下整理其验收方法及每一步能够说明的范围。

以下五张图片来自原工程的真机记录，已裁剪无关桌面区域，并对项目标识、部分命令及功能说明作实色遮挡。图片底部附有编辑说明；遮挡后的截图仅供说明对应操作环节，不作为完整、可复现的验收证据。

1. 应用能够安装并启动

首先安装已签名应用，再启动 EntryAbility，检查页面能否正常展示。

这一项用于检查签名应用安装、Ability 启动和 ArkUI 窗口渲染。应用打开后，还需要继续检查终端中的原生程序。

2. HNP 命令能够被终端找到

在 HiShell 中使用 command -v 检查真实公共命令名，并核对返回路径是否与预期一致。

这一步用于确认系统已经完成 HNP 的提取及公共命令链接注册。如果找不到命令，应检查 HAP 中的 HNP 内容、模块声明、包内链接配置以及当前终端环境。

图 2：HiShell 公共命令路径查询的局部遮挡版，命令名称已遮挡，保留原始路径前缀。

3. 原生程序能够返回版本

对支持版本参数的程序执行 --version，记录实际输出，并与构建版本核对。

版本查询成功，说明对应程序在当前设备上可以完成加载并执行到版本输出路径。这是一项成本较低的基础检查，但尚不能覆盖所有动态依赖、可选功能和业务分支。

图 3：原生程序版本查询的局部遮挡版，程序名称已遮挡，版本号保留原始输出。

4. 帮助信息能够正常输出

对支持帮助参数的程序执行 --help，核对命令入口和参数说明。

该步骤验证帮助输出路径是否可用。对于 feature 控制的功能，还应结合构建参数和功能测试逐项确认，不能仅凭帮助输出就判断完整 feature 集已经通过验证。

图 4：帮助输出的局部遮挡版，项目功能说明与参数详情已遮挡。

5. 终端返回信息的展示范围

原工程还保留了一张终端返回信息截图。本次展示已遮挡请求命令，仅保留当时的返回信息；由于缺少完整执行上下文，不能据此复现测试或判断具体功能是否通过。

图 5：原工程终端返回信息的局部遮挡版，请求命令已遮挡，不能单独作为完整功能验证依据。

建议记录设备型号、系统版本、SDK 版本、构建版本、实际执行命令及退出结果。截图应与文字中的命令和版本保持一致。

本文重点整理安装与基础执行验收方法。展示用图片已经局部遮挡，完整验收记录应在工程内部另行保存。具体业务功能需要独立设计测试用例，其结果不应由版本查询、帮助输出或遮挡后的返回信息截图代替。

五、适配过程中最关键的几个问题

难点一：Rust 目标三元组只是起点，Native 依赖也要使用 OHOS 工具链

把 Cargo 目标改成 aarch64-unknown-linux-ohos，并不意味着所有依赖都会自动使用正确的编译器。带有 Native 依赖的 crate 可能继续调用 C/C++ 编译脚本、系统头文件、链接器和归档工具。

如果构建过程误用了宿主机工具链，就可能产生架构、头文件或 libc 不匹配的问题。因此需要同时核对 CC、CXX、AR、RANLIB、目标专用的 Cargo linker，以及 --target 和 --sysroot 等设置。项目记录中还使用了 __MUSL__ 定义，其他工程应按依赖需求确认是否需要。

配置的目标是让 Rust 与 Native 依赖使用一致的目标环境。构建完成后，应先检查 ELF 的架构和依赖信息，再进行真机加载与执行验证。

难点二：HNP 必须在签名前进入 HAP

HNP 文件生成成功后，还需要确认它进入最终 HAP 的约定目录。仅在源码目录中存在 HNP，或仅配置 module.json5 中的 hnpPackages，不足以证明最终安装包已经包含它。

本项目在 Hvigor 6.22.3 环境下使用 ohos/entry/hvigorfile.ts 中的 inject-hnp 插件，在 default@SignHap 执行前将 HNP 注入未签名 HAP，再进入统一签名流程。

这里最重要的是处理顺序：先完成包内容，再签名。签名后修改归档内容会破坏包完整性校验。其他版本的构建工具若已提供适用的原生打包能力，应先核对其支持情况，再决定是否保留自定义注入步骤。

难点三：SDK 元数据布局与 Hvigor 扫描规则可能不一致

本次工程记录中，DevEco Studio 6.0.2 所带 SDK 的元数据布局与 Hvigor 6.22.x 的目录扫描规则存在差异，导致构建工具不能直接识别所需组件。

项目使用 prepare_hvigor_sdk.sh 读取 SDK 元数据，在项目 .ohos-sdk/harmonyos/ 下创建兼容目录，并通过软链接复用原始 hms 和 openharmony 组件。构建脚本再通过 DEVECO_SDK_HOME 与 OHOS_BASE_SDK_HOME 指向对应环境。

这种处理方式将兼容逻辑保留在项目内，便于重建和排查。升级 SDK 或 Hvigor 后，应重新检查目录约定，确认兼容脚本仍有必要且路径正确。

难点四：HDC Shell 与桌面 HiShell 的环境需要分别验证

开发机通过 hdc shell 进入的调试会话，与用户打开的桌面 HiShell，可能在用户身份、PATH 和文件可见性上存在差异。

因此，本项目用 HDC 完成设备连接、安装和应用启动检查，再在真机 HiShell 中验证公共命令发现与执行。记录两个环境的结果，有助于区分安装问题、入口注册问题和终端环境问题。

难点五：基础执行成功后仍需检查异常路径

程序能够返回版本，只覆盖了很短的执行路径。进入实际任务后，仍可能遇到配置文件不可读、目录不可写、资源不可用或权限不足等问题。

后续验收应关注错误信息是否准确、失败时是否返回适当的退出码、进程是否及时退出，以及日志是否足以定位问题。需要长期运行的工具，还应单独验证进程生命周期与异常恢复。

六、构建、安装与基础检查

开发机需要准备与工程匹配的 DevEco Studio、HarmonyOS/OpenHarmony SDK、Rust 工具链和 Node.js，并确认 OHOS Clang、hnpcli、Hvigor、HDC 及签名工具可用。

准备调试或发行签名材料后，在 ohos/build-profile.json5 中配置相应信息。证书、Profile、Keystore 和密码应按项目的安全管理方式保存，避免提交至公开仓库。

在本项目仓库根目录执行：

./build_hnp.sh

build_hnp.sh 是本项目提供的脚本，其他 Rust 工程需要自行接入对应构建步骤。它负责串联以下流程：

1. 检查 Rust 的 aarch64-unknown-linux-ohos 目标支持。
2. 配置 OpenHarmony Clang、sysroot 与 Native 依赖构建环境。
3. 编译所需 feature，收集 release 二进制及必要资源。
4. 调用 hnpcli 生成 HNP。
5. 准备 Hvigor 所需的 SDK 兼容目录。
6. 将 HNP 纳入未签名 HAP，完成 HAP 与 APP 签名。

本次工程中的主要产物目录如下，实际文件名以构建输出为准：

ohos/hnp/arm64-v8a/
ohos/entry/build/default/outputs/default/
ohos/build/outputs/default/

连接设备后，先检查目标列表：

hdc list targets

随后安装实际生成的已签名应用。以下为命令格式示意，尖括号内容必须替换为当前工程的真实值，不能原样执行：

hdc install -r <已签名 APP 的实际路径>
hdc shell aa start -b <实际 BundleName> -m entry -a EntryAbility

上述启动示例以模块名 entry、Ability 名 EntryAbility 为前提，工程配置不同则同步调整。连接多台设备时，还需按 HDC 支持的方式明确指定目标。

安装完成后，在 HiShell 中按以下格式检查真实命令：

command -v <hnp.json 中配置的公共命令名>
<实际公共命令名> --version
<实际公共命令名> --help

版本和帮助参数以程序实际支持为准。验收记录应保留执行时的真实名称及输出，便于与安装包和构建配置相互核对。

七、当前记录覆盖的范围与后续工作

原工程记录覆盖了以下交付与基础执行环节：

• 签名应用安装、Stage 模型 Ability 启动和 ArkUI 页面展示。
• HNP 随包提取，以及公共命令在 HiShell 中的路径查询。
• ARM64 原生程序的版本查询和帮助输出。
• Rust 交叉编译、HNP 生成、签名前注入和应用签名流程。

这些记录支持对原生程序交付链路进行分析。判断软件是否能够长期稳定使用，还需要补充：

• 按实际 feature 与参数设计的功能测试。
• 配置异常、权限不足和资源不可用等错误路径测试。
• 不同设备和系统版本的兼容性验证。
• 休眠唤醒、长时间运行及异常退出后的恢复验证。
• 如果增加图形化管理，验证页面状态与真实进程状态是否一致。
• 正式发行所需的证书、签名与发布配置。

八、总结

Rust 命令行程序适配鸿蒙 PC，需要同时处理编译目标、Native 依赖、包结构、签名顺序和用户终端环境。任何一个环节配置正确，都不能单独代表整个交付过程已经完成。

本次实践将这些环节串成了一条可检查的流程：使用 OpenHarmony 工具链生成 ARM64 程序，通过 HNP 随应用交付，在签名前完成包内容组装，最后进入真机 HiShell 验证命令发现与基础执行。

对于其他 Rust 原生工具，可以复用这套构建与验收思路，再按各自功能补齐测试。将环境版本、构建参数、实际命令和验收结果记录清楚，才能让一次适配经验变成可以复现的工程方法。