Flutter for OpenHarmony：cider 自动化版本管理与变更日志生成器（发布流程标准化的瑞士军刀） 深度解析与鸿蒙适配指南

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在 App 的迭代过程中，维护 pubspec.yaml 中的版本号和编写 CHANGELOG.md 是一件既繁琐又容易出错的事情。

• "这次发布是 1.0.1 还是 1.1.0？"
• "昨天的 bug fix 有没有写进变更日志？"
• "谁不小心把 build number 搞错了，导致应用商店上传失败？"

对于 OpenHarmony 应用来说，更加严格的版本管控（如 HAP 包的版本对应）使得这一环节尤为重要。

Cider 是一个专为 Dart/Flutter 项目设计的命令行工具，它可以自动化地处理版本升级、变更日志维护以及发布的检查。它就像是你的"发布管家"，确保每一次 Release 都井井有条。

一、核心功能与工作流

cider 是基于 Keep a Changelog 规范设计的。它不依赖复杂的 CI/CD 配置，仅仅作为一个本地 CLI 工具，就能极大提升效率。

1.1 核心能力

1. Version Bump : 自动修改 pubspec.yaml 中的 version 字段（支持语义化版本 SemVer）。
2. Changelog Management : 读取、添加、修改 CHANGELOG.md，自动将 "Unreleased" 部分归档为新版本。
3. Listing: 列出当前版本、未发布变更等。

1.2 工作流示意

1. cider log 2. 开发完成 Yes
   自动更新
   自动归档
2. cider release 开发者
   记录变更 (Unreleased)
   准备发布?
   cider bump
   pubspec.yaml
   CHANGELOG.md
   Git Tag / Release

二、安装与基础命令

2.1 安装

作为全局工具安装：

dart pub global activate cider

或者在项目中作为开发依赖（推荐）：

dev_dependencies:
  cider: ^0.2.10

2.2 初始化配置

在项目根目录创建 cider.yaml（可选），配置默认行为：

proj:
  # 变更日志文件的位置，默认为 CHANGELOG.md
  changelog: CHANGELOG.md 
link_template: https://github.com/your_org/your_repo/compare/%from%...%to%

2.3 常用命令实战

1. 查看版本

cider version
# 输出: 1.0.0+1

2. 添加变更日志

当你修复了一个 bug，不需要手动打开 Markdown 文件编辑，只需：

# 添加到 [Unreleased] 下的 Fixed 分类
cider log fixed "修复了鸿蒙系统下启动白屏的问题"

此时 CHANGELOG.md 会自动更新：

## [Unreleased]

### Fixed
- 修复了鸿蒙系统下启动白屏的问题

3. 发版升级 (Bump)

当积累了足够的变更，准备发布新版本时：

# 升级 patch 版本 (1.0.0 -> 1.0.1) 并更新 build number
cider bump patch --build 2

# 或者升级 minor (1.0.0 -> 1.1.0)
cider bump minor

执行该命令后：

1. pubspec.yaml 版本号更新。
2. CHANGELOG.md 中的 [Unreleased] 标题会被替换为新版本号和当前日期，并创建新的 [Unreleased] 占位符。

4. 标记发布

cider release

三、OpenHarmony 适配与实战：配合 Git 钩子管理 HAP 版本

在 OpenHarmony 项目中，Flutter 的 version (如 1.0.0+1) 最终会映射到鸿蒙 AppScope/app.json5 或 entry/src/main/module.json5 中的 versionCode 和 versionName。

虽然 cider 只修改 pubspec.yaml，但我们可以通过脚本将变动同步给鸿蒙配置。

3.1 编写同步脚本

我们在项目下创建一个 scripts/sync_version.dart：

import 'dart:io';
import 'package:yaml/yaml.dart';

void main() {
  // 1. 读取 pubspec.yaml
  final pubspecFile = File('pubspec.yaml');
  final pubspec = loadYaml(pubspecFile.readAsStringSync());
  final versionFull = pubspec['version'] as String;
  
  // 解析 1.0.0+2
  final parts = versionFull.split('+');
  final versionName = parts[0];
  final buildNumber = int.parse(parts.length > 1 ? parts[1] : '1');

  // 2. 更新鸿蒙 app.json5
  final ohosAppJson = File('ohos/AppScope/app.json5');
  if (ohosAppJson.existsSync()) {
    var content = ohosAppJson.readAsStringSync();
    // 简单正则替换 (实际建议用 json 解析)
    content = content.replaceFirst(
      RegExp(r'"versionCode":\s*\d+'), 
      '"versionCode": $buildNumber'
    );
    content = content.replaceFirst(
      RegExp(r'"versionName":\s*".*?"'), 
      '"versionName": "$versionName"'
    );
    ohosAppJson.writeAsStringSync(content);
    print('✅ 已同步版本到 OpenHarmony: $versionName ($buildNumber)');
  }
}

