企业官网建设流程全解析

专栏：HarmonyOS 三方库适配实战（18/30）
核心问题：一份 C/C++ 源码从上游仓库到 ArkTS 调用，中间到底经过哪些层？

摘要

Native 适配不是“把 C++ 放进工程”这么简单。上游源码先由 HarmonyOS NDK/CMake 为目标 ABI 构建，再生成.so，通过 Node-API 注册模块和做参数转换，最后由.d.ts约束 ArkTS 调用。本文建立完整链路，并在教学工程加入最小text_core、libtextnative.so、类型声明和 ArkTS 调用探针。arm64-v8a 与 x86_64 均已完成目标 SDK 构建和 HAP 打包；设备加载未执行。

六层链路

图 1：上游源码、平台适配、CMake、ABI、Node-API、类型声明与 ArkTS 消费缺一不可。

upstream C/C++ → platform abstraction → CMake target → libtextnative.so per ABI → Node-API registration/conversion → index.d.ts → ArkTS import and call

每一层都有独立失败信号。CMake 成功不等于.so已进 HAP；.so进包不等于设备能加载；模块加载成功也不等于参数和生命周期正确。

教学夹具为什么仍然选“小”

Native 第一只练手库仍应满足：

• 纯算法或数据转换；
• CMake 结构简单；
• 无复杂线程、网络和文件依赖；
• 输入输出容易断言；
• 许可证清楚；
• 公开 C/C++ API 面很窄。

教学夹具只包含 ASCII 文本归一化、字节 XOR 和计数器对象。它不是外部开源库，也不代表真实库适配已经完成；用途是让构建与桥接证据可复现。

核心层不包含 Node-API

namespacetext_core{std::stringNormalizeAscii(conststd::string&input,boollowercase);voidXorByte