🚀 Flutter + OpenHarmony 发布与分发全流程：从构建到上架 AppGallery 的实战指南

推荐作者：晚霞的不甘
日期：2025年12月5日
标签：Flutter · OpenHarmony · 应用发布 · HAP 构建 · AppGallery · 签名 · 分阶段发布 · 鸿蒙生态

---

引言：上线，是产品价值的起点

开发完成只是第一步。
真正的挑战在于：

• 如何生成符合 OpenHarmony 规范的 HAP 包？
• 如何通过 安全签名 与 合规审核？
• 如何在 AppGallery 上精准触达目标用户？
• 如何实现 灰度发布 与 快速回滚？

本文将带你走通 Flutter + OpenHarmony 应用从本地代码到全球上架 的完整流程，涵盖构建、签名、测试、提审、发布五大环节，助你高效、合规、安全地交付应用。

---

一、构建准备：环境与配置检查

1.1 必备工具链

工具	版本要求	用途
DevEco Studio	≥ 5.0	HAP 打包、签名、调试
Flutter SDK	≥ 3.24 (OH 支持版)	Dart 编译、插件管理
HDC	最新版	设备连接、日志抓取
Node.js	≥ 18	构建脚本依赖

✅ 验证命令：

flutter doctor -v
hdc version

1.2 项目配置关键项

pubspec.yaml

name: smart_travel_app
version: 1.2.0+12  # 语义化版本：major.minor.patch+build

module.json5（OpenHarmony 模块配置）

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet", "car", "wearable"],
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }
    ],
    "metadata": [
      { "name": "flutter_native_splash", "resource": "$media:splash" }
    ]
  }
}

⚠️ 注意：

• versionCode（整数）用于升级判断，versionName（字符串）用于展示
• 多设备类型需明确声明，否则无法在对应设备上架

---

二、构建 HAP：生成可分发包

2.1 构建模式选择

模式	命令	用途
Debug	flutter run	开发调试
Profile	flutter build ohos --profile	性能分析
Release	flutter build ohos --release	正式发布

2.2 执行 Release 构建

# 在项目根目录执行
flutter build ohos --release --target-platform=ohos-arm64

📁 输出路径：
build/ohos/release/outputs/default/entry-default-signed.hap

2.3 多 HAP 支持（按需分发）

若应用包含多个功能模块（如车机专属 HAP）：

flutter build ohos --release --flavor car

→ 生成 entry-car-signed.hap

---

三、应用签名：安全分发的前提

OpenHarmony 要求所有 HAP 必须使用正式证书签名。

3.1 证书类型

类型	适用场景	有效期
调试证书	开发测试	365 天（自动生成）
正式证书	AppGallery 上架	10 年（需申请）

3.2 申请正式证书（华为开发者联盟）

1. 登录 AppGallery Connect
2. 进入 “我的项目” → “应用” → “应用信息” → “证书管理”
3. 创建 “发布证书”（系统生成 CSR 并下载 .p12 和 .cer 文件）

3.3 配置签名文件

将证书放入项目：

android/
└── app/
    └── src/
        └── main/
            └── resources/
                └── raw/
                    ├── release.p12
                    └── agconnect-services.json

在 build-profile.json5 中指定：

{
  "app": {
    "signingConfigs": [{
      "name": "release",
      "type": "harmonyos",
      "material": {
        "certpath": "src/main/resources/raw/release.cer",
        "keyAlias": "my_key",
        "keyPassword": "******",
        "profile": "src/main/resources/raw/release.p7b"
      }
    }]
  }
}

🔐 安全提示：

• 证书密码勿提交至 Git
• 使用 CI 环境变量注入敏感信息

---

四、预发布测试：确保上线质量

4.1 内部测试（Internal Testing）

• 上传 HAP 至 AppGallery Connect → “版本管理” → “内部测试”
• 添加测试人员邮箱（需注册华为账号）
• 测试人员通过 “Beta Feedback” App 安装体验

4.2 公开测试（Open Testing）

• 面向更广用户群（最多 10,000 人）
• 需提交隐私政策与数据收集说明
• 可收集崩溃日志与用户反馈

4.3 自动化回归验证

在 CI 中集成：

# 安装到真机并启动
hdc install entry-default-signed.hap
hdc shell aa start -b com.example.smarttravel
# 验证首页是否正常渲染（通过截图比对）

---

五、提审与合规：通过 AppGallery 审核

5.1 审核核心要求（2025 最新）

类别	要求
功能	无崩溃、无白屏、核心流程可用
权限	仅申请必要权限，提供使用说明
隐私	隐私政策链接有效，不收集非必要信息
安全	无明文存储、无未加密通信
内容	无违规、无侵权、适龄分级正确

5.2 提交材料清单

• 应用图标（192×192 PNG）
• 应用截图（每设备类型至少 2 张）
• 隐私政策 URL（必须 HTTPS）
• 功能描述（含分布式场景说明）
• 敏感权限使用说明（如“位置用于导航”）

⏱️ 审核周期：通常 1–3 个工作日

---

六、分阶段发布：降低上线风险

6.1 灰度发布（Staged Rollout）

在 AppGallery Connect 中设置：

• 首批发放比例：1% → 5% → 20% → 100%
• 监控指标：崩溃率 < 0.1%，ANR < 0.05%
• 自动暂停条件：若崩溃率突增，自动停止分发

6.2 快速回滚

若发现严重问题：

1. 进入 “版本管理” → “已发布版本”
2. 点击 “紧急下架”
3. 用户将无法下载，已安装用户不受影响（除非强制更新）

---

七、发布后运营：数据驱动优化

7.1 关键指标监控

指标	工具	目标
下载量	AppGallery Connect	日环比增长 ≥ 5%
活跃用户	HMS Core Analytics	DAU ≥ 10,000
崩溃率	AppGallery Crash Report	< 0.1%
评分	用户评价	≥ 4.5 星

7.2 A/B 测试（多版本对比）

• 上传两个 HAP（如不同引导页）
• 分配 50%/50% 流量
• 对比转化率、留存率
• 保留胜出版本

---

八、常见发布问题与解决方案

问题	原因	解决方案
HAP 安装失败	签名不匹配	重新用正式证书签名
审核被拒（权限）	未说明使用场景	在提审备注中补充说明
启动黑屏	Release 模式缺少资源	检查 assets 是否加入 pubspec
多设备不显示	deviceTypes 未声明	在 module.json5 补充设备类型
更新失败	versionCode 未递增	确保每次发布 versionCode +1

---

结语：发布不是终点，而是用户旅程的开始

每一次成功上架，都是对团队努力的肯定；
每一次用户好评，都是对产品价值的认可。

📲 行动建议：

1. 今天就检查 module.json5 的设备类型声明
2. 明天申请正式签名证书
3. 下周提交首个内部测试版本

因为最好的代码，终要运行在用户的真实设备上。

---

附录：发布检查清单

✅ versionCode 已递增
✅ 正式证书已配置
✅ 隐私政策链接有效
✅ 所有设备类型截图已准备
✅ 内部测试通过
✅ 崩溃监控已接入
✅ 权限使用说明已撰写

---

上线不是冲刺的终点，而是长期价值的起点。