harmonyos-app-dev

name	harmonyos-app-dev
version	1.1.0
description	鸿蒙 HarmonyOS NEXT 应用开发全流程技能。覆盖 ArkTS 语言、ArkUI 声明式开发、Stage 模型、状态管理、分布式能力、性能优化、调试排坑、上架审核等完整链路。特别包含 OpenClaw 鸿蒙版真实踩坑：27个编译错误 + 构建配置错误 + 运行时状态管理错误完整案例。
tags	["鸿蒙","HarmonyOS","HarmonyOS NEXT","ArkTS","ArkUI","鸿蒙开发","鸿蒙应用","Stage模型","状态管理","分布式","元服务","卡片开发","DevEco Studio","鸿蒙避坑","鸿蒙上架","hvigor","ohpm","编译错误","运行时错误"]
triggers	["鸿蒙开发","鸿蒙应用","HarmonyOS","ArkTS","ArkUI","鸿蒙避坑","鸿蒙上架","元服务","服务卡片","Stage模型","UIAbility","状态管理装饰器","鸿蒙分布式","DevEco Studio","鸿蒙性能优化","鸿蒙调试","纯血鸿蒙","鸿蒙NEXT","hvigor","ohpm","鸿蒙编译错误","ArkTS严格模式","ObservedV2","Observed","Track","Trace","装饰器混用","鸿蒙运行时错误","hvigor内存不足","DevEco 6.0"]

鸿蒙 HarmonyOS NEXT 应用开发技能

萃取自 HarmonyOS 面试手册、OpenHarmony 资料库、Awesome HarmonyOS 及一线开发团队实战经验，覆盖从环境搭建到上架审核的全链路。

---

一、技术栈全景

HarmonyOS NEXT 技术栈
│
├── 开发语言
│   ├── ArkTS（TypeScript 超集，声明式 UI 语法，限制动态类型特性以降低运行时开销）
│   └── 仓颉（面向全场景智能的新一代编程语言，2025.7 LTS）
│
├── UI 框架
│   ├── ArkUI（声明式开发范式，核心渲染框架）
│   └── Native API（高性能场景）
│
├── 应用模型
│   ├── Stage 模型（HarmonyOS NEXT 唯一推荐模型）
│   ├── UIAbility（功能模块/界面，拥有独立生命周期）
│   ├── ExtensionAbility（系统能力扩展：Service、Form 等）
│   └── AbilityStage（UIAbility 容器）
│
├── 状态管理
│   ├── V1：@State / @Prop / @Link / @Provide/@Consume / @StorageLink/@StorageProp
│   └── V2：属性级观察（推荐，替代 V1 的对象级观察）
│
├── 分布式能力
│   ├── 分布式软总线（设备发现、连接、数据同步）
│   ├── 跨设备调用（远程设备能力调用）
│   └── 应用接续（跨设备无缝协同）
│
├── 开发工具
│   ├── DevEco Studio（官方 IDE，基于 IntelliJ IDEA）
│   ├── ohpm（包管理，类似 npm）
│   ├── hdc（调试工具，类似 ADB）
│   └── Hvigor（构建工具）
│
└── 安全体系
    ├── 星盾安全架构（隐私可控、数据高安）
    ├── 安全控件取代 ACL 权限
    └── CC EAL 6+ 安全认证内核

---

二、环境搭建与项目创建

2.1 开发环境要求

项目	要求
操作系统	Windows 10/11 64位（推荐 16GB+ 内存、100GB+ 硬盘）
IDE	DevEco Studio（从 developer.harmonyos.com 下载）
依赖	Node.js（LTS 版本）、JDK 11
SDK	HarmonyOS NEXT API 版本（首次启动时下载）

2.2 避坑：环境搭建

坑点	解决方案
DevEco Studio 安装失败	确保系统满足最低要求；使用国内镜像下载；关闭杀毒软件/防火墙
SDK 下载缓慢	使用国内镜像站点；手动下载 SDK 解压到指定目录
环境变量配置错误	检查 PATH 变量是否正确配置 JDK、Node.js 和鸿蒙 SDK 路径
Node.js / JDK 缺失	安装前必须先配好 Node.js（LTS）和 JDK 11，否则项目创建失败
网络不稳定	SDK/工具链需从华为服务器下载，务必在稳定网络下进行

2.3 项目类型选择

类型	说明	建议
Application	完整 App，独立图标，可独立安装运行	✅ 新手首选
Atomic Service（元服务）	免安装、轻量化服务，出现在服务中心/负一屏	进阶学习

2.4 项目核心目录结构

MyApplication/
├── AppScope/
│   ├── app.json5              # 应用级元数据（Bundle信息、权限等）
│   └── resources/             # 应用全局资源
├── entry/                     # 默认模块（Module）
│   ├── src/main/
│   │   ├── ets/               # ArkTS 源代码
│   │   │   ├── entryability/  # UIAbility 组件
│   │   │   └── pages/         # 页面文件
│   │   ├── resources/         # 模块资源（字符串、图片等）
│   │   └── module.json5       # 模块级元数据（Ability、路由、权限声明）
│   └── oh-package.json5       # 模块包配置
├── hvigor/                    # 构建脚本
└── build-profile.json5        # 构建配置

关键配置文件：module.json5（模块级）和 app.json5（应用级）是核心配置。

---

三、ArkTS 语言核心

3.1 ArkTS vs TypeScript

