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

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.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 log2. 开发完成

Yes

自动更新

自动归档

3. 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.mdchangelog: 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';voidmain(){// 1. 读取 pubspec.yamlfinal pubspecFile =File('pubspec.yaml');final pubspec =loadYaml(pubspecFile.readAsStringSync());final versionFull = pubspec['version']asString;// 解析 1.0.0+2final parts = versionFull.split('+');final versionName = parts[0];final buildNumber = int.parse(parts.length >1? parts[1]:'1');// 2. 更新鸿蒙 app.json5final 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. 提交gitadd 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 的版本号同步到鸿蒙工程配置voidmain(){print('开始同步版本号...');// 1. 读取 Flutter 版本final pubspecFile =File('pubspec.yaml');final pubspecContent = pubspecFile.readAsStringSync();// 简单正则提取 version: 1.0.0+1final 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", 1final 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: 鸿蒙配置文件未找到，跳过同步');}}