HarmonyOS开发：版本发布管理

核心要点：版本发布不是点个按钮就完事，从发布策略选择到灰度控制，从回退预案到发布监控，每一步都关乎用户体验。一次失败的发布，可能让你一夜回到解放前。

背景与动机

你有没有经历过这种场景？

凌晨三点发布新版本，结果启动率直接跌了30%。用户反馈打开就闪退，应用商店差评如潮。你赶紧回退版本，但回退操作搞了两个小时，期间新用户还在下载有问题的版本……

这就是没有版本发布管理的后果。

版本发布是个系统工程。不是代码写完了扔上去就行，你得考虑：用全量发布还是灰度发布？灰度比例怎么定？出问题了怎么回退？回退期间新用户怎么办？发布后怎么监控？

这些问题不想清楚，出事是迟早的。

这篇文章，把版本发布的完整流程、全量与灰度的选择策略、回退方案、发布监控全部讲清楚。

核心原理

版本发布完整流程

graph TD
    A[开发完成] --> B[内部测试]
    B --> C{测试通过?}
    C -->|否| A
    C -->|是| D[确定发布策略]
    D --> E{发布类型}
    E -->|全量发布| F[提交审核]
    E -->|灰度发布| G[配置灰度规则]
    G --> H[提交审核]
    H --> I{审核通过?}
    I -->|否| J[修改后重新提交]
    J --> H
    I -->|是| K[发布上线]
    K --> L[发布监控]
    L --> M{监控正常?}
    M -->|是| N[灰度扩大/全量发布]
    M -->|否| O[紧急回退]
    O --> P[定位问题]
    P --> A

    classDef startStyle fill:#FF6B35,stroke:#D4551F,color:#fff,font-weight:bold
    classDef processStyle fill:#4ECDC4,stroke:#3BA99C,color:#fff
    classDef decisionStyle fill:#FFE66D,stroke:#D4B93C,color:#333,font-weight:bold
    classDef dangerStyle fill:#FF6B6B,stroke:#CC5555,color:#fff
    classDef successStyle fill:#96CEB4,stroke:#6DAF8E,color:#fff,font-weight:bold
    
    class A startStyle
    class B,D,F,G,H,K,L,N processStyle
    class C,E,I,M decisionStyle
    class O,P dangerStyle
    class J successStyle

全量发布 vs 灰度发布

简单判断标准：改了一行文案？全量发布。重构了核心模块？灰度发布。拿不准？灰度发布。

版本号管理规范

版本号不是随便写的，它直接影响更新机制。

版本名（versionName）: x.y.z
  x: 主版本号——大重构、不兼容更新时递增
  y: 次版本号——新增功能时递增
  z: 修订号——Bug修复时递增

版本号（versionCode）: 整数，每次发布必须递增

关键规则：versionCode必须严格递增。1→2→3，不能跳，不能回退。AppGallery用versionCode判断版本新旧，搞乱了更新机制就废了。

代码实战

基础用法：版本信息管理

// entry/src/main/ets/utils/VersionManager.ets
// 版本信息管理工具——统一管理版本号、版本名、更新逻辑

import { hilog } from '@kit.PerformanceAnalysisKit';
import { bundleManager } from '@kit.AbilityKit';

// 版本信息
interface VersionInfo {
  versionName: string;   // 版本名，如"1.2.3"
  versionCode: number;   // 版本号，如123
  buildTime: string;     // 构建时间
  changeLog: string;     // 更新日志
  isForceUpdate: boolean; // 是否强制更新
  minSupportVersion: number; // 最低支持版本号
}

export class VersionManager {
  private static instance: VersionManager;
  private currentVersion: VersionInfo | null = null;

  static getInstance(): VersionManager {
    if (!VersionManager.instance) {
      VersionManager.instance = new VersionManager();
    }
    return VersionManager.instance;
  }

  // 获取当前应用版本信息
  async getCurrentVersion(): Promise<VersionInfo> {
    if (this.currentVersion) {
      return this.currentVersion;
    }

    try {
      const bundleInfo = await bundleManager.getBundleInfoForSelf(
        bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT
      );
      
      this.currentVersion = {
        versionName: bundleInfo.versionName,
        versionCode: bundleInfo.versionCode,
        buildTime: this.getBuildTime(),
        changeLog: '',
        isForceUpdate: false,
        minSupportVersion: 1
      };

      hilog.info(0x0000, 'Version', 
        `当前版本: ${this.currentVersion.versionName}(${this.currentVersion.versionCode})`);
      
      return this.currentVersion;
    } catch (error) {
      hilog.error(0x0000, 'Version', `获取版本信息失败: ${JSON.stringify(error)}`);
      return {
        versionName: '0.0.0',
        versionCode: 0,
        buildTime: '',
        changeLog: '',
        isForceUpdate: false,
        minSupportVersion: 0
      };
    }
  }