ArkTS 是基于 TypeScript 的深度扩展优化语言，不能直接套用 Web 开发的 TS 知识：

维度	ArkTS 特点
静态类型检查	编译期发现类型错误
声明式 UI 语法	与 ArkUI 深度集成
现代语法	支持 ES6+ 特性（箭头函数、解构赋值、async/await）
限制动态类型	降低运行时开销（区别于标准 TypeScript）
装饰器体系	@Entry、@Component、@State 等

3.2 避坑：ArkTS 常见误区

误区	正确做法
混淆 TypeScript 与 ArkTS	ArkTS 有自己的 UI 描述语法和装饰器，不能直接复用 Web TS 代码
忽略状态驱动	核心是状态驱动 UI 更新，通过改变状态变量触发 UI 刷新
直接修改 UI 属性	❌ this.textComponent.text = "new text" 在声明式范式中无效，必须修改状态变量
EntryAbility.ts 后缀问题	新建工程默认 .ts 后缀，导入 .ets 工具类会报错 → 直接改为 .ets

---

四、Stage 模型与 UIAbility 生命周期

4.1 UIAbility 生命周期

Create(onCreate) → WindowStageCreate → Foreground(onForeground) ⇄ Background(onBackground) → Destroy(onDestroy)

回调	触发时机	建议操作
onCreate	Ability 实例创建	初始化全局资源、数据库连接
onWindowStageCreate	窗口阶段创建	加载主页面
onForeground	进入前台（用户可见）	恢复动画、定时器
onBackground	进入后台（用户不可见）	释放非必要资源、断开网络
onDestroy	即将销毁	释放所有资源

4.2 避坑：生命周期管理

坑点	解决方案
生命周期回调不触发或顺序异常	确保正确实现生命周期方法，避免在生命周期方法中执行耗时操作
Intent 传递数据过大	确保数据大小不超过限制
应用启动慢	减少 onCreate 和 onWindowStageCreate 中的耗时操作，非必要初始化延迟到空闲时

4.3 核心概念类比（帮助快速上手）

鸿蒙概念	iOS 类比	Android 类比
AbilityStage	UIViewController	Activity 生命周期管理
WindowStage	UIWindow	Window
UIAbility	UIViewController	Activity
ExtensionAbility	App Extension	Service

---

五、ArkUI 声明式开发

5.1 核心思想

"What to render, not How to render" — 开发者只需描述 UI 应该是什么样子（基于当前状态），框架自动处理高效渲染和更新。

5.2 装饰器体系

装饰器	作用范围	说明
@Component	组件定义	定义可复用的自定义组件
@Entry	入口标记	标记应用的入口组件
@State	组件内部	私有状态，变化触发 UI 更新
@Prop	父→子（单向）	父组件传递给子组件的只读属性
@Link	父↔子（双向）	父子组件双向同步
@Provide / @Consume	跨多层组件	状态共享（替代逐层传递）
@StorageLink / @StorageProp	应用级	与 AppStorage / PersistentStorage 关联
@Builder	轻量 UI 复用	无状态组件，替代 @Component 减少状态依赖
@Watch	监听	监听状态变量变化，执行回调

5.3 状态管理 V1 vs V2

维度	V1	V2（推荐）
观察粒度	对象级观察	属性级观察
更新开销	较高	更低，精准更新
适用场景	旧项目兼容	新项目推荐

5.4 避坑：ArkUI 开发

坑点	解决方案
状态更新时机问题	状态更新是异步的，需在更新后操作时用 $watch 或放入下一个事件循环
width/height 百分比 100% 导致遮挡	子组件 .height('100%') 不会预留同级组件空间 → 改用 .layoutWeight(1)（仅 Row/Column/Flex 生效）
RelativeContainer 无子组件时不显示	必须有子组件且子组件设置 ID 才显示
RelativeContainer 子组件 100% 宽高 + margin 无效	不依赖 RelativeContainer 的 padding/margin，改用 offset 调整
RelativeContainer 右边距设置无效	使用"套娃"方案（嵌套其他容器组件）
RelativeContainer padding 不生效	给子组件设 offset({x:0}) 可使父 padding left 生效；直接用 offset 调整偏移
全屏后 WebView 显示异常	WebView 组件作为独立窗口未设全屏导致（已知问题）

5.5 定位属性辨析

属性	坐标原点	递增方向	用途
position({x, y})	父组件左上角	x→右, y→下	绝对定位
markAnchor({x, y})	配合 position 使用时为 position 坐标点	x→左, y→上	锚点偏移
offset({x, y})	前一个组件右上角	x→右, y→下	相对偏移

---

六、路由与导航

6.1 方案选型

方案	推荐度	说明
Navigation（组件导航）	✅ 强烈推荐	官方主推，持续演进，支持复杂页面栈管理
router（页面路由）	❌ 不推荐	未来不再演进，能力有限，无法管理复杂页面栈

6.2 避坑：路由方案

重要：应尽早选用 Navigation 方案，避免在即将废弃的 router 上大量投入。越晚调整代价越高。复杂页面栈（如关闭指定 WebView）必须用 Navigation。

---

七、网络请求与数据存储

7.1 网络请求

• HTTP 请求：@ohos.net.http
• WebSocket 通信
• 数据请求与解析

7.2 数据存储

