DevEco CLI :鸿蒙应用《英语学习手册》从 0 开发到上架应用市场

码农乐园

42人浏览 · 2026-09-16 13:24:53

码农乐园 · 2026-09-16 13:24:53 发布

以一个真实上线项目为样本，完整拆解 ArkTS 业务实现、DevEcoCLI 构建、真机调试、签名打包与华为应用市场发布。文章中的目录、命令、截图和踩坑均来自实际工程。

工程：HarmonyOS NEXT 原生应用
技术：ArkTS / ArkUI / Preferences / RawFile
产物：HAP 真机包 + APP 上架包

文章目录

01 先看最终结果
02 环境与工程初始化
03 业务架构怎么拆
04 把学习闭环做完整
05 DevEcoCLI 构建实战
06 真机安装与排错
07 签名与市场上架
08 真实踩坑复盘
09 发布前清单

01 / PRODUCT

先看最终结果：不是 Demo，而是完整学习产品

《英语学习手册》的目标不是展示几个 ArkUI 组件，而是完成“选词库 → 背单词 → 智能复习 → 默写与语法巩固 → 统计反馈”的闭环，并把真实用户反馈继续迭代进版本。

v1.1.1当前工程版本

API 22目标与兼容 SDK

16 类基础、考试与留学词库

离线优先词库与核心学习流程

从小学到四六级、考研、雅思托福等多类词库，学习进度分别保存。单词、音标、发音与四选一释义构成主学习路径，答案会进入复习策略。周学习量、学习时长与个人遗忘曲线，让学习结果可见。

后续版本还加入了顺序/乱序背词、选择题/思考翻卡两种模式、每日新词与复习目标、答错或“不熟悉”单词的智能复习、桌面宽卡片与锁屏实况窗扩展。真实项目的难点往往不在“页面能显示”，而在状态能否持续、数据能否刷新、系统能力能否真正获得授权。

02 / BOOTSTRAP

环境与工程初始化：先把可重复构建建立起来

开发环境使用 DevEco Studio，项目采用 Stage 模型。全局应用信息放在 AppScope/app.json5，入口模块与系统扩展声明放在 entry/src/main/module.json5。当前实际包名是 com.qxf.jiaoju。

版本信息只保留一个事实来源

AppScope/app.json5

{
  "app": {
    "bundleName": "com.qxf.jiaoju",
    "versionCode": 1001001,
    "versionName": "1.1.1",
    "icon": "$media:xxyy",
    "label": "$string:app_name"
  }
}

versionCode 必须递增，应用市场用它判断是否为新版本；versionName 面向用户展示。两者不要在发布当天临时修改，最好在进入发布分支时就确认。

真实工程目录

jiaoju/
├── AppScope/                         # 应用级配置、图标、版本
├── entry/src/main/
│   ├── ets/
│   │   ├── entryability/             # UIAbility 入口
│   │   ├── pages/                    # 首页、背词、复习、默写、语法、统计
│   │   ├── components/               # 通用标题、图标、筛选控件
│   │   ├── services/                 # 数据、学习策略、发音、锁屏服务
│   │   └── models/                   # WordItem / WordProgress 等模型
│   └── resources/
│       ├── rawfile/                  # 本地词库与语法 JSON
│       └── base/profile/             # 页面与桌面卡片配置
├── build-profile.json5               # 产品、SDK、签名配置
└── hvigorfile.ts

签名密码不要进入仓库或文章

build-profile.json5 可能包含证书路径、密钥别名和加密后的密码字段。截图、博客和公开仓库中都应替换为占位符；团队项目应通过本地配置或 CI 密钥管理注入。

03 / ARCHITECTURE

业务架构怎么拆：页面不直接承担全部状态

这类学习应用最容易出现的问题是：首页显示一份进度，背词页又维护一份进度，退出后两边不同步。实际工程将数据加载、学习状态、发音与系统卡片分别收口到服务层。

表现层ArkUI 页面、可复用组件、Router 路由、响应式状态

业务层StudyService、DataLoader、PronunciationService、LockScreenWordService

数据层Preferences 持久化、RawFile 本地 JSON、学习与错题记录

