鸿蒙百篇系列第 74 篇 · 专家
第 20 篇讲过应用上架流程，第 37 篇讲过企业级 CI/CD。那些讲的是"怎么把应用发出去"。这篇讲的是"怎么安全地发出去"——特别是大版本、大改动时，怎么控制风险。
灰度发布不是"把版本传上去等着"。它是一套完整的版本治理策略：从版本规划、分阶段投放、数据监控、到异常回滚，每个环节都有决策点。
一、AGC 分阶段发布机制
华为 AppGallery Connect（AGC）提供两种分阶段发布方式：
7 天自动更新的阶梯
这个阶梯的节奏是固定的。覆盖范围内的用户如果开启了自动更新，会在对应天数收到更新推送。所有用户都可以在应用市场主动搜索下载。
自定义分阶段的操作
自定义分阶段需要手动控制百分比和生效周期：
登录 AGC → 选择应用 → 版本信息 → 点击"升级"
上传新版本的 App Pack
发布类型选择"分阶段发布"
设置生效时间（开始和结束）和发布百分比
提交审核
生效期间可以执行的操作：
二、版本号策略
鸿蒙应用的版本控制通过 versionCode 和 versionName 两个字段：
// app.json5
{
"app": {
"versionCode": 10003,
"versionName": "1.0.3"
}
}
versionCode 必须是整数且递增，AGC 不允许上传低于当前在架版本的 versionCode。
推荐版本号规则：
把 versionCode 设计成 主版本 × 10000 + 次版本 × 100 + 修复版本，方便从版本号反推版本类型。
三、灰度发布决策树
不是每次发版都需要灰度。决策依据是变更范围和风险等级：
变更范围大吗？（架构改动、新功能模块）
├── 是 → 需要灰度
│ 风险高吗？（涉及支付、用户数据）
│ ├── 是 → 5 阶段灰度（1% → 5% → 10% → 30% → 100%）
│ └── 否 → 3 阶段灰度（5% → 20% → 100%）
└── 否 → 不需要灰度
仅修复 Bug？
├── 是 → 直接发布或 7 天自动更新
└── 否 → 小版本，直接发布
四、灰度阶段的监控指标
灰度期间必须监控的核心指标：
灰度期间的数据对比基线是上一版本的数据。不是和"绝对正常值"比，而是和"上一版实际表现"比。因为用户群体、设备分布都不同，绝对值对比没有意义。
对比监控实现
在应用启动时上报版本信息，服务端按版本分组统计：
import { appInfo } from '@kit.BasicServicesKit';
// 上报版本信息
function reportVersionInfo() {
const version = appInfo.appVersionName;
const versionCode = appInfo.appVersionCode;
// 每次启动上报一次，服务端用于分版本统计
const report = {
version: version,
versionCode: versionCode,
timestamp: Date.now(),
deviceModel: deviceInfo.deviceType,
};
uploadToServer('/api/metrics/version', report);
}
服务端看板按 versionCode 分组，实时对比各版本的指标差异。
五、回滚策略
灰度期间发现严重问题（崩溃率超阻断阈值），需要立即回滚。
回滚操作
AGC 支持两种回滚：
方式一：暂停分阶段发布
暂停后，已安装新版本的用户不受影响，但新用户无法获取到新版本。这是最快速的操作，不需要审核。
方式二：回退到上一版本
在 AGC 版本信息页面，可以将分阶段发布版本回退到上一个全网版本。新用户会获取到旧版本。已安装新版本的用户需要等修复版本发布后再次更新。
注意：已经安装了新版本的用户无法通过 AGC 自动降级。AGC 不支持版本回退推送。所以灰度百分比不要一次给太大——1% 的一百万用户也有上万台设备。
回滚决策流程
收到告警 → 判断严重程度
├── 崩溃 > 0.5% → 立即暂停 → 紧急修复 → 重新灰度
├── 崩溃 0.3%-0.5% → 暂停 → 分析堆栈 → 决定修复 or 回滚
└── 崩溃 < 0.3% → 继续灰度，观察趋势
回滚时通知相关团队的模板：
【灰度回滚通知】
应用：xxx
版本：1.2.0 (versionCode: 10200)
回滚原因：崩溃率 0.8%，超阻断阈值
影响范围：已覆盖 5% 用户，约 xx 万设备
已采取措施：暂停分阶段发布
下一步：紧急修复版本 1.2.1，预计 xx 小时后提交
六、多设备灰度
鸿蒙应用可能同时支持手机、平板、智慧屏、手表等多种设备。不同设备的用户量和风险不同，可以分别灰度。
AGC 的分阶段发布可以按设备类型设置不同节奏：
七、灰度期间的配置降级
灰度版本发现问题但不至于回滚时，可以通过远程配置做功能降级：
// 应用启动时拉取远程配置
async function fetchRemoteConfig() {
const config = await httpClient.get('/api/config');
// 存入 AppStorage
AppStorage.setOrCreate('remoteConfig', config);
}
// 业务代码根据配置开关功能
@Entry
@Component
struct HomePage {
@StorageLink('remoteConfig') config: Record<string, boolean> = {};
build() {
Column() {
if (this.config['enable_new_feed'] === true) {
NewFeedComponent()
} else {
OldFeedComponent()
}
}
}
}
发现新功能有问题，在服务端把 enable_new_feed 设为 false，用户下次启动自动切回旧逻辑。不需要发新版本。
八、版本治理清单
发版前逐项检查：
九、小结
灰度发布的核心思路是"小步快跑，随时刹车"。1% 的时候发现问题，影响的是万分之一；50% 的时候发现问题，影响的是二分之一。越早发现问题，修复成本越低。
AGC 提供的分阶段发布是工具，怎么用它取决于你的版本风险判断。低风险版本直接上，高风险版本多阶段灰度加远程配置降级。没有标准答案，只有根据场景做的决策。
下一篇讲热修复体系——在极端情况下，怎么不发版就修复线上问题。