3.2 串联 Cider

我们可以定义一个 Make 命令或 shell 脚本，将 cider 和同步脚本串联起来。

# bump_ohos.sh

# 1. 使用 cider 升级版本
cider bump patch --bump-build

# 2. 同步到鸿蒙配置
dart scripts/sync_version.dart

# 3. 提交
git add pubspec.yaml CHANGELOG.md ohos/AppScope/app.json5
git commit -m "chore: bump version to $(cider version)"

这样，每次发布时，Flutter 侧和鸿蒙原生侧的版本号就完美同步了，彻底告别"版本不一致"导致的提审被拒风险。

四、高级进阶：自定义模板与 CI 集成

4.1 变更日志模板

你可以自定义 cider 支持的变更类型。在 cider.yaml 中：

diff_group:
  - Added
  - Fixed
  - Changed
  - Performance # 新增性能优化类
  - OHOS-Specific # 新增鸿蒙专属变更

这样就可以专门记录鸿蒙平台的适配工作：

cider log ohos-specific "适配了 Mate 60 Pro 的挖孔屏布局"

4.2 CI/CD 流水线

在 GitLab CI 或 GitHub Actions 中，cider 可以用来检查发布的合法性。

# GitHub Actions 示例
steps:
  - name: Check version
    run: |
      current_version=$(cider version)
      echo "Deploying version $current_version"

五、总结

cider 虽然小巧，但它解决了一个让无数开发者头疼的标准化问题。它强制团队遵循规范的变更日志记录习惯，并自动化了版本号的迭代。

对于 OpenHarmony 开发者，结合简单的脚本，cider 可以成为连接 Flutter 生态与鸿蒙原生工程配置的纽带，让跨端发布流程如丝般顺滑。

最佳实践：

1. 养成随手记 Log 的习惯 ：不要等到发版前才去翻 git log 回忆干了什么，用 cider log 随时记录。
2. 规范化 Commit ：cider 配合 Conventional Commits 规范效果更佳。
3. 自动化同步 ：务必编写脚本同步 pubspec.yaml 和 app.json5，这是鸿蒙混合开发的必修课。

六、完整实战示例

import 'dart:io';
// 假设使用了 yaml 库解析
// import 'package:yaml/yaml.dart'; 

// scripts/sync_version.dart
// 这是一个实用的脚本范例，用于将 pubspec.yaml 的版本号同步到鸿蒙工程配置
void main() {
  print('开始同步版本号...');
  
  // 1. 读取 Flutter 版本
  final pubspecFile = File('pubspec.yaml');
  final pubspecContent = pubspecFile.readAsStringSync();
  
  // 简单正则提取 version: 1.0.0+1
  final versionMatch = RegExp(r'version:\s*(.+)').firstMatch(pubspecContent);
  if (versionMatch == null) {
    print('❌ Error: pubspec.yaml 里没找到 version 字段');
    exit(1);
  }
  
  final fullVersion = versionMatch.group(1)!.trim();
  // 拆分 version: 1.0.0+1 -> "1.0.0", 1
  final parts = fullVersion.split('+');
  final versionName = parts[0];
  final versionCode = parts.length > 1 ? parts[1] : '1';

  print('Flutter Version: $versionName (Build: $versionCode)');

  // 2. 写入鸿蒙配置 (假设是 app.json5)
  final ohosConfigFile = File('ohos/AppScope/app.json5');
  if (ohosConfigFile.existsSync()) {
    var content = ohosConfigFile.readAsStringSync();
    
    // 替换 versionName
    content = content.replaceAll(
      RegExp(r'"versionName":\s*".*?"'), 
      '"versionName": "$versionName"'
    );
    // 替换 versionCode
    content = content.replaceAll(
      RegExp(r'"versionCode":\s*\d+'), 
      '"versionCode": $versionCode'
    );
    
    ohosConfigFile.writeAsStringSync(content);
    print('✅ 已同步到 OpenHarmony 工程: ohos/AppScope/app.json5');
  } else {
    print('⚠️ Warning: 鸿蒙配置文件未找到，跳过同步');
  }
}