方案	适用场景	说明
Preferences（用户首选项）	轻量 KV 存储	类似 SharedPreferences
RDB（关系型数据库）	结构化数据	基于 SQLite
分布式数据	跨设备同步	分布式软总线支持

7.3 避坑：数据相关

坑点	解决方案
Map 遍历常见错误	注意类型误判、遍历与赋值方式不匹配、并发修改问题；使用运行时类型守卫
VPN 类型网络判断	使用 getNetCapabilities 方法获取 bearerTypes 判断

---

八、线程模型与并发

8.1 线程方案

方案	说明
TaskPool	推荐的任务池方案，自动管理线程
Worker	长时间运行的后台任务
EventHub	事件通信机制

8.2 避坑

• 避免在主线程执行耗时操作
• 耗时任务（网络请求、文件 I/O、大数据处理）应使用 TaskPool 或 Worker
• 注意线程间通信的数据序列化开销

---

九、权限与安全

9.1 安全架构变化

HarmonyOS NEXT 从**"权限管控"转向"数据管控"**：

• 安全控件取代 ACL 权限
• 用户每次操作都需明确授权
• 禁止开发九类不合理权限
• 分享转发实现系统级授权

9.2 避坑：权限管理

坑点	解决方案
ACL 权限被要求整改为安全控件	密切关注华为推进节奏和整改期限，及时调整，否则影响上架
权限申请失败	在 module.json5 中正确声明权限；使用 requestPermissionsFromUser 动态申请
分布式能力权限	必须声明 ohos.permission.DISTRIBUTED_DATASYNC；首次使用需引导用户授权
敏感数据访问	使用安全控件，让用户明确选择要分享的数据

---

十、元服务与卡片开发

10.1 元服务（Atomic Service）

核心理念："服务找人"而非"人找服务"

• 项目创建时选择 Atomic Service 模板
• 需在 AppGallery Connect (AGC) 创建项目获取配置
• 核心交互形式是服务卡片，使用 @Builder 构建 UI

10.2 卡片开发

• 服务卡片：Form Extension
• 卡片更新机制
• 卡片数据交互

10.3 适用场景

快捷支付、快递查询、智能家居控制、新闻摘要等高频低时延场景

---

十一、分布式能力

11.1 核心能力

能力	说明
设备发现与连接	自动发现附近 HarmonyOS 设备，建立安全低延迟连接
跨设备调用	像调用本地方法一样调用远程设备能力（摄像头、扬声器等）
数据协同	跨设备数据实时同步和共享
应用接续	跨设备无缝协同（鸿蒙独有）

11.2 避坑：分布式开发

坑点	解决方案
设备发现失败	确保设备连接到同一网络
分布式能力调用失败	检查权限配置，严格遵循官方示例代码
缺少权限声明	必须在 module.json5 中声明分布式权限
未引导用户授权	首次使用跨设备能力时系统弹出授权弹窗，需引导用户授权

---

十二、性能优化

12.1 渲染原理

ArkUI 渲染流程：组件树构建 → 布局测量 → 渲染绘制

差异更新机制：

• 布局脏：影响尺寸和位置，需重新测量布局
• 绘制脏：仅影响样式，重绘但不重新布局

12.2 优化策略矩阵

优化方向	具体做法
冷启动优化	减少 onCreate/onWindowStageCreate 耗时操作，非必要初始化延迟到空闲时
列表优化	长列表务必使用 LazyForEach 懒加载，避免一次性创建所有子组件
布局优化	使用扁平化布局组件（RelativeContainer、Grid）替代多层 Column/Row 嵌套
组件复用	利用组件复用机制，减少滑动过程中组件创建、布局开销
图片优化	使用合适的图片格式和尺寸，避免在 UI 线程进行大图解码
状态管理优化	采用状态管理 V2（属性级观察），降低更新开销
减少组件数	优先使用无状态组件 @Builder 替代 @Component，减少状态依赖
固定尺寸	对固定尺寸组件设置具体宽高，限制布局影响范围
分帧渲染	高负载场景将一帧内加载的数据分成多帧（仅必要时使用）

12.3 帧率标准

设备	单帧耗时上限
120fps	≤ 8ms
90fps	≤ 12ms

12.4 性能分析工具

工具	用途
AppAnalyzer	"体检-报告-修复"一体化，快速定位布局耗时及性能瓶颈
ArkUI Inspector	可视化展示 UI 组件树，分析布局层次和参数
CPU Profiler	抓取 trace 和调用栈，分析耗时点
Time Profiler	分析函数调用耗时
Allocation Profiler	监控内存分配，发现内存泄漏
Frame Profiler	分析 UI 帧率，解决卡顿/掉帧

12.5 避坑：性能相关

坑点	解决方案
应用启动慢	减少 onStart 方法中的初始化操作，使用异步任务加载资源
内存泄漏	避免全局变量持有 Context 引用，及时释放不再使用的资源
麒麟芯片设备冻屏	API9+Stage模型在麒麟设备可能出现冻屏（页面不刷新），属系统兼容性问题
长列表卡顿	必须用 LazyForEach 懒加载 + 实现 IDataSource 接口

---

十三、调试与排坑

13.1 调试方法

方式	说明
断点调试	在 ArkTS 代码中设断点，查看变量值、调用栈
日志输出	使用 console.log() 或 HiLog 输出调试信息
预览器	实时预览 UI 效果，修改代码后自动刷新
hdc 工具	类似 ADB，支持设备查询、文件、安装卸载、shell、日志