系统层UIAbility、FormExtensionAbility、TTS、LiveView、BackupAbility

状态刷新要设计成事件，而不是“希望页面重建”

学习完成、切换词库或调整每日计划后，服务层更新 Preferences，并通过 AppStorage 写入新的数据版本。主页面监听版本变化，将刷新令牌传给首页。这样从子页面返回后，词库名称、已学数量、复习数量和学习位置会重新读取，而不是继续展示上一次进入时的旧状态。

// StudyService 保存时发出全局数据变化信号
AppStorage.setOrCreate('studyDataVersion', Date.now());

// MainPage 监听后更新首页 refreshToken
@StorageLink('studyDataVersion')
@Watch('onStudyDataVersionChange')
studyDataVersion: number = 0;

// HomePage 读取最新服务状态
@Prop @Watch('onRefreshTokenChange')
refreshToken: number = 0;

为什么不用组件的 .key() 强制刷新？

在当前 ArkUI 工具链中，部分 key 用法只用于测试目录，不能把它当成可靠的业务刷新机制。明确的状态输入与 @Watch 更可控，也更容易定位刷新链路。

04 / PRODUCT LOOP

把学习闭环做完整：正确、错误和“不熟悉”必须有区别

1. 选词库独立记录每本词书的进度，可随时切换。

2. 学新词四选一或思考翻卡，支持顺序与乱序。

3. 记录反馈正确、错误、不熟悉进入不同状态。

4. 智能复习错词和薄弱词按间隔策略再次出现。

5. 巩固统计默写、语法、错题本和周统计闭环。

随机复习和智能复习不应共用同一逻辑。随机复习用于抽查当前词库的已学内容；智能复习则由错误记录、熟悉度和到期时间驱动。两套队列分开后，用户能清楚理解“为什么这个词又出现了”。

听音默写从已学单词中随机抽取，本轮不重复，答题结果进入历史记录。

语法练习提交后显示正确答案和解析，错误题目统一进入错题体系。默写历史保留播报词、用户输入、释义和正确性，便于针对性回看。默写、错题本、语法与关于页面集中到工具入口，主学习流程保持安静。

桌面卡片与锁屏实况窗

桌面卡片采用 FormExtensionAbility，表单规格从窄版调整为 2*4，把单词、音标与释义分区展示，并支持 Swiper 左右切词。锁屏使用 liveViewLockScreen 扩展，跟随当前选择词库生成词组。

系统扩展“写了代码”不等于“系统一定展示”

锁屏实况窗还受系统开关和签名权益控制。普通 debug 包即便注册了扩展，也可能返回 1003500005。这类权益必须在华为开发者后台申请，并进入发布 Profile，不能靠代码绕过。

05 / CLI BUILD

DevEcoCLI 构建实战：让构建离开 IDE 也能运行

DevEco Studio 底层仍由 Hvigor 驱动。把 GUI 中的 Build 操作转换成命令后，才能稳定复现、接入脚本并快速定位“编译失败还是签名失败”。以下命令来自 Windows 实际工程。

1. 确认设备与工具

hdc list targets

# 工程根目录查看 Hvigor 任务
hvigorw --help

2. 构建真机调试 HAP

签名工具对 JDK 版本敏感。项目实际遇到过系统旧 Java 解析密钥库失败，因此同时设置 JAVA_HOME 和 Path，确保签名进程也使用 DevEco Studio 自带 JBR。

# PowerShell
$env:JAVA_HOME = "D:\Program Files\Huawei\DevEco Studio\jbr"
$env:Path = "$env:JAVA_HOME\bin;" + $env:Path

& "D:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat" `
  --mode module `
  -p module=entry@default `
  -p product=default `
  -p buildMode=debug `
  assembleHap `
  --no-daemon

成功后会得到：

entry/build/default/outputs/default/entry-default-signed.hap

3. 构建应用市场 APP 包