  // 比较版本号大小
  compareVersions(v1: string, v2: string): number {
    const parts1 = v1.split('.').map(Number);
    const parts2 = v2.split('.').map(Number);
    
    for (let i = 0; i < 3; i++) {
      const num1 = parts1[i] || 0;
      const num2 = parts2[i] || 0;
      if (num1 > num2) return 1;
      if (num1 < num2) return -1;
    }
    return 0;
  }

  // 判断是否需要更新
  async checkNeedUpdate(remoteVersion: VersionInfo): Promise<{
    needUpdate: boolean;
    isForce: boolean;
  }> {
    const current = await this.getCurrentVersion();
    
    // 版本号比较
    const needUpdate = remoteVersion.versionCode > current.versionCode;
    
    // 判断是否强制更新（当前版本低于最低支持版本）
    const isForce = current.versionCode < remoteVersion.minSupportVersion;
    
    return { needUpdate, isForce };
  }

  // 获取构建时间（从应用信息中读取）
  private getBuildTime(): string {
    // 实际项目中可以在构建时写入
    return new Date().toISOString();
  }
}

进阶用法：发布策略配置

// entry/src/main/ets/utils/PublishStrategy.ets
// 发布策略管理——根据版本类型自动选择发布方式

import { hilog } from '@kit.PerformanceAnalysisKit';

// 版本变更类型
enum ChangeType {
  HOTFIX = 'hotfix',       // 紧急修复
  BUGFIX = 'bugfix',       // Bug修复
  FEATURE = 'feature',     // 新功能
  REFACTOR = 'refactor',   // 重构
  MAJOR = 'major'          // 大版本
}

// 发布策略
interface PublishStrategy {
  type: 'full' | 'gray';   // 全量或灰度
  grayPercentage: number;   // 灰度比例（0-100）
  grayDuration: number;     // 灰度观察时长（小时）
  graySteps: number[];      // 灰度步骤
  rollbackEnabled: boolean; // 是否启用自动回退
  rollbackThreshold: number; // 回退阈值（崩溃率百分比）
  monitorDuration: number;  // 监控时长（小时）
}

// 版本发布配置
interface ReleaseConfig {
  versionName: string;
  versionCode: number;
  changeType: ChangeType;
  changeLog: string;
  affectedModules: string[];  // 影响的模块
  riskLevel: 'low' | 'medium' | 'high'; // 风险等级
  strategy: PublishStrategy;
}

export class PublishStrategyManager {
  // 根据变更类型自动推荐发布策略
  recommendStrategy(changeType: ChangeType, riskLevel: string): PublishStrategy {
    switch (changeType) {
      case ChangeType.HOTFIX:
        // 紧急修复：全量发布，但开启自动回退
        return {
          type: 'full',
          grayPercentage: 100,
          grayDuration: 0,
          graySteps: [100],
          rollbackEnabled: true,
          rollbackThreshold: 5, // 崩溃率超5%自动回退
          monitorDuration: 4
        };

      case ChangeType.BUGFIX:
        // Bug修复：小范围灰度后全量
        return {
          type: 'gray',
          grayPercentage: 100,
          grayDuration: 12,
          graySteps: [10, 50, 100],
          rollbackEnabled: true,
          rollbackThreshold: 3,
          monitorDuration: 24
        };

      case ChangeType.FEATURE:
        // 新功能：标准灰度
        return {
          type: 'gray',
          grayPercentage: 100,
          grayDuration: 24,
          graySteps: [5, 20, 50, 100],
          rollbackEnabled: true,
          rollbackThreshold: 2,
          monitorDuration: 48
        };

      case ChangeType.REFACTOR:
        // 重构：保守灰度
        return {
          type: 'gray',
          grayPercentage: 100,
          grayDuration: 48,
          graySteps: [2, 5, 10, 30, 50, 100],
          rollbackEnabled: true,
          rollbackThreshold: 1,
          monitorDuration: 72
        };

      case ChangeType.MAJOR:
        // 大版本：极保守灰度
        return {
          type: 'gray',
          grayPercentage: 100,
          grayDuration: 72,
          graySteps: [1, 3, 5, 10, 20, 40, 70, 100],
          rollbackEnabled: true,
          rollbackThreshold: 1,
          monitorDuration: 96
        };

      default:
        return this.recommendStrategy(ChangeType.FEATURE, riskLevel);
    }
  }