13.2 HiLog 使用

import hilog from '@ohos.hilog';

const DOMAIN = 0x00201;
const TAG = 'MyTag';

hilog.info(DOMAIN, TAG, 'Ability Started');
hilog.error(DOMAIN, TAG, 'Error occurred: %{public}s', errorMsg);

13.3 避坑：调试相关

坑点	解决方案
日志输出不完整	使用 HiLog 工具，确保日志级别设置正确；用 hdc 查看设备日志
hdc 连接设备失败	确保设备开启开发者模式并启用 USB 调试；检查 hdc 版本匹配
真机 UI 不刷新（旧设备）	华为 P40Pro 等旧设备在鸿蒙 4.0 上可能卡顿/不刷新 → 用模拟器或新设备
系统 Bug 导致卡死重启	先区分系统层还是应用层问题，善用 hdc hilog 抓日志
预览器正常但真机异常	预览器和真机行为可能不一致，务必真机测试

---

十四、WebView 开发

14.1 技术要点

• 内核：ArkWeb（方舟 Web 内核），基于 Chrome 114 定制
• 兼容性查询：https://caniuse.com/
• Hybrid 通信：Native 与 WebView 的 Bridge 是全新方案，不能复用 Android/iOS 的 Bridge 实现

14.2 API 梳理方法论

分类	处理策略
直接支持，前端无需修改	功能对等实现或简化实现
推荐使用新方案	用新方案替代旧方案
不支持	业务下线 / 版本初期不考虑

关键方法：根据线上 URL 中接口调用的埋点日志，结合业务归属，整理二维矩阵表评估改造工作量。

---

十五、第三方库与 SDK

15.1 包管理

• ohpm：类似 npm，但有独立的 package.json 命名、lock 文件内容和开源中心仓
• 私仓用 ohpm-repo 部署
• 三方库组织：gitee.com/openharmony-tpc

15.2 避坑：三方依赖

坑点	解决方案
第三方库不兼容	优先使用鸿蒙官方推荐的库；检查库的依赖与鸿蒙 NEXT 兼容性；必要时修改源码适配
微信/支付宝等 SDK 缺失	涉及登录、支付、分享等核心业务必须准备 PlanB 方案
Hvigor 构建工具 Bug	检查 hvigor 版本是否正确；验证 @ohos/hvigor 路径
UniApp 对鸿蒙 NEXT 不兼容	原有基于安卓的 UniApp 无法直接运行，需等待官方适配

---

十六、应用上架审核

16.1 上架前准备

准备项	说明
开发者实名认证	华为开发者联盟完成
资质证书	软件著作权登记证书 / 电子版权认证
隐私政策	必须提供完整隐私政策文档
应用签名	配置签名证书（发布证书与调试证书）
应用图标与截图	按要求提供各尺寸资源

16.2 审核要点

审核维度	注意事项
功能完整性	所有声明功能必须可用，不能有空壳页面
隐私合规	安全控件取代 ACL 权限；用户明确授权；隐私政策完整
权限使用	权限声明与使用必须匹配；禁止过度申请权限
内容规范	内容合法合规，无违规信息
性能标准	无卡顿、崩溃、内存泄漏等性能问题
稳定性	应用不能出现闪退、ANR 等问题

16.3 避坑：上架审核

坑点	解决方案
ACL 权限被要求整改	及早适配安全控件方案，否则影响上架
Dev 证书 100 台设备限制	通过 AGC 后台企业分发能力解决内部测试
审核被驳回	仔细阅读驳回原因，按审核指南逐项整改

---

十七、学习路径与资源

17.1 推荐学习路径

基础搭建（环境 + Hello World）
  → 语言精进（ArkTS + 声明式 UI）
    → 模型理解（Stage 模型 + UIAbility 生命周期）
      → 实战演练（完整应用开发）
        → 探索进阶（元服务 + 分布式 + 性能优化）

17.2 官方资源

资源	地址
鸿蒙开发者官网	developer.harmonyos.com
DevEco Studio 下载	developer.harmonyos.com/cn/develop/deveco-studio
HarmonyOS NEXT 文档	developer.harmonyos.com/cn/documentation
AppGallery Connect	developer.huawei.com/consumer/cn/service/josp/agc/
OpenHarmony 官网	www.openharmony.cn
应用审核指南	developer.huawei.com/consumer/cn/doc/app/50170
ohpm 开源中心	ohpm.openharmony.cn

17.3 社区与学习

资源	地址
华为开发者论坛	developer.huawei.com/consumer
华为开发者学院	developer.huawei.com/consumer/cn/training/
鸿蒙学堂	hmxt.org
OpenHarmony 在线交流	zulip.openharmony.cn
OpenHarmony SIG 列表	www.openharmony.cn/sig

---

十八、速查清单：Top 30 避坑要点

