HarmonyOS 7.0 / API 26 DevEco SDK 基线治理：把版本漂移拦在 CI 前

这篇只拆一个具体点：DevEco Studio、HarmonyOS SDK、Hvigor 和 API 26 的团队基线治理。版本边界先放前面：下面的写法面向 HarmonyOS 7.0 / API 26。工程里如果还在混用旧 SDK、旧模拟器镜像或旧设备系统，先不要直接照搬代码，先把版本对齐。

这个问题为什么值得单独拆

团队里最容易被忽略的问题不是代码写错，而是每个人的 DevEco Studio、HarmonyOS SDK、Hvigor、Node 和模拟器镜像版本不一致。单机能跑，换一台电脑、换 CI、换审核机型就开始报错。这个问题如果不在提交前拦住，后面排查会非常慢。

这类问题的麻烦点是：代码经常能编译，页面第一次打开也像是正常的，但一到折叠屏、多窗口、后台恢复、跨设备入口或审核机型上，行为就开始不稳定。我的处理方式不是先改 UI，而是先把能力边界、触发条件、失败原因和兜底方案拆开。

先对齐官方能力边界

这里要避免一个常见误区：看到 7.0 新能力就直接在页面里调用。更稳的做法是先做一层能力判断，判断通过再进入新能力分支，判断失败就明确走兜底，日志里也要能看出失败原因。

两个容易复现的场景

场景一：同一份 ArkTS 工程在两台电脑上构建结果不一致

复现方式不要做得太复杂。先把页面打开到目标状态，再连续触发两次能力入口。这个时候重点看三个点：状态有没有丢、资源有没有重复申请、失败时有没有明确原因。

场景二：CI 镜像还停在旧 SDK，API 26 相关代码在流水线里失败

第二个场景更接近线上：用户不会按开发者预设路径操作，他会切后台、恢复、换方向、分屏、拖拽、锁屏再回来。只看单次点击，问题很容易被遮住。

拆法：先决策，再执行，再兜底

我会把实现拆成三层：

1. 能力判断层：只判断版本、设备形态、入口参数和依赖状态。
2. 执行层：只负责调用具体 API，不混入页面展示逻辑。
3. 兜底层：能力不可用时给旧方案、提示或延迟重试，不让页面进入半坏状态。

这样拆的好处是后面升级 SDK 或换设备时，不需要在每个页面里翻 if 判断。页面只拿一个明确结果：能用、不能用、为什么不能用。

Demo：把能力判断收口到一个 guard

type BaselineStatus = 'passed' | 'failed';

interface SdkBaseline {
  minApi: number;
  harmonyVersion: string;
  hvigorMajor: number;
  nodeMajor: number;
}

interface LocalEnvSnapshot {
  apiLevel: number;
  harmonyVersion: string;
  hvigorMajor: number;
  nodeMajor: number;
  modules: Array<{ name: string; compatibleSdk: number }>;
}

interface BaselineCheckResult {
  status: BaselineStatus;
  reason: string;
  moduleName?: string;
}

class DevEcoBaselineGuard {
  constructor(private readonly baseline: SdkBaseline) {}

  check(env: LocalEnvSnapshot): BaselineCheckResult {
    if (env.apiLevel < this.baseline.minApi) {
      return { status: 'failed', reason: 'sdk-api-missing' };
    }
    if (!env.harmonyVersion.startsWith('7.')) {
      return { status: 'failed', reason: 'harmony-version-mismatch' };
    }
    if (env.hvigorMajor < this.baseline.hvigorMajor || env.nodeMajor < this.baseline.nodeMajor) {
      return { status: 'failed', reason: 'toolchain-version-mismatch' };
    }
    const drift = env.modules.find((item) => item.compatibleSdk < this.baseline.minApi);
    if (drift) {
      return { status: 'failed', reason: 'module-profile-drift', moduleName: drift.name };
    }
    return { status: 'passed', reason: 'baseline-ok' };
  }
}

