API 26 编译通过，旧设备启动却崩了：HarmonyOS 7 兼容矩阵不能只测一个版本
项目升级 API 26 后在新模拟器编译、启动都正常，旧设备进入某页面却直接崩溃。团队把“编译通过”当成“兼容完成”，漏掉了运行时能力差异、行为变更和旧设备分支。官方升级指南明确要求评估 API 变化，并在新旧设备上做兼容验证；设备不足时可以使用云调试。本文把兼容测试从一台设备扩成可执行矩阵。
证据边界：文中 API 26/HarmonyOS 7 能力以华为当前官方文档为准；代码中的应用侧状态与一致性断言已在本机 Node.js 环境执行。当前本机 SDK 为 API 24，且没有连接 HarmonyOS 7 真机，因此本文不声称完成 API 26 编译、真机性能或上架审核验证。
先把故障钉在可复现步骤上
选取一个使用 API 26 新能力但仍需支持旧系统的页面。分别在旧 API 设备、API 26 设备和能力不可用设备上运行：冷启动、进入页面、切后台、恢复、升级安装。记录 compileSdkVersion、targetSdkVersion、deviceApi、capabilityResult 和 fallbackPath。
案例一：代码分支保护了调用，却没保护数据格式
新版本把本地数据升级为新结构，旧版本回滚安装后无法读取。兼容矩阵不仅测接口是否存在，还要测升级与回退的数据边界；不可回退时必须明确产品策略。
案例二：新 API 可用但设备能力仍不满足
设备 API 版本达到 26，不代表每个硬件能力都存在。入口展示和执行前都要做能力判断，并验证降级路径不是一张永远加载的空页面。
API 版本矩阵只是第一层
官方升级流程包括工具链升级、API 变化评估、新旧设备兼容测试和 AppGallery 发布。工程矩阵要再加安装路径、设备类型、能力结果与数据版本，才能覆盖真实用户从旧版升级到新版的过程。
API Change Assistant 用来找变化，不替代行为测试
工具可以帮助发现新增、废弃或行为变化位置，但它不能证明你的业务降级逻辑正确。每一个受影响调用都要落到页面场景、输入数据和预期结果。
设备不够时先补云侧覆盖，再保留证据边界
官方指南建议设备不足时使用云调试。云侧验证能扩展机型与 API 覆盖，但仍要保存构建号、设备信息、操作步骤和结果；一次远程打开成功不等于完整回归。
可直接放进工程的接口片段
// 工程配置示意，字段以实际 build-profile.json5 与产品配置为准。 const compatibilityCase = { compileSdkVersion: 26, targetSdkVersion: 26, deviceApi: 24, deviceType: 'phone', capabilityAvailable: false, expectedPath: 'fallback' } // API 26 调用必须在真实能力判断之后进入。上面是围绕官方接口位置整理的 ArkTS/工程片段，仍需在 API 26 工具链和目标设备上编译验证。为避免把接口示意当成证据，应用侧关键判定另写成可执行断言：
function route(c){ if(c.deviceApi<26 || !c.capability) return 'fallback'; return 'api26'; } if(route({deviceApi:24,capability:false})!=='fallback') throw new Error('旧设备没有降级'); if(route({deviceApi:26,capability:false})!=='fallback') throw new Error('只按版本误判能力'); if(route({deviceApi:26,capability:true})!=='api26') throw new Error('新能力入口错误');方案不是越复杂越好
| 方案 | 适用场景 | 放弃它的理由 |
| 只测 API 26 模拟器 | 新应用且无旧用户 | 看不到升级与旧设备问题 |
| 只做静态 API 扫描 | 迁移初筛 | 无法证明运行行为 |
| 版本×设备×安装路径矩阵 | 持续升级应用 | 用例数量更多但风险可见 |
采用分层矩阵：先用工具发现变化，再按风险选择版本、设备、能力和安装路径组合。高风险数据迁移与启动链路必须覆盖旧到新。
最终交付物
一张兼容矩阵模板和route()能力门禁断言。每个失败都能定位到版本、设备、能力或数据迁移维度。
- 旧设备冷启动和核心页面可用。
- API26 设备但能力缺失时能降级。
- 覆盖旧版升级到新版的数据迁移。
- 记录构建号与设备 API 证据。
- 云调试结果不冒充本地真机长期测试。
API 26 编译通过只是迁移开始。让版本、能力、设备与升级路径都进入矩阵，旧用户才不会替你完成第一轮兼容测试。
官方资料
- HarmonyOS 7 API 26 升级适配指南
- DevEco Studio 26 新特性
- HarmonyOS 开发者测试服务