1. 环境先行：开发前确认环境配置正确，优先使用国内镜像
2. 紧跟官方：鸿蒙 NEXT 版本迭代快，及时关注官方文档更新
3. 选 Navigation 不选 router：router 不再演进，Navigation 是官方推荐
4. 安全控件取代 ACL：隐私合规方向已变，不及时跟进影响上架
5. 状态驱动 UI：不能直接修改 UI 属性，必须通过状态变量触发更新
6. 生命周期忌耗时：onCreate 等回调中绝不能执行耗时操作
7. 长列表用 LazyForEach：一次性创建所有子组件会严重卡顿
8. 布局权重代替 100%：.layoutWeight(1) 替代 .height('100%') 避免遮挡
9. 状态管理用 V2：属性级观察替代对象级观察，降低更新开销
10. EntryAbility 后缀改 .ets：.ts 导入 .ets 文件会报错
11. 内存警惕 Context 泄漏：全局变量持有 Context 是内存泄漏常见原因
12. 真机测试不可少：预览器和真机行为可能不一致
13. 权限声明要完整：敏感能力必须正确声明并动态申请
14. 分布式需同网络：设备发现和连接要求在同一网络下
15. 三方库验兼容性：使用前务必验证鸿蒙 NEXT 兼容性
16. PlanB 应对 SDK 缺失：微信/支付宝等 SDK 前期可能无鸿蒙版本
17. 区分系统 vs 应用 Bug：遇异常先用 hdc hilog 定位，善用华为工单
18. RelativeContainer 小心使用：padding/margin 行为特殊，优先用 offset
19. 组件复用优于重建：利用组件复用机制提升滑动帧率
20. 扁平化布局减少嵌套：RelativeContainer/Grid 替代多层 Column/Row
21. @Builder 替代 @Component：无状态 UI 复用场景减少状态依赖
22. WebView Bridge 全新：不能复用 Android/iOS 的 Bridge 实现
23. 固定尺寸组件设具体值：限制布局影响范围，减少不必要的重新布局
24. 旧设备兼容性问题：麒麟芯片设备可能有冻屏等系统级 Bug
25. ohpm 不是 npm：包管理方式有差异，私仓用 ohpm-repo
26. 上架需完整资质：软件著作权、隐私政策、签名证书缺一不可
27. Dev 证书设备数有限：企业分发解决内部测试需求
28. 埋点数据驱动 API 评估：WebView Hybrid 迁移时用线上数据评估工作量
29. 沟通价值最大化：当前阶段华为工单响应效率高，有问题积极提工单
30. 类比学习但独立深入：与 Android/iOS 类比加速理解，但鸿蒙特有概念需独立掌握

---

十九、仓颉编程语言（前瞻）

面向全场景智能的新一代编程语言，特征：

• 原生智能化、天生全场景、高性能、强安全
• 2025.7.1 LTS 版本正式发布
• Magic 框架：基于仓颉的 LLM Agent 开发框架（Agent DSL、MCP 协议）

当前鸿蒙 NEXT 主力开发语言仍为 ArkTS，仓颉为前瞻方向。

---

二十、版本历程参考

时间	里程碑
2023.11	鸿蒙 NEXT 宣布不再支持安卓
2024.1	原生 HarmonyOS NEXT 鸿蒙星河版发布，首批 200+ 原生应用启动
2024.6	HDC 2024 发布纯血鸿蒙；仓颉编程语言发布；设备超 9 亿
2024.10	HarmonyOS NEXT 正式版（鸿蒙 5）发布，生态设备超 10 亿台
2025.5	发布鸿蒙电脑；OpenHarmony 5.1.0 Release（API 18）
2025.7	仓颉编程语言 LTS 版本正式发布

---

---

二十一、OpenClaw HarmonyOS 真实踩坑经历（27 个编译错误实战）

以下内容来自 OpenClaw 鸿蒙版 App 真实开发过程中遇到的所有 ArkTS 编译错误及修复方案，共 27 个错误分两轮修复。

第一轮：18 个 ArkTS 编译错误

✅ 1. 类型定义错误（arkts-no-untyped-obj-literals）

• 错误信息：Object literal must correspond to some explicitly declared class or interface
• 问题：ArkTS 需要显式的类型定义，不支持隐式对象字面量
• 修复：

// 添加接口定义
interface ColorTokens {
  primary: string;
  background: string;
  // ...
}
interface SpacingTokens {
  sm: number;
  md: number;
  // ...
}

// 显式声明类型
const COLORS: ColorTokens = {
  primary: '#4F8EF7',
  background: '#F5F6FA',
}

• 避坑：所有对象字面量必须先定义接口或类型别名

✅ 2. Shape 组件 viewBox 属性不存在

• 错误信息：Property 'viewBox' does not exist on type 'ShapeAttribute'
• 问题：ArkTS 的 Shape 组件不支持 viewBox 属性
• 修复：移除所有 .viewBox() 调用

✅ 3. Rect 组件 x/y/rx 属性错误

• 错误信息：
  • Property 'x' does not exist on type 'RectAttribute'
  • Property 'rx' does not exist on type 'RectAttribute'
  • Argument of type '{ x, y, width, height }' is not assignable
• 问题：Rect 的 x、y、width、height 不能用链式方法设置；rx 方法不存在
• 修复方案一（推荐）：改用 Path 组件绘制

// 错误方式：
Rect().width(8).height(8).x(3).y(3).rx(2)

// 正确方式（Path）：
Path().commands('M3 3H11V11H3V3Z')

• 修复方案二：Rect 构造函数传参

// 正确方式（Rect）：
Rect({ x: 3, y: 3, width: 8, height: 8 })

✅ 4. FontWeight.SemiBold 不存在

• 错误信息：Property 'SemiBold' does not exist on type 'typeof FontWeight'
• 问题：ArkTS 中没有 FontWeight.SemiBold 常量
• 修复：使用 FontWeight.Medium 代替

