企业官网建设流程全解析

十分钟判断三方库的 HarmonyOS 适配路线：直接用、改 ArkTS、加兼容层还是走 Native

专栏：HarmonyOS 三方库适配实战（5/30）
阶段目标：在投入代码前，给候选库一条有证据的适配路线。

摘要

三方库适配最昂贵的错误，往往发生在写第一行补丁之前：把依赖 Node.js 的大型库当成纯 TypeScript，把带复杂系统调用的 C++ 项目当成“改一下 CMake”，或者没有检查许可证就开始移植。本文提供一套十分钟侦察流程，检查语言、运行时、构建、平台 API、ABI、许可证、测试和维护状态，并将结果归入五条路线：直接使用、ArkTS 改造、兼容层、Native 移植或暂缓采用。

输入、输出与停止条件

开始前至少准备候选库的官方仓库或发布页、准确 tag/commit、包仓坐标（如有）和许可证文件。十分钟结束时必须交付一张八维评估表、一条推荐路线以及下一项可验证动作；不能只写“看起来可用”。

出现以下任一情况，应停止进入代码适配：上游身份或版本无法锁定；许可证缺失或目标用途不明确；仅有其他平台闭源二进制且没有 HarmonyOS 产物；核心运行时依赖无法替代；无法获得最小测试输入。停止不是失败，而是避免把未知成本带进工程。

十分钟不是给兼容性下结论

这十分钟只做立项筛选，目标是决定下一步花时间在哪里。它不能替代源码审计、SDK 编译、模拟器或真机测试。

筛选结束后应该得到这种结论：

候选库是 TypeScript 实现，核心路径不依赖 DOM/Node.js，存在动态对象写法和两个间接依赖。建议进入 ArkTS 改造路线，先验证入口与类型，再迁移上游测试。许可证文件存在，但发布时仍需复核义务。

而不是：

看起来是 TS，应该能用。

图 1：十分钟侦察时间线（示意图）。它只决定下一步验证路线，不能替代编译和设备测试。

第 1 分钟：锁定身份，防止评错版本

记录：

library:name:"<package name>"upstream_url:"<official repository>"release_or_commit:"<exact tag or commit>"package_registry:"<registry and package coordinate>"license_file:"<path or missing>"assessed_at:"<timestamp with timezone>"

仓库首页、包仓坐标和你下载的源码必须指向同一个版本。若无法锁定上游来源，先停止技术适配；否则后续补丁无法审阅，也无法判断安全更新。建议同时记录归档文件哈希或提交 ID，避免同名版本被误换。

第 2—3 分钟：看语言和产物

快速统计：

• 源码主要是.ets、.ts、.js、C、C++ 还是混合？
• 发布物是源码、HAR、HSP、.so还是多种组合？
• 是否存在CMakeLists.txt、平台构建脚本或预编译二进制？
• 是否只有类型声明，没有对应运行实现？

初步路线：

第 4—5 分钟：扫描运行时耦合

在已获得授权、可读取的源码目录中，可以使用rg做第一轮线索扫描：

rg-n"eval\(|new Function|process\.|require\(|node:|fs\.|path\.|window\.|document\.|WebSocket|Worker".

这条命令只负责找候选位置，不能自动判定“不兼容”。例如字符串、测试夹具和注释也可能命中。每个结果都要回到真实调用链判断。

需要重点问：

• 是否要求 Node.js 内置模块或浏览器 DOM？
• 是否使用eval()、字符串构造函数或运行期动态改对象结构？
• 是否依赖特定模块加载器、文件布局或进程环境变量？
• 是否在主线程执行不可控的同步 I/O 或大计算？

ArkTS 语法适配背景说明了更严格的静态类型检查，并列出eval()、字符串创建函数等运行环境限制。命中这些模式不代表必须重写全库，但说明“直接复制源码”风险较高；必须回到真实调用链确认命中代码是否进入发布产物。

第 6 分钟：看依赖树，而不是只看直接依赖

若候选包已安装到当前工程，记录客户端版本并查看它的父依赖和深层依赖：

ohpm --version ohpm list <候选包名> ohpm list -d 10

尖括号表示需要替换的输入。根据官方ohpm list文档，指定包名时会列出该包的父依赖；没有安装时不能把空结果解释为“无依赖”，应改查上游包清单和构建文件。

重点关注：

• 间接依赖数量是否远高于库自身规模；
• 是否出现多个版本；
• 是否包含 Native 产物；
• 是否依赖另一个尚未适配的平台库；
• 版本范围是否会让结果随时间变化。

如果候选库还没有 ohpm 包，就从其原始包清单和构建文件建立等价依赖图，不要把“尚未安装”记录成“无依赖”。

第 7 分钟：看平台 API 和构建系统

TypeScript 库重点看：

• 文件、网络、数据库、加密、线程、定时器和 UI 能力来自哪里；
• 是否能把平台能力收敛为接口并由消费方注入；
• 核心算法能否独立测试。

C/C++ 库重点看：

• CMake 是否清晰，还是绑定其他平台工程；
• 是否使用特定系统调用、汇编、线程实现或动态加载；
• 是否假定特定 ABI、编译器或标准库；
• 上游测试能否在交叉构建后复用。

如果只有一两个平台调用，兼容层往往比 fork 全库更容易维护；如果平台判断散布在几十个文件中，成本会迅速上升。

第 8 分钟：看许可证与交付义务

至少记录：

