Flutter OHOS SDK 版本目录校验 Bug 修复实战

Flutter OHOS SDK 版本目录校验 Bug 修复实战

本文详细记录了一个困扰鸿蒙 Flutter 开发环境的 Bug 的分析、定位与修复过程。

问题源于 OhosSdk 与 HmosSdk 共享全局变量导致的副作用，最终通过调整校验逻辑从"全部存在"改为"任一存在"解决。

仅改动 3 行代码，但涉及对 SDK 版本管理机制和共享状态风险的深入理解。

• PR 地址 : CPF-Flutter/flutter_flutter!2
• 作者 : jianguoxu (坚果)
• 目标分支 : oh-3.41.9-dev
• 变更文件 : packages/flutter_tools/lib/src/ohos/ohos_sdk.dart
• 变更量: +3 / −3，共 3 行

---

一、背景

Flutter OHOS SDK 架构简介

Flutter 在 OpenHarmony/HarmonyOS NEXT 上的运行需要两个 SDK：

SDK 类型	类名	来源	典型版本目录
OpenHarmony CLI SDK	OhosSdk	OpenHarmony SDK 管理器	ohos-sdk/.../23
DevEco Studio SDK	HmosSdk	DevEco Studio 内置	hmos-sdk/.../default (对应 API 24)

这两个 SDK 虽然来源不同，但都通过统一的 HarmonySdk 接口对外提供服务。

sdkVersionMap 共享机制

在 ohos_sdk.dart 中，存在一个全局静态变量：

static Map<String, String> sdkVersionMap = <String, String>{};

调用方	写入时机	写入内容
OhosSdk.localOhosSdk()	初始化时	{..., "23": "23"}
HmosSdk.localHmosSdk()	初始化时	{..., "24": "default"}

这个 Map 的 Key 是 API Level 的字符串表示，Value 是对应的子目录名称。问题是：两个不同来源的 SDK 共享同一个全局 Map。

---

二、问题现象

复现步骤

1. 配置 OHOS 开发环境，同时安装了 OpenHarmony CLI SDK (API 23) 和 DevEco Studio SDK (API 24)
2. 运行 flutter doctor 或执行任何需要校验 SDK 的命令
3. 输出报错：找不到有效的 SDK 目录 ，HmosSdk.validApi11SdkDirectory() 返回 false

错误日志

[✗] OHOS development
    ✗ HmosSdk directory validation failed at /path/to/hms-sdk/...
    ✗ Valid SDK directory not found

根本原因分析

执行流程如下：

1. OhosSdk.localOhosSdk() 被调用 → 将 "23" 写入 sdkVersionMap["23"]
2. HmosSdk.localHmosSdk() 被调用 → 将 "24" 写入 sdkVersionMap["24"]

此时 Map 内容为：{"23": "23", "24": "default"}

3. HmosSdk.validApi11SdkDirectory(hmosHomeDir) 被调用，代码如下：

// 修复前：要求 ALL 条目都存在
static bool validApi11SdkDirectory(String hmosHomeDir) {
  if (sdkVersionMap.length == 0) return false;
  for (String sdkName in sdkVersionMap.values) {
    Directory sdkDir = globals.fs.directory(
        globals.fs.path.join(hmosHomeDir, sdkName));
    if (!sdkDir.existsSync()) return false;  // 🔴 只要有一个不存在就失败
  }
  return true;
}

• 遍历 {"23", "default"}
• hmosHomeDir/default → ✅ 存在（DevEco SDK 的正确目录）
• hmosHomeDir/23 → ❌ 不存在！（这是 OpenHarmony SDK 的目录，不在 DevEco 路径下）
• 返回 false → 校验失败

核心矛盾 ：OhosSdk 的版本号（API 23）被写入了全局 Map，但当 HmosSdk 做目录校验时，它被迫检查所有 Map 条目------包括不属于自己的版本目录。

---

三、修复方案

代码变更

// 修复前
if (!sdkDir.existsSync()) {
  return false;
}
// ... 循环结束后
return true;

// 修复后
if (sdkDir.existsSync()) {
  return true;
}
// ... 循环结束后
return false;

逻辑变化

模式	运算符	含义	要求
修复前	AND (全称)	∀ dir ∈ map: exists(dir)	所有版本目录都必须存在
修复后	OR (存在)	∃ dir ∈ map: exists(dir)	任意一个版本目录存在即可

为什么这个修复是正确的？

核心论证 ：validApi11SdkDirectory 的目的是"检查 DevEco SDK 是否有效安装"，而不是"检查所有已注册的 SDK 类型是否都已安装"。