// 错误：
.fontWeight(FontWeight.SemiBold)

// 正确：
.fontWeight(FontWeight.Medium)

• 可用字重值：Light、Normal（或 Regular）、Medium、Bold

✅ 5. fontVariant 属性不存在

• 错误信息：
  • Property 'fontVariant' does not exist on type 'TextAttribute'
  • Cannot find name 'FontVariantNumeric'
• 问题：ArkTS 不支持 fontVariant 属性
• 修复：移除 .fontVariant(FontVariantNumeric.TABULAR_NUMS) 调用

✅ 6. .background() 返回 void

• 错误信息：Property 'margin' does not exist on type 'void'
• 问题：.background() 方法返回 void 类型，不能链式调用 .margin()
• 修复：使用 .backgroundColor() 代替 .background()
• 影响：修复了 8 处 .background() 调用
• 避坑：ArkTS 中背景颜色正确的 API 是 .backgroundColor()

✅ 7. Transition API 格式错误

• 错误信息：Argument of type '{ type: TransitionType.All, duration: 120, curve: Curve.EaseInOut }' is not assignable
• 问题：ArkTS 的 transition API 使用不同格式
• 修复：

// 错误方式：
.transition({ type: TransitionType.All, duration: 120, curve: Curve.EaseInOut })

// 正确方式：
.transition(TransitionEffect.OPACITY.animation({ duration: 120, curve: Curve.EaseInOut }))

第二轮：9 个额外错误

✅ 8. 多处 Rect 组件 x/y/rx 错误

• 问题：第一轮修复时部分 Rect 组件改用构造函数方式，但 rx() 方法仍然不存在
• 修复：全部改用 Path 组件绘制四宫格等图标

// 四宫格图标（之前错误）：
Rect({ x: 3, y: 3, width: 8, height: 8 }).rx(2)

// 正确方式：
Path().commands('M3 3H11V11H3V3ZM13 3H21V11H13V3ZM3 13H11V21H3V13ZM13 13H21V21H13V13Z')

✅ 9. @Builder 方法链式调用错误

• 错误信息：Property 'margin' does not exist on type 'void'
• 问题：在 @Builder 方法的结果上调用 .margin()，但 Builder 返回 void
• 修复：移除调用处的 .margin()，因为 ConnectionCard 内部已设置 margin
• 避坑：@Builder 方法不返回组件对象，不能链式调用属性方法

ArkTS 开发核心规则（避坑精华）

规则	说明
严格类型检查	所有对象字面量必须有接口/类型定义，不支持隐式类型
组件 API	.background() → .backgroundColor()；.fontVariant() → 移除
Rect/Shape	无 viewBox；Rect 用构造函数 {x, y, w, h} 或改用 Path；无 rx()
字重枚举	可用：Light、Normal、Medium、Bold；无 SemiBold
Transition	使用 TransitionEffect 枚举配合 .animation() 方法
@Builder	不返回组件对象，不能链式调用属性方法
严禁混用 V1/V2 装饰器	@State/@Component 与 @Param/@ComponentV2 不可混用
@Track 限制	getter/计算属性不能被 @Track 追踪，需改为 @Track 属性 + 手动更新方法

ArkTS V1 vs V2 装饰器对照

V1	V2	说明
@Component	@ComponentV2	组件定义
@State	@Param	组件内状态
@Prop	@Event	父→子单向
@Link	—	父子双向
@Provide	@Provider	跨层级共享
@Consume	@Consumer	跨层级消费
@Observed + @Track	@ObservedV2 + @Trace	状态观察
AppStorage / PersistentStorage	AppStorageV2	持久化存储

OpenClaw HarmonyOS 项目技术栈参考

• DevEco Studio：6.0.2 Release (Build 6.0.2.650)
• SDK：HarmonyOS NEXT SDK
• 目标设备：Phone / Tablet
• 架构：MVVM（Model-View-ViewModel）
• 路由：Navigation + NavPathStack
• 网络：@ohos.net.http
• 存储：@ohos.data.preference / @ohos.data.storage
• 状态管理：@State / @Link / @Watch / @Observed + @Track
• 内置 Skills：16 个（v1.2.0 版本）

OpenClaw HarmonyOS 语音能力集成方案

TTS（语音播报）方案选择

方案	优点	缺点
华为 HMS ML Kit TTS（推荐）	华为设备原生体验，中文效果好，无需网络	需在 AppGallery Connect 开通 ML Kit
OpenClaw 后端 TTS API	统一后端管理，支持多种音色	需要后端接入 TTS 服务

ASR（语音识别）方案选择

方式	说明	依赖
方式一（推荐）	OpenClaw 后端已有 Whisper ASR 接口	后端配置 /v1/audio/transcriptions
方式二	华为 HMS Speech Kit	需集成 HMS ML Kit
方式三	腾讯 / 百度 ASR API	需替换 HTTP 调用

OpenClaw HarmonyOS UI 设计规范参考

• 背景色：#F2F2F7（iOS 标准设置页背景）
• 卡片圆角：12vp border-radius
• 分区标题：13fp，灰色 #8E8E93
• 主色调：#4F8EF7（科技蓝）
• 危险操作：红色 #FF3B30
• Toggle 选中色：#4F8EF7
• 滚动效果：弹性滚动 + Spring 效果

---