& "D:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat" `
  --mode project `
  -p product=default `
  -p buildMode=release `
  assembleApp `
  --no-daemon

当前工程已经生成过实际 APP 产物：

build/outputs/default/jiaoju-default-signed.app

产物	用途	是否直接提交市场
signed.hap	模块包，适合真机安装和模块级验证	通常否
signed.app	应用级 App Pack，包含模块与发布签名	是，以控制台要求为准
app-symbol.zip	符号文件，用于崩溃堆栈还原	建议同步保存或上传

06 / DEVICE

真机安装与排错：先保留数据，再判断失败阶段

覆盖安装时使用 -r 保留 Preferences 中的学习记录。应用启动后再用进程号筛选 hilog，能快速确认问题发生在应用代码还是系统服务。

# 覆盖安装并保留数据
hdc app install -r entry\build\default\outputs\default\entry-default-signed.hap

# 启动入口 Ability
hdc shell aa start -a EntryAbility -b com.qxf.jiaoju

# 获取进程并读取应用日志
hdc shell pidof com.qxf.jiaoju
hdc shell hilog -x -P <PID>

真实错误 1：签名阶段 11014003

报错包含 Init keystore failed、parseAlgParameters failed 时，不要先怀疑业务代码。实际原因是签名工具使用了不兼容的旧 JDK。把 DevEco 自带 JBR 21 放到 Path 首位后，CompileArkTS、PackageHap 和 SignHap 全部通过。

真实错误 2：安装阶段 9568322

signature verification failed due to not trusted app source 常见于开发者模式、USB 调试安装授权或设备锁屏状态变化。先解锁设备、确认调试授权，不要为了重装直接卸载应用，否则用户的本地学习进度可能一起丢失。

排错顺序

先看 Hvigor 最后失败的任务，再看 HAP/APP 是否生成，最后看 hdc 安装返回码。编译、签名、安装和运行是四个独立阶段，不要混为一个“构建失败”。

07 / APPGALLERY

签名与应用市场上架：代码完成只是发布的一半

发布前在 AppGallery Connect 创建应用，包名必须与工程完全一致。随后配置发布证书与 Profile，用 release 模式生成 signed APP 包。debug Profile 只用于开发验证，不能替代正式分发权益。

应用市场素材准备

素材	本项目做法
应用名称	英语学习手册
一句话简介	背单词、学语法、练听写，支持四六级考研词库与智能复习
搜索词布局	背单词、英语词汇、四六级单词、考研英语、英语语法、单词听写、智能复习
截图	首页、词库、背词、默写、语法、统计，全部使用真实设备界面
隐私说明	明确说明本地学习数据、网络权限用途，以及是否采集个人信息
版本说明	写用户可感知的功能变化，不罗列内部重构

发布描述要与实际能力一致

例如锁屏实况窗需要额外权益，在权益正式开通前不应把它作为已上线卖点。语法题如果是“考试风格练习”，也不要写成未经授权的“官方真题”。审核文案、页面截图和安装后的实际功能必须一致。

市场截图聚焦一个卖点，保持真实界面可辨识，不用与产品无关的装饰图替代。

数据页适合表现持续学习价值，同时避免展示虚构成绩或不可验证承诺。

应用上架后仍要保留每次提交的 signed APP、符号文件、发布 Profile、审核文案和截图版本，出现崩溃或回滚时才有可追踪的发布基线。

08 / LESSONS

真实迭代复盘：用户说“不好用”，通常是状态与策略问题

最初版本“能背词”，但用户很快指出：正确和错误没有差异、不会再次安排复习、不能乱序、每日计划不可调、退出后首页仍显示旧进度、音标位置甚至显示原单词。这些反馈都不是简单换颜色能解决的。

用户反馈	工程修正
答对答错没有区别	记录答题结果与熟悉度，驱动不同复习间隔
不会再次复习	错误和“不熟悉”进入智能复习队列
只能一种背法	增加顺序/乱序、选择题/思考翻卡设置
计划按钮没反应	本地 State 先即时更新，再异步持久化
返回首页还是旧数据	AppStorage 数据版本 + refreshToken 明确刷新链路
音标展示错误	补充词库音标数据，并过滤“音标等于原单词”的脏数据
桌面卡片太窄	规格调整为 2*4，长单词按长度自适应字号
锁屏没有卡片	实现 LiveView 扩展，同时在 UI 中展示系统权限或权益错误码