Flutter 鸿蒙化的 tag 比上游多一位，根源在 semver：-ohos 是预发布后缀，会降低优先级。1.0.2 版改用 +ohos 构建元数据，让前半段与上游 3.41.9 一致，工具链的 parseOhosVersion 也支持这种写法。

Flutter 版本：3.41.9+ohos-1.0.2[1]

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

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

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 的两段后缀语义：

于是最终方案非常干净——把 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 等关键能力，为开发者带来更稳定的开发体验。

版本矩阵

新特性

• 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 行

六、结语

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

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

如果这篇文章对你有帮助，麻烦大家点赞 + 收藏 + 转发三连支持～ 你们的每一份认可，都是我持续输出技术干货的最大动力！后续还会带来更多实操教程，技术解读。记得关注不迷路哦～

也欢迎添加我的联系方式，咱们交个朋友！未来我也会持续分享各类前沿技术干货。

参考文档

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

参考资料

[1]3.41.9+ohos-1.0.2: https://atomgit.com/CPF-Flutter/flutter_flutter/tree/3.41.9+ohos-1.0.2

[2]issue #2414: https://atomgit.com/CPF-Flutter/flutter_flutter/issues/2414

[3]3.41.9+ohos-1.0.2: https://atomgit.com/CPF-Flutter/flutter_flutter/tree/3.41.9+ohos-1.0.2

[4][立即下载]: https://developer.huawei.com/consumer/cn/download/deveco-studio

[5][立即下载]: https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos

[6]build-profile.json5: https://developer.huawei.com/consumer/cn/doc/doccenter-deveco-studio/ide-hvigor-build-profile-app#section45865492619

[7]3.41.9+ohos-1.0.2: https://atomgit.com/CPF-Flutter/flutter_flutter/tree/3.41.9+ohos-1.0.2

[8]CPF-Flutter/flutter_flutter: https://atomgit.com/CPF-Flutter/flutter_flutter

[9]Issue #2414：Flutter OHOS 发布的版本号与上游社区不一致: https://atomgit.com/CPF-Flutter/flutter_flutter/issues/2414

[10]Flutter 3.41.9+ohos 1.0.2 ReleaseNote: https://atomgit.com/CPF-Flutter/flutter_flutter/blob/3.41.9%2Bohos-1.0.2/release-notes/Flutter%203.41.9%2Bohos%201.0.2%20ReleaseNote.md

[11]flutter_flutter 仓库: https://atomgit.com/CPF-Flutter/flutter_flutter

[12]samples 仓库（运行示例）: https://atomgit.com/CPF-Flutter/flutter_samples/blob/master/docs/ohos/README.md