  // 生成发布计划
  generateReleasePlan(config: ReleaseConfig): string {
    const strategy = config.strategy;
    let plan = `=== 版本发布计划 ===\n\n`;
    plan += `版本: ${config.versionName}(${config.versionCode})\n`;
    plan += `变更类型: ${config.changeType}\n`;
    plan += `风险等级: ${config.riskLevel}\n`;
    plan += `发布方式: ${strategy.type === 'full' ? '全量发布' : '灰度发布'}\n\n`;

    if (strategy.type === 'gray') {
      plan += `--- 灰度计划 ---\n`;
      strategy.graySteps.forEach((step, index) => {
        plan += `第${index + 1}轮: ${step}%用户, 观察${strategy.grayDuration / strategy.graySteps.length}小时\n`;
      });
      plan += `\n`;
    }

    plan += `--- 安全策略 ---\n`;
    plan += `自动回退: ${strategy.rollbackEnabled ? '开启' : '关闭'}\n`;
    plan += `回退阈值: 崩溃率>${strategy.rollbackThreshold}%\n`;
    plan += `监控时长: ${strategy.monitorDuration}小时\n`;
    plan += `\n--- 更新日志 ---\n`;
    plan += config.changeLog;

    return plan;
  }

  // 判断是否应该回退
  shouldRollback(
    crashRate: number,    // 崩溃率
    anrRate: number,      // ANR率
    negativeFeedback: number // 差评数
  ): { shouldRollback: boolean; reason: string } {
    const strategy = this.recommendStrategy(ChangeType.FEATURE, 'medium');

    if (crashRate > strategy.rollbackThreshold) {
      return {
        shouldRollback: true,
        reason: `崩溃率${crashRate.toFixed(1)}%超过阈值${strategy.rollbackThreshold}%`
      };
    }

    if (anrRate > strategy.rollbackThreshold * 2) {
      return {
        shouldRollback: true,
        reason: `ANR率${anrRate.toFixed(1)}%超过阈值${strategy.rollbackThreshold * 2}%`
      };
    }

    if (negativeFeedback > 50) {
      return {
        shouldRollback: true,
        reason: `差评数${negativeFeedback}超过阈值50`
      };
    }

    return { shouldRollback: false, reason: '' };
  }
}

完整示例：发布监控与自动回退

// entry/src/main/ets/utils/ReleaseMonitor.ets
// 发布监控与自动回退——发布后的安全网

