Flutter 鸿蒙化版本号对齐上游：3.41.9+ohos-1.0.2 发布，一个 + 号背后的工程细节

Flutter 版本：3.41.9+ohos-1.0.2

---

一、背景：一个影响"使用体验"的版本号问题

开发者在实际使用中普遍反馈了一个长期存在的问题（社区已在 issue #2414 中跟进确认）：

Flutter OHOS 适配的是上游社区的 3.41.9 版本，但发布的 tag 却是 3.41.10-ohos-1.0.0，版本号不一致，影响使用体验，希望发布的 tag 能与上游社区的版本号一致。

为什么会出现"3.41.9 变 3.41.10"？问题出在 semver 的解析规则上：

• 按 semver 规范，3.41.9-ohos-1.0.0 中的 -ohos 是 prerelease（预发布） 后缀，会降低版本优先级，导致 3.41.9-ohos < 3.41.9；
• 为了避免版本比较解析失败，tag 不得不"加一"发布成 3.41.10-ohos-*。

结果是：OHOS 版本号与上游版本号"看着差一截"，开发者排查问题时无法直接对应到上游 tag，依赖解析中也容易产生歧义。

二、方案：用 build metadata 取代 prerelease

修复思路的关键在于正确理解 semver 的两段后缀语义：

后缀形式	示例	优先级影响
-prerelease	3.41.9-ohos	降低优先级（3.41.9-ohos < 3.41.9）
+buildmetadata	3.41.9+ohos	不影响优先级（3.41.9+ohos == 3.41.9）

于是最终方案非常干净——把 tag 从 3.41.10-ohos-* 改为 3.41.9+ohos-*：

git tag: 3.41.9+ohos-1.0.0  (标准 semver build metadata)
↓ parseOhosVersion 解析
gitTag:  3.41.9+ohos-1.0.0  (无需转换)
↓ pub_semver 解析
优先级 == 3.41.9 (上游稳定版)  ✅
满足 >=3.41.9  ✅

配套改动是让工具链的 parseOhosVersion 支持 +ohos build metadata 的 tag 格式（对应 PR：“feat: parseOhosVersion 支持 +ohos build metadata 格式”）。从此 Flutter 鸿蒙化版本的前半段与上游版本号完全一致，OHOS 侧的差异只体现在 +ohos 之后的适配层版本上。

三、3.41.9+ohos-1.0.2 发布内容速览

新的版本号格式在本轮发版中正式落地。Flutter OpenHarmony 适配版本 1.0.2 Release 基于上游 Flutter 3.41.9，主版本采用 +ohos build metadata 格式（与上游版本号完全一致），提升了 OpenHarmony 适配的可靠性，优化了版本 Channel、多实例管理、命令行 SDK 等关键能力，为开发者带来更稳定的开发体验。

版本矩阵

属性	版本	说明
Flutter SDK	3.41.9+ohos-1.0.2	版本采用 +ohos build metadata 格式
DevEco Studio	DevEco Studio 26.0.0 Release	开发环境（IDE）[立即下载]
Command Line Tools	Command Line Tools 26.0.0 Release	开发环境依赖项 [立即下载]
图形渲染 SDK	26.0.0	配置 DEVECO_SDK_HOME 环境变量指定 SDK 路径
运行时编译 SDK	26.0.0	在 build-profile.json5 中配置：compileSdkVersion: "26.0.0"
运行时兼容 SDK	5.0.5(17)	同上文件中配置：compatibleSdkVersion: "5.0.5(17)"

新特性

• feat(flex_overflow)：动态 DPI overflow 策略（含测试 API 与单元测试），解决动态 DPI 下 platformview 点击事件坐标分布异常的问题
• feat：parseOhosVersion 支持 +ohos build metadata 的 tag 格式（即本文主角）
• feat(ohos)：提升 GPU marknew 稳定性
• add：新增每日构建 dfx

行为变更

• 【3.41】change(Template)：新增 oh flutter 模板
• 【3.41】change(Template)：OHOS 工程默认 targetSdkVersion 改为 26.0.0，compatibleSdkVersion 改为 5.0.5(17)
• LTPO feature 默认开启

问题修复（节选）

• 【3.41】修复 StandardMessageCodec.writeValueInternal 缺失数据类型导致序列化失败
• 修复滑动掉帧时总帧数统计错误
• 【3.41】修复 channel 工厂模式下 JS crash
• 修复 Ability 重建后插件状态未恢复
• 修复 physicalTouchSlot 缺失 DPR 转换导致 touchSlot 降为 1.4
• 【3.41】修复(Texture)：通过 unregisterTexture 实现 SurfaceTextureEntry.release()
• 修复(Channel)：result 解码失败时发送 fallback 错误 envelope；Dart handler 抛异常时投递错误 envelope
• 修复 edgeToEdge 与 freeform 窗口退出时的安全区 padding
• 修复多 FlutterView onWindowCreate 场景下 keyboardHeightChangeCallback 未正确清理
• 修复 flutter drive 执行失败、DartVM deadline 时间错误等问题
• 修复(HarmonyOS 适配)相关部分内存泄漏
• 更新 skia_revision 修复字体别名与字重

完整变更请见仓库内 CHANGELOG_OHOS.md。

四、对开发者意味着什么

1. 版本对齐，排查更顺：OHOS tag 的主版本号与上游一一对应，遇到问题可以直接对照上游 3.41.9 的 release note 与 diff，不再需要"猜"适配了哪个上游版本。
2. 依赖解析无坑：+ohos 后缀不改变版本优先级，pub 依赖解析中 OHOS 版本被视为与上游稳定版同级，不会再出现"为了绕过解析而 +1"的补丁。
3. 升级建议：正在使用旧 3.41.10-ohos-* 系列 tag 的项目，建议迁移到 3.41.9+ohos-* 系列（如本次的 3.41.9+ohos-1.0.2），并同步关注 DevEco Studio / Command Line Tools 26.0.0 与 compileSdkVersion: 26.0.0 的配套要求。

五、踩坑复盘：为什么 -ohos 不行、+ohos 行

现象	根因	解法
直接用 3.41.9-ohos 作 tag，pub/semver 比较后优先级低于 3.41.9，部分 >=3.41.9 约束无法满足	- 后缀是 prerelease，按规范降低版本优先级	改用 +ohos build metadata，优先级与上游稳定版一致
旧方案被迫把 tag 提升为 3.41.10-ohos-*	prerelease 语义无法表达"基于 3.41.9 的稳定适配版"	引入 parseOhosVersion 对 +ohos 格式的支持，tag 语义由 build metadata 承载

六、结语

从社区提 issue 到新格式落地发版，这个改动很小——只是把一个 - 换成 +；但它把 Flutter 鸿蒙化版本的定位从"上游的魔改分支"变成了"上游版本的 OpenHarmony 构建"（build metadata 恰好就是干这个的）。版本语义正确了，生态的协作成本才会持续下降。

欢迎体验 3.41.9+ohos-1.0.2，有问题到 CPF-Flutter/flutter_flutter 提 issue 反馈。

参考文档

• Issue #2414：Flutter OHOS 发布的版本号与上游社区不一致
• Flutter 3.41.9+ohos 1.0.2 ReleaseNote
• flutter_flutter 仓库
• samples 仓库（运行示例）