• DevEco Studio SDK 的安装路径下，只包含自己的版本目录 （如 default/API 24）
• OpenHarmony CLI SDK 的版本目录（如 23）在完全不同的路径下
• 如果要求 DevEco 路径下必须存在 OpenHarmony 的版本目录，逻辑上就不合理

所以将"ALL"改为"ANY"是对业务语义的纠正，而非简单的保守降级。

---

四、潜在的更优方案

虽然当前修复（3 行变更）是最小侵入、最安全的方案，但理论上还有两种更彻底的解决思路：

方案 A：分离全局状态

// OhosSdk 和 HmosSdk 各自维护自己的版本 Map
class OhosSdk {
  static Map<String, String>? _ohosVersionMap;
  // ...
}

class HmosSdk {
  static Map<String, String>? _hmosVersionMap;
  // ...
}

优点 ：彻底消除副作用的根源

缺点 ：重构量大，可能影响其他依赖 sdkVersionMap 的代码，且需要全量回归测试

方案 B：限定校验范围

static bool validApi11SdkDirectory(String hmosHomeDir) {
  // 只校验 HmosSdk 相关的版本，而非全部
  final hmosVersions = sdkVersionMap.entries
      .where((e) => /* 属于 HmosSdk 的版本条件 */);
  // ...
}

优点 ：保留了 map 共享，但做了隔离

缺点：需要额外的过滤逻辑，复杂度增加

为什么最终选择当前方案？

考量维度	当前方案 (ANY)	方案 A (分离)	方案 B (过滤)
改动量	3 行	~50+ 行	~15 行
回归风险	极低	高	中
永久正确性	✅	✅	⚠️ 需维护过滤条件
合入速度	当天可合	需多轮评审	需额外讨论

对于生产环境的紧急 Bug 修复，3 行变更 + 极低风险是最高优先级。

---

五、关键决策说明

决策 1：不改全局共享设计

虽然共享 sdkVersionMap 是问题的根源，但修复 PR 没有选择重构这一设计，原因如下：

1. sdkVersionMap 在多个代码路径中被引用（ohos_sdk.dart 内有 localOhosSdk、localHmosSdk、validApi11SdkDirectory、sdkVersion getter 等），改动扩散面大
2. 该 PR 的目标是 fix a concrete bug，而非进行架构重构
3. 重构可以单独开一个 Refactor PR，分开评审、分开测试

原则：Bug 修复聚焦最小可行修复，架构改进分离到独立 PR。

决策 2：保留 sdkVersionMap.length == 0 的检查

修复方案保留了 Map 为空时返回 false 的早期退出逻辑。这是合理的兜底------没有任何已注册版本时，目录校验理应失败。

---

六、测试与验证

测试环境

项目	版本
Flutter (OHOS fork)	oh-3.41.9-dev
OpenHarmony SDK	API 23
DevEco Studio SDK	API 24
测试设备	OpenHarmony 模拟器

测试用例

#	场景	预期	结果
1	仅安装 OhosSdk + 配置 HmosSdk 路径	validApi11SdkDirectory ✅	通过
2	仅安装 HmosSdk	validApi11SdkDirectory ✅	通过
3	两者都未安装	validApi11SdkDirectory ❌	通过
4	flutter doctor 完整流程	所有检查通过	通过

---

七、总结与收获

本次修复的核心价值

Bug:  HmosSdk.validApi11SdkDirectory() 错误地使用了 ALL 语义
       → 因共享全局 Map 导致遍历到不属于自己的版本目录
Fix:  改为 ANY 语义
       → 任一有效版本目录存在即可通过校验
Risk: 极低（3 行，逻辑等价翻转）

可以推广的经验

1. 共享全局状态的副作用 ：即使设计初期觉得"两个类共享一个 Map 没问题"，实际运行中可能因初始化顺序、调用上下文不同而出现意料之外的交互。如果你在设计公共 SDK 类时发现它们在共享状态，考虑早期分离或使用依赖注入。

2. "ALL" vs "ANY" 的校验语义选择：遍历集合做存在性检查时，问自己一个问题------"这个集合里的条目是属于我的，还是混杂了其他人的？"如果答案是可能混杂，应该使用 ANY。

3. 最小修复原则：生产环境 Bug 修复优先选择影响面最小的方案。重构可以且应该单独进行。

后续改进方向

• 可以考虑将 sdkVersionMap 拆分为 OhosSdk 和 HmosSdk 各自的私有作用域 Map
• 增加针对共享状态问题的单元测试，覆盖混合 SDK 配置场景

---

参考文档

• Flutter OHOS SDK 文档
• PR #2 - update: 更新文件 ohos_sdk.dart
• OpenHarmony SDK 管理
• Awesome HDC 命令合集