import { hilog } from '@kit.PerformanceAnalysisKit';
import { preferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

// 监控数据
interface MonitorData {
  timestamp: number;
  crashCount: number;       // 崩溃次数
  launchCount: number;      // 启动次数
  anrCount: number;         // ANR次数
  activeUsers: number;      // 活跃用户数
  negativeFeedback: number;  // 差评数
}

// 回退决策
interface RollbackDecision {
  shouldRollback: boolean;
  severity: 'none' | 'low' | 'medium' | 'high' | 'critical';
  reason: string;
  affectedUsers: number;
  recommendedAction: string;
}

// 监控告警
interface MonitorAlert {
  type: 'crash' | 'anr' | 'feedback' | 'launch_rate';
  message: string;
  timestamp: number;
  data: MonitorData;
}

export class ReleaseMonitor {
  private static instance: ReleaseMonitor;
  private context: common.Context | null = null;
  private monitorData: MonitorData[] = [];
  private alerts: MonitorAlert[] = [];
  private isMonitoring: boolean = false;

  // 告警阈值
  private thresholds = {
    crashRate: 2,          // 崩溃率阈值（百分比）
    anrRate: 4,            // ANR率阈值
    negativeFeedback: 30,  // 差评数阈值
    launchRateDrop: 20     // 启动率下降阈值（百分比）
  };

  static getInstance(): ReleaseMonitor {
    if (!ReleaseMonitor.instance) {
      ReleaseMonitor.instance = new ReleaseMonitor();
    }
    return ReleaseMonitor.instance;
  }

  // 初始化监控
  init(context: common.Context): void {
    this.context = context;
    this.loadThresholds();
    hilog.info(0x0000, 'ReleaseMonitor', '发布监控初始化完成');
  }

  // 上报监控数据
  reportData(data: MonitorData): void {
    this.monitorData.push(data);
    
    // 只保留最近100条数据
    if (this.monitorData.length > 100) {
      this.monitorData.shift();
    }

    // 检查是否触发告警
    this.checkAlerts(data);
  }

  // 计算崩溃率
  calculateCrashRate(): number {
    if (this.monitorData.length === 0) return 0;
    
    const latest = this.monitorData[this.monitorData.length - 1];
    if (latest.launchCount === 0) return 0;
    
    return (latest.crashCount / latest.launchCount) * 100;
  }

  // 计算ANR率
  calculateAnrRate(): number {
    if (this.monitorData.length === 0) return 0;
    
    const latest = this.monitorData[this.monitorData.length - 1];
    if (latest.launchCount === 0) return 0;
    
    return (latest.anrCount / latest.launchCount) * 100;
  }

  // 检查告警
  private checkAlerts(data: MonitorData): void {
    const crashRate = data.launchCount > 0 
      ? (data.crashCount / data.launchCount) * 100 : 0;
    const anrRate = data.launchCount > 0 
      ? (data.anrCount / data.launchCount) * 100 : 0;

    // 崩溃率告警
    if (crashRate > this.thresholds.crashRate) {
      const alert: MonitorAlert = {
        type: 'crash',
        message: `崩溃率${crashRate.toFixed(1)}%超过阈值${this.thresholds.crashRate}%`,
        timestamp: Date.now(),
        data: data
      };
      this.alerts.push(alert);
      hilog.error(0x0000, 'ReleaseMonitor', alert.message);
    }

    // ANR率告警
    if (anrRate > this.thresholds.anrRate) {
      const alert: MonitorAlert = {
        type: 'anr',
        message: `ANR率${anrRate.toFixed(1)}%超过阈值${this.thresholds.anrRate}%`,
        timestamp: Date.now(),
        data: data
      };
      this.alerts.push(alert);
      hilog.error(0x0000, 'ReleaseMonitor', alert.message);
    }

    // 差评数告警
    if (data.negativeFeedback > this.thresholds.negativeFeedback) {
      const alert: MonitorAlert = {
        type: 'feedback',
        message: `差评数${data.negativeFeedback}超过阈值${this.thresholds.negativeFeedback}`,
        timestamp: Date.now(),
        data: data
      };
      this.alerts.push(alert);
      hilog.warn(0x0000, 'ReleaseMonitor', alert.message);
    }
  }

  // 生成回退决策
  makeRollbackDecision(): RollbackDecision {
    if (this.monitorData.length === 0) {
      return {
        shouldRollback: false,
        severity: 'none',
        reason: '无监控数据',
        affectedUsers: 0,
        recommendedAction: '继续观察'
      };
    }

    const latest = this.monitorData[this.monitorData.length - 1];
    const crashRate = this.calculateCrashRate();
    const anrRate = this.calculateAnrRate();

    // 严重程度判断
    if (crashRate > 10 || anrRate > 20) {
      return {
        shouldRollback: true,
        severity: 'critical',
        reason: `崩溃率${crashRate.toFixed(1)}%或ANR率${anrRate.toFixed(1)}%严重超标`,
        affectedUsers: latest.activeUsers,
        recommendedAction: '立即回退，全量恢复旧版本'
      };
    }

    if (crashRate > 5 || anrRate > 10) {
      return {
        shouldRollback: true,
        severity: 'high',
        reason: `崩溃率${crashRate.toFixed(1)}%或ANR率${anrRate.toFixed(1)}%偏高`,
        affectedUsers: latest.activeUsers,
        recommendedAction: '尽快回退，停止灰度扩大'
      };
    }

    if (crashRate > this.thresholds.crashRate || anrRate > this.thresholds.anrRate) {
      return {
        shouldRollback: false,
        severity: 'medium',
        reason: `崩溃率或ANR率略高于阈值，需要持续观察`,
        affectedUsers: latest.activeUsers,
        recommendedAction: '暂停灰度扩大，持续监控24小时'
      };
    }

    if (latest.negativeFeedback > this.thresholds.negativeFeedback) {
      return {
        shouldRollback: false,
        severity: 'low',
        reason: `差评数偏多，需要关注用户反馈`,
        affectedUsers: latest.activeUsers,
        recommendedAction: '分析差评原因，评估是否需要修复'
      };
    }

    return {
      shouldRollback: false,
      severity: 'none',
      reason: '各项指标正常',
      affectedUsers: latest.activeUsers,
      recommendedAction: '继续灰度或全量发布'
    };
  }

  // 生成监控报告
  generateReport(): string {
    const decision = this.makeRollbackDecision();
    const crashRate = this.calculateCrashRate();
    const anrRate = this.calculateAnrRate();

    let report = `=== 发布监控报告 ===\n\n`;
    report += `数据点数: ${this.monitorData.length}\n`;
    report += `告警数: ${this.alerts.length}\n`;
    report += `崩溃率: ${crashRate.toFixed(2)}%\n`;
    report += `ANR率: ${anrRate.toFixed(2)}%\n\n`;
    report += `--- 回退决策 ---\n`;
    report += `是否回退: ${decision.shouldRollback ? '是' : '否'}\n`;
    report += `严重程度: ${decision.severity}\n`;
    report += `原因: ${decision.reason}\n`;
    report += `影响用户: ${decision.affectedUsers}\n`;
    report += `建议操作: ${decision.recommendedAction}\n`;

    if (this.alerts.length > 0) {
      report += `\n--- 最近告警 ---\n`;
      this.alerts.slice(-5).forEach(alert => {
        const time = new Date(alert.timestamp).toLocaleString();
        report += `[${time}] ${alert.type}: ${alert.message}\n`;
      });
    }

    return report;
  }

  // 加载告警阈值（可以从远程配置获取）
  private async loadThresholds(): Promise<void> {
    if (!this.context) return;
    
    try {
      const pref = await preferences.getPreferences(this.context, 'monitor_config');
      this.thresholds.crashRate = (await pref.get('crash_rate_threshold', 2)) as number;
      this.thresholds.anrRate = (await pref.get('anr_rate_threshold', 4)) as number;
      this.thresholds.negativeFeedback = (await pref.get('feedback_threshold', 30)) as number;
    } catch (error) {
      hilog.warn(0x0000, 'ReleaseMonitor', '使用默认告警阈值');
    }
  }
}

踩坑与注意事项

坑1：versionCode没有递增

新版本的versionCode必须大于旧版本。如果你不小心用了相同的versionCode，AppGallery会拒绝上传。如果你用了更小的versionCode，用户永远收不到更新提示。

正确做法：每次发布前检查versionCode，确保严格递增。建议在CI/CD流水线中自动递增。

坑2：灰度发布后忘记扩大范围

灰度发布设了5%，然后你就忘了。一周过去了，95%的用户还在用旧版本。

正确做法：灰度发布后设置日历提醒，每天检查灰度数据。确认无问题后及时扩大灰度比例。

坑3：回退操作不熟练，关键时刻手忙脚乱

出问题了需要回退，结果你在AGC控制台找了半天找不到回退按钮在哪，找到了又不确定点了会怎样。

正确做法：在发布前就演练一遍回退流程。知道回退按钮在哪、回退需要多久、回退期间新用户会下载哪个版本。

坑4：更新日志写得太随意

更新日志写了个"修复了一些bug"——用户看了不知道更新了什么，审核人员看了觉得你不认真。

正确做法：更新日志要具体、要用户能看懂。比如"修复了在折叠屏设备上页面显示异常的问题"比"修复了一些bug"好一万倍。

坑5：发布时间选择不当

周五下午5点发布——万一出问题，周末没人处理，用户要等到周一才能用上修复版本。

正确做法：选择周二到周四的上午发布。这样如果出问题，你有完整的工作日来处理。

坑6：没有发布检查清单

每次发布都是临时准备，容易遗漏关键步骤。上次忘了改版本号，这次忘了更新隐私政策，下次可能忘了配置灰度规则。

正确做法：建立发布检查清单（Checklist），每次发布前逐项确认。

HarmonyOS 6适配说明

HarmonyOS 6对版本发布做了几项调整：

1. 强制API版本校验：上传的包必须声明targetAPIVersion且不低于12。低于12的包无法上传。

2. 灰度发布增强：AGC控制台新增了按设备类型（手机/平板/折叠屏）分别设置灰度比例的功能。

3. 自动回退机制：AGC新增了基于崩溃率的自动回退功能。如果灰度版本的崩溃率超过设定阈值，系统会自动停止灰度并回退到上一版本。

4. 版本发布审批流：企业开发者可以配置多人审批流，版本发布需要至少两人确认才能生效。

// HarmonyOS 6 版本信息配置示例
// AppScope/app.json5
{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "versionCode": 1000003,    // 必须递增
    "versionName": "1.0.3",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "targetAPIVersion": 12,    // HarmonyOS 6最低要求API 12
    "minAPIVersion": 12,
    "apiReleaseType": "Release"
  }
}

5. 发布后数据看板：AGC控制台新增了发布后实时数据看板，展示新版本的启动率、崩溃率、ANR率等关键指标，无需额外集成SDK。

总结

版本发布是应用生命周期中最关键的环节之一。一次成功的发布，背后是充分的准备和完善的预案。核心记住三点：

1. 选对发布策略：大改动灰度发布，小修复全量发布，拿不准就灰度
2. 准备好回退方案：发布前演练回退流程，确保出问题时能快速恢复
3. 发布后持续监控：关注崩溃率、ANR率、用户反馈，发现问题及时处理