企业官网建设流程全解析

【 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。

五、两者的核心区别

如果类比 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的值。如果不满足此规则，编译时会报错。