不会鸿蒙的人，三个月把 Android 项目搬上了鸿蒙【鸿蒙心迹】

6 月 18 日，我接到一个很直接的问题：“鸿蒙版什么时候能上？”

摆在面前的是一个已经运行多年的 Android 项目。业务不算轻：经络查询、按时取穴、学习资料、PDF 和 EPUB 阅读、微信与支付宝登录支付，后面还有 Unity 三维经络。我的鸿蒙开发经验则接近于零。

到 9 月 20 日，HarmonyOS 工程已经有 18 个注册页面。按 entry 和 tuanjieLib 两个模块统计，共有 74 个 ETS 文件、17,969 行代码，Git 提交 85 次。数字不算惊人，但它们背后有一个很具体的问题：一个熟悉 Android 的人，怎样把旧项目迁到一套并不熟悉的平台上？

这篇不写“鸿蒙开发前景”，只复盘这三个月实际做过的事。

第一步不是写代码，是把旧项目看清楚

Android 工程里有 4 个模块、约 174 个 Java/Kotlin 文件和 49 个 XML 布局。Activity、Fragment、DataBinding 构成了页面骨架，外围还接着定位、WebView、PDF、视频、微信、支付宝和 Unity。

如果按文件数量安排迁移，最容易得到一张很忙、却无法验收的清单。我们最后按能力拆成三层：

层级	先做什么	判断标准
基础层	启动、路由、网络、登录、本地存储	应用能稳定进入主界面
业务层	首页、经络、学习、会员、阅读	主要流程能和 Android 结果对照
系统与三方层	定位、微信、支付宝、Unity	必须结合签名和真机验证

这个拆法带来的第一个好处，是不用把 Android 页面逐个翻译成 ArkTS。后端接口和业务规则可以复用，UI、系统能力和第三方 SDK 则按 HarmonyOS 的方式重新实现。

逐文件翻译看似省事，实际会把 Android 的生命周期、组件习惯和依赖方式一起搬过来。短期能看到页面，后面每接一个系统能力都要返工。

最早撞上的不是业务，而是 ArkTS

ArkTS 看起来像 TypeScript，但不能沿用普通前端项目里的全部写法。

我们在网络层第一次集中遇到这些问题：匿名对象字面量没有明确类型、throw 抛出了非 Error 对象、第三方声明使用了结构化类型、临时代码写了 any，以及普通逻辑混进 build() 的 UI 语法块。

最后网络请求参数收敛成了显式类：

export class ApiRequestOptions {
  path: string = '';
  method?: ApiHttpMethod;
  authMode?: ApiAuthMode;
  query?: Map<string, string | number | boolean>;
  data?: string;
  headers?: Map<string, string>;
}

创建请求时，不再随手传一个匿名对象，而是先构造实例、再填写字段。代码长了一点，却把数据边界说清楚了。ArkTS 的严格在刚开始很烦，工程变大以后反而减少了“这个对象到底有什么字段”的猜测。

编译错误也因此成了迁移过程里最可靠的提示。它通常会给出规则名、错误号、文件和行号。与其绕过，不如把报错原文留下来，再围绕规则修改。

页面做出来不难，结果对齐才难

项目首页涉及平太阳时、真太阳时、干支和七类取穴算法。这里不能用“页面能打开”作为完成标准。同一个地点、时间和穴位，HarmonyOS 版算出的结果必须和 Android 版一致。

迁移时，我们保留 Android 版作为参照，固定输入样本，再逐项核对输出。一次结果偏差看起来只是一个日干支不对，最后追到旧公式里针对早期年份的位序处理。如果只做页面验收，这类问题很容易漏过去。

阅读器也是同样的道理。PDF 页面能显示不等于大文件能稳定打开；EPUB 能显示文字不等于目录、图片、字号、夜间模式和阅读进度都可用。

迁移工作的验收单位不是“文件写完了”，而是一个真实用户流程走通了。

三方 SDK 是另一套问题

微信、支付宝和团结引擎最容易制造一种错觉：依赖已经加进工程，代码也能编译，功能应该就完成了。

实际还差很多东西。微信需要查询 scheme、回调 action 和 Ability 分发；支付宝需要把回调 URI、客户端 SDK 与服务端签名流程接起来；团结引擎导出的库要处理独立 Ability、原生渲染、返回桥和每次重新导出后的覆盖问题。

这类能力还不能只看 Previewer。签名、应用标识、第三方平台登记和真机环境共同决定最终结果。因此我们的记录里会明确区分：

• 源码静态检查通过；
• ArkTS 编译和 HAP 打包通过；
• 真机拉起通过；
• 生产回调尚待验证。

没有真机结论时就写“待验证”，不拿构建成功代替功能成功。

AI 可以写代码，但不能替你验收

这个项目的大部分实现由 AI 辅助完成。我真正花时间的工作主要有三件：给出准确参照、提供完整报错、逐项验收。

为了让长周期开发不依赖聊天记录，项目里一直维护三份文件：task_plan.md 记录阶段和决策，findings.md 保存技术结论，progress.md 记录改动和验证结果。会话可以结束，结论必须留在项目里。

这套方法并不神秘。它只是把以前写给团队成员的任务说明、排错记录和验收表，继续写给下一次开发会话看。

现在完成了什么

目前已经落地的主要能力包括：五个主导航、手机号与第三方登录、学习和会员、经络查询、PDF/EPUB/视频、时间与取穴算法、微信小程序、微信与支付宝支付接入，以及团结引擎三维经络。

同时还有明确的尾项：部分能力需要正式签名和生产环境继续真机验证，上架材料也要逐项收口。这些没有必要藏起来。真实项目不是某一天突然“全部完成”，而是一项项把未验证变成已验证。

回头看，零经验并不是最大问题。真正危险的是没有迁移边界、没有参照结果，也没有留下验证记录。

如果你也准备把一个旧 Android 项目迁到 HarmonyOS，最担心的是页面重写、业务算法，还是第三方 SDK？后面的文章我会把这三类问题分别拆开。

---

本系列下一篇：《ArkTS 不是 TypeScript：我踩过的 6 条编译红线【鸿蒙心迹】》