当前位置：首页>鸿蒙APP>axios 是怎么跑在鸿蒙上的?——从 npm 到 OHPM 的移植全流程

axios 是怎么跑在鸿蒙上的?——从 npm 到 OHPM 的移植全流程

2026-08-20 13:07:29

你有一个在 npm 上用了很久的库，想在鸿蒙上继续用。不是重写，是适配。这件事有一个专门的名字——鸿蒙化。

OpenHarmony 官方把三方库按语言分成了两种（来源）：一种是 JS/TS 写的，以 HAR/HSP 格式引入，直接在应用开发中使用；另一种是 C/C++ 写的，通过 N-API 暴露 JS 接口，或者直接编译进系统镜像。

开发者不是在鸿蒙上凭空造库。他们是从 npm 生态中选一个成熟的库，然后把它移植到 OHPM。axios、dayjs、lodash、crypto-js——这些 npm 上每天被下载几百万次的库，在 OHPM 上都有对应的 @ohos/ 版本。

第一步：选一个 npm 库

OpenHarmony 官方论坛的移植指南建议：首选在成熟的JS/TS开源库上做移植。去 npm 或 GitHub 上搜，找 Star/Fork 数量高、开源协议友好的库。

如果在 npm 上实在没有合适的 JS/TS 库，才考虑移植 C/C++ 三方库——通过 N-API 或 @ohos/aki 把原生接口暴露给 ArkTS 调用。

这就引出了移植的难度梯度：

库的类型	例子	移植难度	原因
纯 JS/TS 库	lodash、dayjs、crypto-js	低	不依赖 Node.js/浏览器 API，核心逻辑直接可用
依赖 Node.js API 的 JS 库	fs-extra、node-fetch	中	需要替换 `fs`、`http` 等 Node.js 内置模块
依赖浏览器 API 的 JS 库	某些 DOM 操作库	中	需要替换 `document`、`window` 等浏览器 API
带 C/C++ addon 的 npm 包	node-sass、bcrypt、sharp	高	需要交叉编译原生代码 + N-API 绑定
带 Rust/Go addon 的 npm 包	esbuild (Go)、napi-rs 系列 (Rust)	高	需要对应的 OpenHarmony 交叉编译工具链

纯 JS/TS 的库最容易——换一套 API 就能跑。带 native addon 的库需要同时处理编译工具链和 N-API 绑定。

第二步：扫描依赖

在动手改代码之前，先用工具扫描一遍——这个库依赖 Node.js 或浏览器内置模块吗？

OpenHarmony 社区提供了一个叫js-e2e的工具，基于 ESLint 封装。它能分析出 JS 库代码中对 Node.js 和浏览器内置模块、对象的依赖。

js-e2e scan ./node_modules/target-lib/

扫描结果分三种：

不依赖 Node.js/Web 内置模块：最理想。核心代码可以直接在 ArkTS 运行时上跑。

少量依赖：需要 Fork 源库，逐个替换。比如 fs.readFileSync → 鸿蒙的文件 API。

大量依赖：移植成本高。建议换一个更合适的库。

一个容易被忽略的点：要连依赖的依赖一起扫。npm install 下载后，node_modules 里的直接依赖和间接依赖都得扫。因为发布到 OHPM 中心仓时，依赖的组件都需要在中心仓存在。

第三步：开始移植

根据库的类型，移植路径分两种。

纯 JS/TS 库：替换 API

以axios为例——@ohos/axios 是 OHPM 中心仓上最常用的网络请求库之一。它的移植方式很有代表性：

Fork axios 源码

实现ohadapter——把 axios 的底层网络请求从 Node.js 的 http 模块替换成 OpenHarmony 的 @ohos.net.http

上面所有 API 保持不变——axios({ url, method })、拦截器、并发请求——开发者用法跟 npm 版完全一样

另一个例子是dayjs——纯 JS 日期处理库。它完全不依赖 Node.js 或浏览器 API，核心代码一行不改就能在 ArkTS 上跑。只需要把 import dayjs from 'dayjs' 换成 import dayjs from '@ohos/dayjs'。

带 Native Addon 的库：N-API 绑定 + 交叉编译

很多 npm 上流行的库，底层其实是 C/C++ 写的。比如：

node-sass：C++ 写的 Sass 编译器

bcrypt：C 写的密码哈希

sharp：C 写的图像处理（基于 libvips）

这些库在 npm 上通过 node-gyp 编译成 .node 文件，然后从 JS 层调用。移植到 OpenHarmony 的路径是：

C/C++ 源码 → OpenHarmony 交叉编译 → N-API 绑定 → ArkTS import

具体步骤：

交叉编译：用 OpenHarmony SDK 的工具链把 C/C++ 代码编译成 .so。需要写 gn 脚本（OpenHarmony 的构建文件），指定源文件、编译选项、依赖关系。

N-API 封装：写一个 N-API 封装层，把 C/C++ 函数暴露给 ArkTS。N-API 是 Node.js 标准的 C API，OpenHarmony 的方舟引擎实现了这套接口。如果嫌手写 N-API 繁琐，可以用aki——社区维护的简化方案，一行代码完成 JS ↔ C++ 互调。

测试验证：在 OpenHarmony 真机或模拟器上跑通单元测试。

对于Rust写的 npm 包（如 napi-rs 生态），社区已经有了 ohos-rs 项目——一套 Rust 的 OpenHarmony 绑定工具，支持通过 N-API 暴露 Rust 函数给 ArkTS。napi-ohos 是 crates.io 上的对应 crate。

对于Go写的 npm 包（如 esbuild），目前还没有成熟的 OpenHarmony 绑定方案，需要手动编译成 C 共享库再通过 N-API 调用。

第四步：跑测试

移植完不等于能用。需要验证。

OpenHarmony 论坛的官方指南推荐用XTS 用例验证——把库的源码和测试代码拷贝到 DevEco Studio 里，连接真机跑单元测试。

一个实际的操作流程：

把源码放到 src/main/ets/

把测试代码放到 src/ohosTest/ets/

在 Ability.test.ets 中导入测试用例

连接 OpenHarmony 设备，跑 ohosTest

如果测试不通过，根据报错排查：是不是用了 Node.js 特有 API？是不是断言接口不兼容？

OpenHarmony 的断言接口跟 Jest/Mocha 不完全一样，比如 assertEqual 而非 expect().toBe()。这部分需要手动适配。

第五步：发布到 OHPM

测试通过后，下一步是发布到 OHPM 中心仓。OHPM 的发布流程跟 npm publish 类似：

完善 oh-package.json5：这是 OHPM 的包描述文件，相当于 npm 的 package.json。包含 name、version、description、license、dependencies 等字段。

本地验证：ohpm publish --dry-run

正式发布：ohpm publish

如果要贡献到 TPC 汇集组织，还需要额外满足 TPC 的审核标准——代码许可证规范、版本命名规则、漏洞治理流程。但普通开发者可以直接把自己的库发布到 OHPM，不需要经过 TPC 审核。

目前哪些库已经移植了？

OHPM 中心仓上已经有不少常用库：

npm 原库	OHPM 对应	类型
axios	@ohos/axios	JS（需要 ohadapter）
dayjs	@ohos/dayjs	纯 JS（零改动）
crypto-js	@ohos/crypto-js	纯 JS
protobufjs	@ohos/protobufjs	JS/TS
lodash	@ohos/lodash	纯 JS
lottie	@ohos/lottie	JS/TS（动画渲染）
zlib	@ohos/zlib	C（N-API 绑定）
openssl	@ohos/openssl	C（系统级）