专栏：HarmonyOS 三方库适配实战（8/30）
本篇交付：一张错误分类表、一套修复顺序，以及可回读的 HAR/HAP 构建证据。
摘要
TypeScript 源码第一次进入 ArkTS 编译时，几十条错误常常来自少数根因：入口没有被解析、平台 API 不存在、类型不明确、对象形状动态变化、函数与模块语法不兼容。逐行修复会让同类错误反复出现。本文先保存首次编译现场，再按六类归档，优先处理会产生连锁错误的根因。文末用 API 22 教学工程演示 HAR 与消费方 HAP 的真实构建边界。
开始前先冻结现场
第一次编译的目标是收集证据，不是立刻得到绿色结果。保存：
- 候选源码 revision；
- 工程 product、module、target、build mode；
- SDK、ohpm、Hvigor 版本；
- 完整命令、退出码和原始日志；
- 第一个错误，以及各错误码出现次数。
不要在记录前清缓存、升级 SDK 或一次改几十个文件，否则无法判断错误消失是由哪项变化造成的。
从当前工程发现构建入口
命令必须来自项目自身配置。本文教学工程的 HAR 构建入口如下，尖括号和路径没有写死到文章中：
node <DevEco-Hvigor入口>--mode module `-p product=default `-p module=library_adapter@default `-p buildMode=debug ` assembleHar--no-daemon--warnHAR 生成后，再安装消费方依赖并构建 HAP：
node <ohpm入口> install--all node <DevEco-Hvigor入口>--mode module `-p product=default `-p module=entry@default `-p buildMode=debug ` assembleHap--no-daemon--warn在自己的工程中应从 DevEco Studio 或项目脚本读取真实任务，不要照抄模块名。
六类错误，比文件顺序更有用
| 类别 | 典型信号 | 先检查什么 | 代表性修复 |
|---|---|---|---|
| 入口与模块 | 找不到模块/导出 | main、路径、大小写、导出名 | 统一公共入口与标准 import/export |
| 平台 API | 找不到process/DOM/Node 模块 | 是否位于核心路径 | 删除、抽象、替换或停止 |
| 类型不明确 | any/unknown/推断失败 | 数据真实形状 | 明确参数、返回值、类或接口 |
| 动态对象 | 运行时增删属性、索引访问 | 属性集合是否固定 | 改为显式模型或受控容器 |
| 函数类型 | 回调签名、this、泛型推断异常 | 输入/返回/异常约定 | 定义命名函数类型或窄接口 |
| 语法与标准库 | require、export =、受限 API | 官方规则与替代写法 | 使用标准导入导出和支持的 API |
图 1：六类错误归档（示意图）。一轮只处理一个错误族，再重跑同一构建任务。
官方从 TypeScript 到 ArkTS 的适配规则明确列出require、export =、不明确类型、运行时改变对象布局等限制。诊断文字和错误码可能随工具链变化，文章或工单应保存本机原文，不要只写一个网上搜来的编号。
修复顺序：先消灭会制造连锁错误的根因
推荐顺序：
- 入口与依赖解析：编译器读错文件时，后面的类型错误没有意义；
- 平台 API：核心路径依赖不存在的运行时，先决定删除、抽象、替换还是停止；
- 公共数据模型：参数和返回值一旦稳定，会消掉大量下游推断错误；
- 动态对象与函数类型：按一种模式批量处理同类问题；
- 局部语法与风格：最后修不会扩散的单点错误。
每轮只处理一个错误族，然后重跑同一命令，记录“该族数量是否下降、是否出现新根因”。
示例：不要把any机械换成Object
原始 TypeScript 可能写成：
functionnormalize(input:any,options:any):any{if(options.trim){input=input.trim()}returninput}机械改成Object并没有说明trim属性和返回值。更可靠的目标是显式模型：
classNormalizeOptions{trim:booleanconstructor(trim:boolean){this.trim=trim}}functionnormalize(input:string,options:NormalizeOptions):string{returnoptions.trim?input.trim():input}这不是为了“让编译器闭嘴”，而是把原先隐含的运行时契约提前到编译期。第 9 篇会处理对象形状和输入边界。
区分源码错误和环境错误
教学工程的复现过程中出现过两个环境失败：
- SDK 根目录配置错误时，Hvigor 报配置错误
00303217； - DevEco JBR 不在当前进程 PATH 时，ArkTS 编译后打包阶段出现
spawn java ENOENT。
它们不能证明教学库不兼容。判断依据是失败发生在哪个阶段、错误指向源码还是工具路径，以及修正环境后同一源码能否通过同一任务。
本轮真实构建读回
2026-10-18 重新运行独立复现脚本，结果为：
| 项目 | 结果 |
|---|---|
library_adapter@default的assembleHar | 退出码 0 |
| 消费方依赖 | @demo/text-tool→ 本地text-tool.har |
entry@default的assembleHap | 退出码 0 |
| HAR SHA-256 | 35133D7A18A9075EC9F45C22E1284C2926020ABBB9B52C122F900292A483AA04 |
| HAP SHA-256 | 07E67FD2BFAB93E3563D3AD9DF3F65776B577F55A51572ECBFD0616C50413FEC |
| 签名 | 未配置，产物为 unsigned |
| 设备运行 | 未执行 |
退出码 0 证明当前公开 ArkTS 代码被 API 22 工具链接受，并完成 HAR/HAP 打包；它不证明页面、异常分支或设备行为已经运行。
图 2：修复顺序与构建读回（本地复现实验记录）。HAR/HAP 构建退出码为 0，签名与设备运行仍未完成。
常见失败：只保留最后一张绿色截图
绿色截图无法回答首次错误是什么、改了什么、任务和模式是什么。至少保留首次失败日志、最终命令、退出码、产物路径或哈希，以及中间修复记录。真实日志截图需遮盖用户名、绝对路径、签名信息和令牌。
本篇产物与下一篇门槛
本篇产物是六类错误清单与按根因修复的迭代记录。进入第 9 篇前，应选出“类型不明确/动态对象”族中的一个核心模型，并为它准备正常、边界和错误输入。
官方来源
- 从 TypeScript 到 ArkTS 的适配规则：用于六类错误中的静态类型、对象布局、模块语法和受限标准库。访问日期：2026-10-18。
- ArkTS 迁移背景：用于说明 ArkTS 强化静态检查，不能把普通 TypeScript 结果直接外推。访问日期：2026-10-18。
- 构建 HAR：用于核对 HAR 构建任务与产物语义。访问日期：2026-10-18。
验证声明
本文核心公开代码已在独立教学工程中使用 HarmonyOS 6.0.2 Release（API 22）、ohpm 6.0.1、Hvigor 6.22.3 完成 HAR 与消费方 HAP 构建，两个任务退出码均为 0，产物哈希已记录。代表性“不兼容代码”用于解释分类，没有冒充真实编译日志；当前未配置签名，也未连接模拟器或真机，因此验证层级止于目标 SDK 编译（L3）。
