目录

影响应用兼容性的关键信息

API版本号格式从26.0.0开始进行调整(详见版本号格式调整说明),不影响对API兼容性判断的基本逻辑,因此在文档的示意性描述中暂时仍保持旧版本格式的说明。

近期API版本号的大小关系如下:

26.0.0 > 6.1.1(24) > 6.1.0(23) > 6.0.2(22) > 6.0.1(21) > 6.0.0(20) > 5.1.1(19) > 5.1.0(18) > 5.0.5(17)

应用开发过程使用的SDK版本

如简介所述,开发应用时使用的SDK版本决定了API能力范围以及具体的API行为。在应用开发过程中,有如下SDK版本属性:

SDK版本属性

源码工程中配置项

(build-profile.json5文件中)

应用打包后的对应字段

(module.json5文件中)

说明

编译应用的SDK版本

compileSdkVersion

compileSdkVersion

编译应用工程的SDK版本,该字段决定了应用开发过程中可自动联想的API范围和使用的工具链版本。

取值默认为DevEco Studio自带的SDK版本,如需显式配置,只能配置为当前DevEco Studio自带的SDK版本。

应用运行的目标SDK版本

targetSdkVersion

targetAPIVersion

应用运行的目标SDK版本。默认取值为编译该应用的SDK版本号,即与compileSdkVersion的取值相同。

针对系统侧进行API版本隔离的变更,应用在终端设备上运行时会呈现以targetSdkVersion版本为目标版本的行为。

例如当前设备API版本为5.0.2(14),而运行在该设备上的某应用targetSdkVersion配置为5.0.1(13),则经过API版本隔离的变更会以5.0.1(13)版本的API行为呈现。在5.0.2(14)发生的API变更不会影响该应用在当前设备的实际表现。

建议开发者在升级SDK后重新编译应用工程时充分考虑API行为变更的影响,并合理配置targetSdkVersion的值。

应用运行的最低SDK版本

compatibleSdkVersion

minAPIVersion

应用运行要求的最低SDK版本。运行该应用的终端设备系统搭载的API版本不能低于该字段的值,低于则无法安装。

该字段版本值不能高于目标SDK版本。

可将compatibleSdkVersion的值设置为较小值,从而可在更低版本的系统上安装该应用,但应用是否能在compatibleSdkVersion对应系统版本上面正常运行,需要开发者针对无法在compatibleSdkVersion版本使用的API进行兼容性判断保护。

在应用的工程配置中,三个SDK版本属性之间的大小关系为:compatibleSdkVersion值≤targetSdkVersion值≤compileSdkVersion值,如果配置不符合这个规则,会有报错提示。

示例:

作为应用开发者,使用并适配了API版本6.0.2(22),同时希望应用能够运行到尽可能多的HarmonyOS现网设备,那么可以在应用工程的build-profile.json5 文件中进行如下配置:

"products": [
  {
    "name": "default",
    "signingConfig": "default",
    "compileSdkVersion": "6.0.2(22)",
    "targetSdkVersion": "6.0.2(22)",
    "compatibleSdkVersion": "6.0.0(20)",
    "runtimeOS": "HarmonyOS",
    ...
  }
]

本示例中,将compatibleSdkVersion值配置为6.0.0(20)(注意:compatibleSdkVersion字段具体配置的最低值,可根据应用运营策略和HarmonyOS现网设备API版本分布来决定),但因为该应用升级到了6.0.2(22),并使用了该版本的新API,考虑到新的API在6.0.0(20)版本会运行异常,所以需通过API版本判断进行保护,具体保护方式可以参考后续章节:API兼容性保护和告警屏蔽。

运行应用的设备系统所搭载的API版本

如简介所述,应用能否正常运行在终端设备上,与终端设备系统所搭载的API版本是否匹配应用中声明的SDK版本相关。

设备系统(ROM)所搭载的API版本可通过以下三种方式获取:

[h2]应用包中所记录的SDK版本信息

参考上述SDK版本属性表格, 在编译后的应用包的module.json中会记录compileSdkVersion,targetAPIVersion和minAPIVersion三个字段,其字段作用在上述表格有详细说明。

应用工程在编译后,单个模块的编译产物中,会将工程文件中的app.json5和module.json5的内容合并到一个module.json文件(详见应用配置文件概述)。因此上述三个版本字段在工程文件中来自module.json5,在编译产物中来自module.json,在获取时应注意区分。

应用市场分发时主要根据minAPIVersion进行分发范围的控制,该字段表示能够分发到的最小API版本的现网设备。

当用户设备的API版本低于应用包中的minAPIVersion时,该应用仍可在该设备的应用市场推荐页被展示,或通过搜索被查看到。但当用户点击安装此应用时,会提示此应用“无法安装”并给出所需要的系统版本要求(如下图所示)。

[h2]对API的行为变更进行API版本隔离

API版本在演进过程中可能会引入一些API的行为变更,系统对这些变更是否进行了API版本隔离也会直接影响应用的兼容性。

API实施行为变更时进行版本隔离是一种对应用的保护机制,应用开发者可以通过在应用源码工程中配置targetSdkVersion字段来告诉系统该应用运行的目标版本,从而决定使用什么样的API行为。

从2025年1月起,将对所有API行为变更是否进行版本隔离进行明确声明。

针对所有的应用,要求显式配置targetSdkVersion信息,方便系统根据该字段值判断应用的目标版本,从而决定版本隔离API的行为。从API版本6.0.0(20)开始,在开发者使用DevEco Studio打开工程时,如果源码工程中未配置targetSdkVersion,将会弹框提示开发者进行配置。