一、SDK版本
三个SDK版本属性
| SDK版本属性 | 配置文件 | 打包后字段 | 说明 |
|---|---|---|---|
| 编译应用的SDK版本（compileSdkVersion） | build-profile.json5 | compileSdkVersion | 决定开发过程中可自动联想的API范围和工具链版本。默认为DevEco Studio自带的SDK版本 |
| 应用运行的目标SDK版本（targetSdkVersion） | build-profile.json5 | targetAPIVersion | 默认与compileSdkVersion相同。系统侧进行API版本隔离的变更以此版本为目标行为 |
| 应用运行的最低SDK版本（compatibleSdkVersion） | build-profile.json5 | minAPIVersion | 应用能安装的最低API版本，低于此版本无法安装。不能高于targetSdkVersion |
三者大小关系
compatibleSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion如果配置不符合这个规则，会有报错提示。
配置示例
开发中使用并适配了API版本6.0.2(22)，同时希望应用能够运行到尽可能多的HarmonyOS现网设备：
{
"products": [
{
"name": "default",
"signingConfig": "default",
"compileSdkVersion": "6.0.2(22)",
"targetSdkVersion": "6.0.2(22)",
"compatibleSdkVersion": "6.0.0(20)",
"runtimeOS": "HarmonyOS"
}
]
}targetSdkVersion的作用
应用在终端设备上运行时，会呈现以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。
二、运行应用的设备系统所搭载的API版本
应用能否正常运行在终端设备上，与终端设备系统所搭载的API版本是否匹配应用中声明的SDK版本相关。
三种获取方式
| 方式 | 操作 |
|---|---|
| 方式一（设置界面） | 设备设置 → 关于本机 → 查看"API版本" |
| 方式二（hdc命令） | hdc shell param get const.product.os.dist.apiname |
| 方式三（API接口） | deviceInfo中的distributionOSApiVersion/sdkApiVersion接口 |
hdc命令
# 获取API版本字符串（X.Y.Z格式）
hdc shell param get const.product.os.dist.apiname
> 5.0.5
# 获取API版本数值（X*10000 + Y*100 + Z）
hdc shell param get const.product.os.dist.apiversion
> 50005
# 获取OpenHarmony底座的API Level
hdc shell param get const.ohos.apiversion
> 17说明：
| 参数 | 说明 |
|---|---|
const.product.os.dist.apiname |
API版本的字符串表示（X.Y.Z） |
const.product.os.dist.apiversion |
API版本的数值表示（X*10000+Y*100+Z） |
const.ohos.apiversion |
OpenHarmony底座的API Level |
注意 ：界面中的API版本取值是从deviceInfo的distributionOSApiName和sdkApiVersion属性组合而成。
三、应用包中所记录的SDK版本信息
在应用包的module.json5中会记录三个字段：
| 字段 | 说明 |
|---|---|
| compileSdkVersion | 编译应用的SDK版本 |
| targetAPIVersion | 目标API版本 |
| minAPIVersion | 最低API版本 |
应用市场分发规则
应用市场分发时主要根据minAPIVersion进行分发范围控制：
-
用户设备的API版本低于minAPIVersion时：
-
可在推荐页展示或通过搜索查看到
-
点击安装时会提示"无法安装"并给出所需系统版本要求
-
四、API版本隔离
API版本在演进过程中可能引入行为变更。系统对变更进行API版本隔离是一种对应用的保护机制。
通过配置targetSdkVersion字段来告诉系统该应用运行的目标版本，从而决定使用什么样的API行为。
版本隔离的处理逻辑
| 情况 | 处理方式 |
|---|---|
| 配置的targetSdkVersion < API行为变更引入的版本 | 完全无需关注此变更影响，仍能在更高API版本系统上正常运行 |
| 配置的targetSdkVersion ≥ API行为变更引入的版本 | 需要关注此API行为变更，如果需在更高API版本系统正常运行，需要进行适配 |
未进行版本隔离的情况
如果API在行为变更时未进行版本隔离，将影响使用该API的所有应用。这些应用都必须按照变更说明中的适配指导进行调整，重新声明SDK版本要求，并完成编译上架。
说明
-
从2025年1月 起，将对所有API行为变更是否进行版本隔离进行明确声明
-
从API版本6.0.0(20) 开始，要求应用显式配置targetSdkVersion（如未配置，DevEco Studio会弹框提示）