const guard = new DevEcoBaselineGuard({ minApi: 26, harmonyVersion: '7.0.0', hvigorMajor: 7, nodeMajor: 18 });
const result = guard.check({
  apiLevel: 26,
  harmonyVersion: '7.0.0',
  hvigorMajor: 7,
  nodeMajor: 18,
  modules: [
    { name: 'entry', compatibleSdk: 26 },
    { name: 'feature-search', compatibleSdk: 26 },
    { name: 'feature-pay', compatibleSdk: 25 },
  ],
});
console.info('[baseline]', JSON.stringify(result));

这个 Demo 只做一件事：先判断能力条件，再把结果交给页面。页面不直接关心 API 细节，也不把版本判断散落在 build 里。后面要接真实页面时，可以把 HarmonyFeatureGuard 放到公共模块里复用。

异常日志应该长什么样

[baseline] deveco=6.0.0, harmonySdk=7.0.0, api=26, hvigor=7.x, node=18.20.x
[baseline] status=failed, reason=sdk-api-missing, expected=26, actual=25
[baseline] status=failed, reason=module-profile-drift, module=feature-pay
[baseline] status=passed, modules=8, cost=412ms

日志不要只打印“失败了”。至少要带上 scene、status、reason 和耗时。否则出了问题以后，只能靠猜。

验证矩阵

跑完后应该看到的结果

case: local_api26_build -> passed
case: missing_api26_sdk -> blocked_before_compile
case: ci_hvigor_mismatch -> blocked_before_business_compile
case: module_profile_drift -> reported_with_module_name

我会怎么选方案

我的选择是第三种。只要这个能力会被多个页面用到，就不要把判断逻辑塞在页面里。页面只负责展示，能力边界、异常兜底、版本判断放到独立函数或组件里。这样后面改 SDK、换设备、补兼容逻辑，影响面会小很多。

排查顺序

1. 先把 DevEco、SDK、Hvigor、Node 版本全部打印出来，不要先猜 ArkTS 代码。
2. 再扫描 app.json5、module.json5、build-profile.json5，看 API 26 边界有没有在多模块里漂移。
3. 然后在 CI 构建前跑 baseline check，失败就直接返回明确 reason。
4. 最后把检查脚本放进提交前和发版前，避免只靠个人电脑环境。

可以怎么复用

这个写法可以继续扩成一个小工具：输入 featureName、apiLevel、deviceMode、entryState，输出 passed / failed / fallback 和 reason。页面层只根据结果更新 UI。这样做虽然前期多写几行代码，但后面接更多 HarmonyOS 7.0 能力时，判断逻辑不会越写越散。

最后总结

DevEco SDK 基线治理的核心不是记版本号，而是把版本、工具链、API 边界和 CI 检查收口成一套可复用的门禁，让团队在写业务代码之前先排除环境漂移。

这类特性真正有价值的地方，不是知道一个新名字，而是知道它在什么场景该用、什么时候不该用、怎么复现问题、怎么把修复沉淀成可复用代码。后面再接复杂页面时，先把这个小 Demo 跑通，基本能避开一半低级返工。

在中式美食项目里我会怎么落地

中式美食现在已经不是单页面 Demo，后面会有搜索、收藏、购物清单、互动卡片、多设备入口和可能的上架材料。只要多人协作或者换电脑，SDK 基线不统一就会反复制造假问题：有人说能编译，有人说不能；本地能跑，CI 不过；旧设备没问题，新能力页异常。

我的处理方式是把基线检查放到业务代码之前：先跑环境快照，再跑模块配置扫描，最后才允许进入 Hvigor 构建。这样排查顺序是确定的，日志也能直接告诉你是 SDK 缺失、Hvigor 版本不对，还是某个模块 compatibleSdk 没跟上。

为什么这比临时改配置更稳

这里我更建议第三种。HarmonyOS 7.0 / API 26 后面会继续引入新能力，项目越往后走，越不能靠口头约定。环境不统一，很多“代码问题”其实都是假问题。先把假问题挡住，真正的业务问题才会浮出来。