• 仓库是否包含明确 LICENSE 文件；
• 源码版本与发布包中的许可证是否一致；
• 是否包含第三方子依赖及各自许可证；
• 修改、再分发、署名、源码提供或 NOTICE 是否有要求；
• 项目是否允许你的目标使用方式。

技术文章可以说明“发现了什么文件、计划如何保留声明”，但不要在没有法律审查的情况下给出绝对合规保证。许可证不清楚时，路线应标为“暂缓采用”，而不是“先发包再说”。这里的检查是工程风险筛选，不构成法律意见。

第 9 分钟：看测试和维护信号

有价值的信号包括：

• 上游是否有可运行测试和固定输入；
• 最近发布与提交是否正常；
• Issue 是否揭示已知平台假设；
• API 是否稳定，是否存在迁移说明；
• 维护者是否接受其他平台补丁。

活跃度不是质量证明，星标数量也不是兼容证据。真正有用的是：你能否锁定版本、运行测试、解释变更并长期合并上游。

第 10 分钟：填表并选择路线

使用下面的评估表：

| 维度 | 发现 | 风险 | 证据 | 下一步 | | --- | --- | --- | --- | --- | | 语言 | | 低/中/高 | 文件/统计 | | | 运行时 | | 低/中/高 | 命中位置 | | | 依赖树 | | 低/中/高 | 列表/清单 | | | 平台 API | | 低/中/高 | 调用点 | | | 构建/ABI | | 低/中/高 | 构建文件 | | | 许可证 | | 低/中/高/阻塞 | LICENSE | | | 测试 | | 低/中/高 | 命令/用例 | | | 维护 | | 低/中/高 | tag/commit | |

然后选择：

先处理阻塞项，再比较技术成本：许可证或来源阻塞直接进入路线 E；存在 HarmonyOS 成熟产物时先走 A 并完成五级验证；平台无关 TS 核心优先 B；少量平台调用可收敛为接口时优先 C；可交叉构建的 C/C++ 源码再评估 D。若证据同时指向两条路线，下一步应设计一个最小实验，而不是用主观分数强行决定。

图 2：路线选择图。右下角是本地教学库的实际评估：路线 A、证据到 L3、设备未测。

路线 A：直接使用

适用于已有合格 HarmonyOS 包、入口清楚、依赖明确的库。仍要完成第 1 篇的五级验证，不因“已有 HAR”跳过设备测试。

路线 B：ArkTS 改造

适用于规模可控、核心逻辑平台无关，但存在 TypeScript/JavaScript 语法或类型差异的库。优先迁移测试，再按错误类别改造。

路线 C：兼容层

适用于核心逻辑可复用，只在少数位置依赖文件、网络、时钟等平台能力的库。用窄接口注入 HarmonyOS 实现，尽量不污染上游核心。

路线 D：Native 移植

适用于成熟 C/C++ 实现，且保留原生算法明显比重写更合理的库。需要额外评估 CMake、系统调用、ABI、Node-API、线程和生命周期。

路线 E：暂缓采用

适用于许可证不清、只有其他平台闭源二进制、核心运行时不可替代、维护停止或适配成本超过业务价值的库。放弃不合适的候选也是有效工程决策。

三个示例判断

小型文本算法库

纯 TypeScript、没有平台 API、有测试，但大量依赖动态对象结构。结论：优先走 ArkTS 改造，先锁定测试向量，再重构类型。

网络 SDK

业务协议逻辑清晰，但底层绑定 Node.js 网络和文件系统。结论：评估兼容层，把传输、存储和时钟抽象出来；如果耦合遍布全库，重新比较改造与替代方案。

只有其他平台二进制的闭源库

没有 HarmonyOS 产物、没有源码、厂商也没有适配计划。结论：暂缓采用或推动厂商支持，不要把二进制改名后尝试加载。

这些是决策示例，不代表任何具体真实库的审计结果。

本篇产物

• 一份十分钟候选库评估流程。
• 一个八维风险表。
• 五条适配路线及停止条件。

完成本篇后，第一阶段结束。进入第 6 篇前，应选择一个规模小、测试明确、许可证清晰、无 DOM/Node.js 强依赖的 TypeScript 工具库，并锁定准确上游版本。

官方来源

• 从 TypeScript 到 ArkTS 的适配指导：用于确定 TypeScript 源码需要单独做 ArkTS 规则审查。访问日期：2026-10-15。
• ArkTS 语法适配背景：用于静态类型与受限动态行为背景。访问日期：2026-10-15。
• ohpm list：用于读取父依赖和深层依赖树。访问日期：2026-10-15。
• oh-package.json5：用于包入口、依赖类型、本地源码/HAR 和覆盖方式。访问日期：2026-10-15。
• 开发发布与管理共享包：用于当前 HAR/HSP 开发、发布与管理入口。访问日期：2026-10-15。

验证声明

本文已于 2026-10-15 核对华为官方 ArkTS 迁移、ohpm 依赖树、包配置和共享包文档，并用本地教学库@demo/text-tool@1.0.0走完十分钟评估：源码为纯 ArkTS、运行时耦合扫描无命中、无子依赖、无 Native ABI，许可证标记为 Apache-2.0，HAR 与消费方均通过 API 22 目标 SDK 编译，因此该教学夹具可进入“直接使用后验证”路线。它不是对真实外部三方库的审计，许可证文件也不构成法律意见；模拟器和真机运行仍未执行。