本 Skill 萃取自以下资源：HarmonyOS-Next/interview-handbook-project、fenwii/OpenHarmony、Awesome-HarmonyOS/HarmonyOS，以及华为官方博客、InfoQ、CSDN、掘金、腾讯云开发者社区等一线实战经验。特别新增：OpenClaw 鸿蒙版 App 全链路踩坑：27 个 ArkTS 编译错误 + 构建配置错误 + 运行时状态管理错误（2026-04-11 ～ 2026-04-14）。

---

二十二、OpenClaw HarmonyOS 构建配置 & 运行时测试完整踩坑

背景：OpenClaw 鸿蒙版 App 从零搭建到真机运行，经历了三个阶段：构建配置阶段 → ArkTS 编译阶段 → 运行时测试阶段，共计出现 40+ 个问题。本章补充编译错误之外的全部问题。

---

第一阶段：项目构建配置错误（hvigor / DevEco 6.0.2 迁移）

✅ B1. hvigorfile.ts 导入路径错误

• 错误信息：Cannot find module '@ohos/hvigor-ohos-plugin'
• 根本原因：DevEco 6.0.2 调整了 hvigor 插件路径
• 修复：

// 旧（失效）：
import { hapTasks } from '@ohos/hvigor-ohos-plugin';

// 新（DevEco 6.0.2 正确路径）：
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
// 同时确保 oh-package.json5 中依赖项与 SDK 版本对齐

• 避坑：升级 DevEco 大版本后必须同步升级 hvigor 依赖版本，查看 hvigor/hvigor-config.json5 中的版本号。

✅ B2. build-profile.json5 模块配置缺失

• 错误信息：compileSdkVersion / compatibleSdkVersion 字段缺失或格式错误
• 修复：必须同时配置应用级 build-profile.json5 和模块级 entry/build-profile.json5，两者格式不同

// 应用级（根目录）
{
  "app": { "signingConfigs": [...], "products": [...], "buildModeSet": [...] },
  "modules": [{ "name": "entry", "srcPath": "./entry" }]
}
// 模块级（entry/）
{
  "apiType": "stageMode",
  "buildOption": {},
  "targets": [{ "name": "default" }]
}

✅ B3. $media:app_icon 资源引用找不到

• 错误信息：$media:app_icon is not defined
• 问题：module.json5 中 icon 引用的资源文件不存在
• 修复：在 entry/src/main/resources/base/media/ 和 AppScope/resources/base/media/ 下都放入 app_icon.png（至少 512×512）

✅ B4. module.json5 权限声明格式错误

• 错误信息：requestPermissions 格式不正确导致 Sync 失败
• 修复：

// 正确格式
"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]
// 不能省略 "name" 字段，不能只写字符串数组

✅ B5. EntryAbility.ts 后缀问题

• 错误信息：导入 .ets 文件失败
• 问题：新建工程默认生成 EntryAbility.ts，但其他 .ets 文件无法被 .ts 文件正确引用
• 修复：将 EntryAbility.ts 改名为 EntryAbility.ets，所有 Ability 文件使用 .ets 后缀

✅ B6. hvigor 构建内存不足

• 错误信息：OutOfMemoryError: Java heap space 或构建进程无响应
• 原因：默认 JVM 堆内存在大型项目/全量编译时不足
• 修复：在 hvigor/hvigor-config.json5 中增加 jvmOptions：

{
  "modelVersion": "5.0.0",
  "execution": {
    "daemon": {
      "jvmOptions": ["-Xmx4096m", "-XX:MaxMetaspaceSize=512m"]
    }
  }
}

• 避坑：首次完整构建或切换 SDK 版本后容易触发，建议预先设置为 4GB+

✅ B7. ohpm 依赖版本冲突

• 错误信息：ohpm install 失败，peer dependency 版本不匹配
• 常见原因：@ohos/hypium、@ohos/hvigor-ohos-plugin 版本与 SDK API Level 不匹配
• 修复原则：
  1. 查看 DevEco Studio 的 SDK Manager 确认 API Level
  2. 参照 OpenHarmony 配套关系表 确定 ohpm 包版本
  3. 删除 oh_modules/ 目录 + oh-package-lock.json5，重新 ohpm install

---

第二阶段：ArkTS 严格模式编译错误（27 个，已在第二十一章详述）

详见 § 二十一 完整记录。核心规则速览：

规则	ArkTS 正确写法
对象字面量	必须有接口/类型别名，不可隐式
for...in	❌ 禁止，改用 Object.keys() + for...of
动态 import	❌ 不支持 new (import(...).Class)()，使用静态 import
background()	→ backgroundColor()
FontWeight.SemiBold	→ FontWeight.Medium
fontVariant	→ 移除
Rect.x/y/rx	→ 使用 Path().commands(...) 绘制
.transition({...})	→ TransitionEffect.OPACITY.animation({...})
@Builder 链式调用	❌ Builder 返回 void，不可链式调 .margin() 等

---

第三阶段：运行时测试错误（实机测试阶段）

✅ R1. @Provide + @State 与 @ObservedV2 不兼容（严重）

• 现象：编译通过，但 App 启动后立即崩溃或功能异常（UI 不更新）
• 错误日志（hdc hilog 中）：

  Error: Cannot mix @Provide/@State (V1) decorators with @ObservedV2 class (V2)
  

