1. 项目背景与核心目标
这个开源教程系列已经进行到第35篇,聚焦HarmonyOS应用开发的最后关键环节——打包与发布。作为React技术栈在鸿蒙生态的实践指南,本教程特别关注如何将开发阶段的应用转化为可分发、可安装的正式产物。
当前项目基于HarmonyOS 3.0+开发环境,使用ArkTS语言配合React开发范式,已经完成了核心功能开发。现在面临的是每个开发者都会经历的"临门一脚"问题:如何让代码变成用户手机上的应用?这涉及到几个关键维度:
- 构建配置:理解build-profile.json5如何定义构建行为
- 模块声明:掌握module.json5对应用身份的界定
- 资源管理:处理rawfile等资源的打包优化
- 签名体系:配置可发布的签名方案
- 质量检查:构建警告与运行时验证
特别提示:很多开发者容易陷入"能跑就行"的思维,但发布质量直接关系到应用商店审核通过率、用户安装成功率和后续OTA更新可靠性。这个阶段投入的优化时间,往往能节省后期数倍的维护成本。
2. 构建配置深度解析
2.1 build-profile.json5的核心作用
这个文件相当于鸿蒙应用的构建蓝图,当前项目中的配置已经包含发布所需的关键元素:
json复制{
"signingConfigs": [{
"name": "default",
"storeFile": "myreleasekey.jks",
"keyAlias": "alias_name",
"storePassword": "password",
"keyPassword": "password",
"profile": "myprofile.p7b",
"certpath": "mycertificate.cer"
}],
"products": [{
"name": "default",
"signingConfig": "default",
"targetSdkVersion": "6.0.0(20)",
"compatibleSdkVersion": "6.0.0(20)",
"runtimeOS": "HarmonyOS"
}]
}
签名配置的注意事项:
- storeFile建议使用相对路径(如"signing/release.jks")
- 密码字段在实际项目中应该通过环境变量注入
- profile文件需要与鸿蒙开发者账户关联
2.2 构建模式与变体管理
buildModeSet定义了构建的维度组合,常见配置包括:
json复制"buildModeSet": {
"release": {
"isDebuggable": false,
"signingConfig": "default"
},
"debug": {
"isDebuggable": true
}
}
实际开发中,建议增加staging模式用于预发布验证:
json复制"staging": {
"isDebuggable": true,
"signingConfig": "default",
"resValue": {
"env": "staging"
}
}
3. 模块配置与页面路由
3.1 module.json5的身份证作用
entry/src/main/module.json5定义了应用模块的元信息:
json复制{
"module": {
"name": "entry",
"type": "entry",
"mainElement": "EntryAbility",
"deviceTypes": ["phone"],
"pages": "$profile:main_pages"
}
}
关键字段解析:
type: "entry"表示这是可独立运行的入口模块deviceTypes需要与manifest.json中的设备类型一致pages指向的注册文件必须真实存在
3.2 页面注册的隐藏陷阱
main_pages.json示例:
json复制{
"src": [
"pages/Index",
"pages/Course/CourseList",
"pages/Project/Detail"
]
}
常见问题包括:
- 新增页面后忘记注册
- 路径大小写不匹配(Linux环境敏感)
- 嵌套路由未完整声明
建议在build.gradle中添加校验脚本:
groovy复制task validatePages {
doLast {
def pages = file("src/main/resources/base/profile/main_pages.json")
def declared = new groovy.json.JsonSlurper().parseText(pages.text)
declared.src.each { page ->
if (!file("src/main/ets/${page}.ets").exists()) {
throw new GradleException("Page ${page} declared but missing!")
}
}
}
}
4. 构建流程与优化实践
4.1 assembleHap的完整生命周期
执行hvigor assembleHap时发生的完整流程:
-
环境检查
- Node.js版本
- DevEco Studio插件
- SDK工具链
-
配置加载
- 合并build-profile.json5和全局配置
- 解析模块依赖图
-
编译阶段
- ArkTS转译
- 资源压缩(WebP转换)
- 字节码生成
-
打包阶段
- HAP结构组装
- 资源索引生成
- Manifest合并
-
签名阶段
- 选择签名配置
- V1/V2签名
- 签名验证
4.2 构建警告处理实战
典型警告案例与解决方案:
| 警告类型 | 示例 | 修复方案 |
|---|---|---|
| 过时API | pushUrl is deprecated |
改用router.pushUrl |
| 资源冗余 | Unexpected source code in rawfile |
配置exclude规则 |
| 权限声明 | Permission not declared |
更新module.json5 |
| 尺寸超标 | HAP exceeds 10MB |
启用多HAP拆分 |
针对rawfile的优化配置示例:
json复制// build-profile.json5
"buildOption": {
"resourceFilter": {
"exclude": ["**/*.java", "**/*.kt", "**/README.md"]
}
}
5. 发布准备清单
5.1 必须检查的12个事项
- [ ] 签名证书有效期(至少剩余6个月)
- [ ] 应用图标各分辨率齐备
- [ ] 隐私政策链接可访问
- [ ] 权限使用说明完整
- [ ] 多语言资源完整
- [ ] 启动页加载时间<1.5s
- [ ] 回退路由配置正确
- [ ] 无调试日志残留
- [ ] 敏感信息已混淆
- [ ] 三方库License声明
- [ ] 无障碍功能测试
- [ ] 黑暗模式适配
5.2 自动化验证方案
推荐集成以下CI流水线检查:
yaml复制# .github/workflows/release-check.yml
steps:
- name: Build Verification
run: hvigor assembleHap --mode release
- name: Size Check
run: |
hap_size=$(stat -c%s build/outputs/hap/release/entry-release.hap)
if [ $hap_size -gt 10000000 ]; then
echo "HAP size exceeds 10MB!"
exit 1
fi
- name: Page Test
uses: cypress-io/github-action@v4
with:
config-file: cypress.config.ts
6. 高级发布策略
6.1 多HAP分发方案
对于大型应用,建议采用动态特性分发:
json复制// feature1/build-profile.json5
{
"module": {
"name": "feature1",
"type": "feature",
"deliveryWithInstall": false
}
}
安装后动态加载示例:
typescript复制import featureAbility from '@ohos.ability.featureAbility';
featureAbility.installFeature(
{ bundleName: 'com.example.app', moduleName: 'feature1' },
(err) => {
if (err) {
console.error('Install failed:', err);
} else {
console.log('Feature installed');
}
}
);
6.2 资源热更新方案
通过rawfile管理可更新资源:
- 配置资源索引:
json复制// resources/base/rawfile/version.json
{
"assets": {
"course_1.zip": "v2.1.0",
"config.json": "v1.0.0"
}
}
- 实现差分更新逻辑:
typescript复制async function checkUpdate() {
const localVer = await getLocalVersion();
const remoteVer = await fetchRemoteVersion();
if (remoteVer.assets.course_1.zip !== localVer.assets.course_1.zip) {
const patch = await downloadPatch('course_1.zip');
await applyPatch(patch);
}
}
7. 疑难问题排查指南
7.1 常见构建错误代码
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 1001 | 签名配置无效 | 检查storePassword和keyPassword匹配 |
| 2003 | 资源冲突 | 检查重复的resource/文件名 |
| 3008 | API级别不兼容 | 调整compatibleSdkVersion |
| 4012 | 权限未声明 | 在module.json5中添加requiredPermissions |
7.2 真机调试技巧
当发布版本在真机出现问题时:
- 获取详细日志:
bash复制hdc shell hilog -w > device.log
- 检查签名指纹:
bash复制keytool -list -v -keystore myreleasekey.jks
- 验证HAP完整性:
bash复制unzip -t entry-release.hap
8. 工程化建议
8.1 环境变量管理
推荐采用dotenv方案管理敏感配置:
- 安装依赖:
bash复制npm install @ohos/node-dotenv
- 创建.env文件:
ini复制SIGNING_STORE_PASSWORD=your_password
KEY_ALIAS=release_key
- 在build-profile.json5中引用:
json复制"storePassword": "${env:SIGNING_STORE_PASSWORD}",
"keyAlias": "${env:KEY_ALIAS}"
8.2 代码混淆配置
在build-profile.json5中启用:
json复制"buildOption": {
"proguard": {
"enabled": true,
"rules": "proguard-rules.pro"
}
}
示例混淆规则:
code复制-keep class com.example.** { *; }
-keepattributes SourceFile,LineNumberTable
9. 性能优化指标
发布前必测的性能基线:
| 指标 | 合格线 | 测量工具 |
|---|---|---|
| 冷启动时间 | <800ms | HiTrace |
| 内存峰值 | <150MB | hdc shell top |
| HAP大小 | <10MB | ls -lh |
| 帧率稳定性 | >55fps | DevEco Profiler |
| 电量消耗 | <3%/h | Battery Historian |
采集示例代码:
typescript复制import hiTraceMeter from '@ohos.hiTraceMeter';
hiTraceMeter.startTrace('cold_start', 1000);
// 启动逻辑...
hiTraceMeter.finishTrace('cold_start');
10. 持续交付实践
10.1 自动化发布流水线
推荐GitHub Actions配置:
yaml复制name: Publish Pipeline
on:
push:
tags: v*
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '16'
- name: Build HAP
run: |
npm install
hvigor assembleHap --mode release
- name: Upload to AppGallery
uses: huawei-actions/upload-appgallery@v1
with:
client_id: ${{ secrets.HUAWEI_CLIENT_ID }}
client_secret: ${{ secrets.HUAWEI_CLIENT_SECRET }}
app_id: ${{ secrets.APP_ID }}
file: build/outputs/hap/release/*.hap
10.2 版本发布策略
推荐采用语义化版本控制:
- 主版本号:架构级变更
- 次版本号:功能新增
- 修订号:问题修复
在module.json5中声明:
json复制"version": {
"code": 35,
"name": "3.2.1"
}
配套的变更日志规范:
markdown复制## [3.2.1] - 2023-08-20
### Fixed
- 修复课程列表滚动卡顿问题
- 解决深色模式图标显示异常
### Changed
- 优化打包脚本执行效率
通过这套完整的发布体系,开发者可以确保React技术栈开发的HarmonyOS应用能够以最佳状态交付给最终用户。记住,优秀的发布质量是用户体验的第一道门槛,也是技术专业性的直接体现。
