【 HarmonyOS 7.0 】三分钟理解 compatibleSdkVersion compileSdkVersion与 targetSdkVersion一、前言在 HarmonyOS 工程配置中你可能会看到类似这样的字段compatibleSdkVersion:6.0.0(20),targetSdkVersion:7.0.0(26),compileSdkVersion:7.0.0(26)很多初学者第一次看到它们时会觉得这些字段很像都是 SDK 版本那它们到底有什么区别这篇文章就用比较直观的方式讲清楚。compatibleSdkVersion最低兼容版本我的应用最低能跑在哪个系统版本上 targetSdkVersion目标适配版本我的应用是按照哪个系统版本来适配和测试的 compileSdkVersion我用哪个 SDK 来编译代码推荐与targetSdkVersion相同但不是必须相同compileSdkVersion targetSdkVersion。 所以上面的版本配置表示这个应用 最低要求 HarmonyOS 6.0.0 / API 20 才能运行 并且开发者声明应用已经按照 HarmonyOS 7.0.0 / API 26 的能力和规则完成适配。补充一下OpenHarmony 当前配置说明里仍能看到 compileSdkVersion 作为构建生成逻辑中的概念例如 targetAPIVersion 未配置时可由工程级 build-profile.json5 的 compileSdkVersion 自动生成。但在 DevEco 新工程模板中它不一定作为显式字段出现。在现在的 HarmonyOS / DevEco Studio 新工程里通常已经不需要你手动写 compileSdkVersion 了。以前一些教程或旧工程里会显式出现 compileSdkVersion但新版本工具链里编译 SDK 更多是由 DevEco Studio / Hvigor / 当前安装并选择的 SDK 来决定不一定再作为你手写的业务配置项出现。二、compatibleSdkVersion设置应用最低能跑在哪个sdk版本compatibleSdkVersion关注的是“兼容性下限”。例如compatibleSdkVersion:6.0.0(20)意思是这个应用最低要求 API 20。那么可以这样理解API 19 的设备不满足最低要求可能无法安装或运行 API 20 的设备满足最低要求可以运行 API 21 及以上设备通常也可以运行 它回答的是 这个应用最低支持哪个 HarmonyOS SDK/API 版本如果你的应用使用了 API 20 才有的新接口、新权限、新组件或新系统能力把compatibleSdkVersion设置为6.0.0(20)是合理的。如果你想让应用兼容更老的设备就不能随便把它设得太高。三、targetSdkVersion我按哪个版本来适配targetSdkVersion关注的是“目标适配版本”。例如targetSdkVersion:6.0.0(20)开发者声明这个应用已经适配到哪个 HarmonyOSSDK/API版本意思是这个应用是按照 API 20 的系统行为、接口规范和安全要求来开发与适配的。系统看到这个字段后会知道你的应用目标版本是多少。有些平台行为、权限要求、安全策略、兼容策略可能会根据目标版本有所不同。所以 targetSdkVersion不只是一个写给自己看的版本号它也是应用向系统表达的一种声明按照当前版本进行了适配。四、compileSdkVersion 哪个 SDK 来编译代码常见情况compileSdkVersion:6.0.0(20),targetSdkVersion:6.0.0(20)这是最常见、也最清爽的配置用 API 20 编译也按 API 20 适配。但也可能这样compileSdkVersion:6.0.0(20),targetSdkVersion:5.0.0(12)意思是我用较新的 SDK 编译 但应用暂时还声明按旧版本规则适配。这种情况通常出现在“正在逐步升级适配”的阶段。你可以先用新 SDK 编译接触新 API但还没有完全完成新版本行为、权限、安全策略等适配所以暂时不提高targetSdkVersion。不过不建议这样compileSdkVersion:5.0.0(12),targetSdkVersion:6.0.0(20)因为你声明目标适配到 API 20但编译环境却还是 API 12这在逻辑上就不匹配工具链通常也不鼓励甚至不允许。所以可以记成一句话compileSdkVersion 可以等于或高于 targetSdkVersion 新项目通常两者相同 升级期可以先提高 compileSdkVersion再完成适配后提高 targetSdkVersion。五、两者的核心区别字段关注点含义compatibleSdkVersion运行下限应用最低支持哪个版本targetSdkVersion适配目标应用按照哪个版本完成适配compileSdkVersion编译环境用哪套 SDK 编译代码如果类比 Android可以粗略理解为compatibleSdkVersion ≈ minSdkVersion targetSdkVersion ≈ targetSdkVersion 注意这里只是帮助理解的类比HarmonyOS 的具体配置和行为仍然要以 HarmonyOS 工程规则为准。当你不知道怎么设置时可以问自己三个问题1. 我的应用用了哪个 API 版本才支持的新能力 2. 我希望最低支持到哪个系统版本 3. 我实际测试和适配到了哪个目标版本对应关系就是用了新 API但不想兼容旧系统提高 compatibleSdkVersion 想兼容旧系统降低 compatibleSdkVersion并做好版本判断 已经按新系统完成适配提高 targetSdkVersion并且有个很重要的点如果你用了 API 26 才有的新接口但 compatibleSdkVersion 仍然是 API 20那么运行在 API 20 到 API 25 的设备上时必须做版本判断或降级处理。所以很多APP的处理方式是让用户升级到目标版本才能使用该APP不去做太低版本的兼容。因为兼容低版本功能判断和逻辑会很繁琐。在配置中三个 SDK 版本属性之间的大小关系为compatibleSdkVersion的值 ≤ targetSdkVersion的值 ≤ compileSdkVersion的值。如果不满足此规则编译时会报错。