• 根本原因：V1 装饰器（@Provide/@State/@Component）和 V2 装饰器（@ObservedV2/@Trace/@ComponentV2）严禁混用，但编译器不总是报错，运行时才崩溃
• 涉及文件：ChatViewModel.ets、SkillsViewModel.ets、HistoryViewModel.ets、SettingsViewModel.ets、Index.ets
• 修复方案：统一使用 V1 体系（因 Index.ets 使用了 @Provide/@State）：

// ❌ 错误（混用）：
@ObservedV2   // V2
class ChatViewModel {
  @Trace messages: ChatMessage[] = [];  // V2
}
@Component    // V1
struct Index {
  @State viewModel: ChatViewModel = new ChatViewModel();  // V1 持有 V2 对象 → 崩溃
}

// ✅ 正确（统一 V1）：
@Observed     // V1
class ChatViewModel {
  @Track messages: ChatMessage[] = [];  // V1
}
@Component    // V1
struct Index {
  @State viewModel: ChatViewModel = new ChatViewModel();  // ✅ 兼容
}

• 决策原则：先确定主页面（Index.ets）使用 V1 还是 V2，所有 ViewModel 必须与之保持一致。

✅ R2. @Track 不能追踪 getter / 计算属性

• 现象：列表筛选功能失效，搜索结果不更新
• 问题代码：

@Observed
class SkillsViewModel {
  @Track allSkills: Skill[] = [...];
  @Track searchQuery: string = '';

  // ❌ getter 无法被 @Track 追踪
  get filteredSkills(): Skill[] {
    return this.allSkills.filter(s => s.name.includes(this.searchQuery));
  }
}

• 修复：将 getter 改为 @Track 属性 + 手动更新方法：

@Observed
class SkillsViewModel {
  @Track allSkills: Skill[] = [...];
  @Track searchQuery: string = '';
  @Track filteredSkills: Skill[] = [...];  // ✅ 独立 @Track 属性

  updateFilter(): void {
    this.filteredSkills = this.allSkills.filter(
      s => s.name.includes(this.searchQuery)
    );
  }
}
// 在 searchQuery 变化时手动调用 updateFilter()

• 避坑：@Track 只能追踪属性赋值，computed/getter 不触发重渲染，必须手动维护派生状态。

✅ R3. @Watch 监听器在 @Observed 类中无效

• 现象：设置 @Watch 的回调从不触发
• 问题：@Watch 只在 @Component 内的 @State/@Prop/@Link 等装饰器上有效，不能用于 @Observed 类的属性
• 修复：在组件侧用 @Watch 监听 ViewModel 引用变化，或在 ViewModel 方法内部直接调用回调逻辑

✅ R4. StorageService 首次读取返回 undefined

• 现象：App 首次安装后，设置界面所有值都是空/异常
• 原因：Preferences 在 key 不存在时返回 undefined，但 ArkTS 不允许隐式 undefined
• 修复：所有 get 操作必须提供默认值：

// ❌ 错误
const apiUrl: string = await pref.get('api_url') as string;

// ✅ 正确
const apiUrl: string = await pref.get('api_url', 'http://localhost:7890') as string;

✅ R5. HTTP 请求 INTERNET 权限运行时被拒绝

• 现象：编译正常，联网请求返回 permission denied
• 原因：仅在 module.json5 声明权限还不够，需要确认 Ability 级别权限配置
• 修复：
  1. module.json5 requestPermissions 正确声明 ohos.permission.INTERNET
  2. 真机需开发者模式 + 允许调试安装
  3. HTTP（非 HTTPS）需要额外在 module.json5 的 network 配置中允许明文传输：

"metadata": [
  {
    "name": "network_security_config",
    "resource": "$profile:network_security_config"
  }
]
// 并创建 resources/base/profile/network_security_config.json：
{ "domain-config": [{ "domain": [{"subdomains": true, "name": "localhost"}], "trust-anchors": [{"certificates": "@system/etc/security/cacerts"}] }] }

---

第四阶段：综合决策与最佳实践（来自 OpenClaw 项目经验）

🔑 V1 vs V2 决策树

你的项目中 Index.ets（根页面）使用哪套装饰器？
│
├── 使用 @Component + @State / @Provide
│   └── 所有 ViewModel 用 @Observed + @Track（V1 体系）
│       ✅ 编译 OK；@Track 不追踪 getter，需手动维护派生状态
│
└── 使用 @ComponentV2 + @Param / @Provider
    └── 所有 ViewModel 用 @ObservedV2 + @Trace（V2 体系）
        ✅ 属性级观察更精准；新项目推荐

结论：绝对不能两套混用，即使编译通过，运行时也会崩溃或 UI 不更新。选定一套后全项目统一。

🔑 构建问题排查优先级

1. Sync 失败 → 先看 build-profile.json5 和 module.json5 配置
2. ohpm install 失败 → 删除 oh_modules/ 重装，检查版本对应关系
3. 编译 ArkTS 错误 → 逐一按类型分类修复（见 § 二十一）
4. 内存溢出 → hvigor-config.json5 加 -Xmx4096m
5. 运行时崩溃 → hdc hilog 抓日志，优先排查 V1/V2 混用问题

🔑 hdc 常用排查命令

# 查看设备
hdc list targets

# 实时查看应用日志（过滤包名）
hdc hilog | grep "com.openclaw.app"

# 安装调试包
hdc install entry-default-unsigned.hap

# 截图
hdc shell snapshot_display -f /data/local/tmp/screen.png
hdc file recv /data/local/tmp/screen.png ./screen.png