📚 课程目录第2章 Android SDK版本演进与兼容性策略

Android SDK 版本演进与兼容性策略：API 级别、targetSdkVersion、compileSdkVersion、minSdkVersion 的作用与最佳实践

说到 Android 兼容性，绕不开的就是那三个版本号：minSdkVersion、compileSdkVersion、targetSdkVersion。很多人刚入行时会觉得，反正都写 33 就完事了呗？千万别这么干——这三个玩意儿各管一摊，搞混了就会出现「明明编译通过了，用户手机直接崩溃」的惨案。我带团队的时候，就见过好几次这种问题。

三个版本号，各司其职

先看一个典型的 build.gradle 片段：

android {
    compileSdkVersion 34
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }
}

它们到底在干嘛？说白了：

compileSdkVersion：你用来编译 App 的 SDK 版本。它决定你代码里能调用哪些 API。比如 compileSdkVersion 34 你就可以用 Android 14 的新接口。
minSdkVersion：你的 App 最低能跑在哪个 API 级别上。低于这个版本的系统会直接拒绝安装。
targetSdkVersion：你声明这个 App 已经在某个 API 级别上做过充分测试，系统会按照这个级别的行为规则来运行你的 App。

你想想看，如果 minSdkVersion 设置太低，你调用了高版本的 API 又没做运行时检查，低版本设备上就会抛出 NoSuchMethodError。我在项目中遇到过类似情况：compileSdkVersion 升到 31 后直接用了 NotificationChannel，结果 minSdkVersion 是 19，线上崩溃率瞬间飙升——后来紧急加了版本判断才修复。

一张表格看清楚三者差异

属性	影响范围	运行时行为	升级风险
compileSdkVersion	编译期	不影响运行时，只控制能调用的 API	低风险，但可能引入编译警告
minSdkVersion	安装时 + 编译期	系统根据此值过滤设备，运行时不检查	降低会失去新 API，升高会丢失用户
targetSdkVersion	运行时	系统根据此值启用/禁用行为变更	中等风险，需适配系统新行为

我的习惯：每次 Google 发布新的 API 级别，我会先升 compileSdkVersion 看看编译是否通过，等适配完行为变更后再升 targetSdkVersion。一步到位容易踩坑。

API 级别演进：别忽视这几年的“坑”

Android 从 1.0 到现在的 14（API 34），每次版本更新都会带来一堆行为变更。我不可能把每个版本的变化都列出来，但有几个关键节点你必须清楚：

API 23 (Android 6.0)：引入运行时权限。如果你 targetSdkVersion 低于 23，系统会自动帮你授予权限；高于 23 就必须自己弹窗申请。我记得第一次升级 targetSdkVersion 到 23 时，整个团队花了一周改权限逻辑。
API 26 (Android 8.0)：后台执行限制 + 通知渠道。不设 NotificationChannel 的通知直接不显示。
API 28 (Android 9.0)：非 SDK 接口限制。通过反射调用隐藏 API 会收到警告甚至被拒绝。
API 30 (Android 11)：分区存储全面强制。我之前有个文件管理类的项目，升级到 targetSdkVersion 30 时差点重写所有文件读写逻辑。
API 33 (Android 13)：通知权限需要运行时申请。
API 34 (Android 14)：前台服务类型声明 + 更严格的隐式广播限制。

这些行为变更只会发生在 targetSdkVersion 等于或高于该版本时。所以你暂时不升 targetSdkVersion 就不受影响——但 Google Play 会逐渐强制要求新应用和更新必须使用较新的 targetSdkVersion。

最佳实践：怎么配置才安全？

1. minSdkVersion：尽量低，但别太低

原则上覆盖你目标用户群的 95% 以上就行。我一般会看 Google Play 控制台里的设备分布，或者用 android-api-level-distribution 统计。目前 minSdkVersion 21（Android 5.0）基本能覆盖 97% 以上的设备。如果你做的应用需要用到 Jetpack Compose，那 minSdkVersion 至少要 21。

曾经踩过的坑：我为了覆盖更多低端机把 minSdkVersion 设成 16，结果用到了 Java 8 的 lambda（需要 API 24+），运行时直接崩溃。后来改用 desugar 才解决。建议根据实际用到的语言特性和 API 做取舍。

2. compileSdkVersion：永远用最新

为什么？因为新 SDK 会弃用过时的 API，给你编译警告；而且 Android Studio 的 Lint 也会基于这个版本做检查。我习惯在 Google 发布新平台后的两周内升级 compileSdkVersion，让团队开始适配新 API。这样等到必须升 targetSdkVersion 时，我们已经把编译问题都解决了。

3. targetSdkVersion：稳步更新，不要拖

Google Play 对 targetSdkVersion 有强制要求：新应用必须使用最新的 API 级别，更新应用也有时间窗口。我的策略是：

每个版本升一级，不要跨多级升级（风险太高）。
升之前先读官方行为变更文档，列出所有可能影响的模块。
在测试机上跑全套自动化测试。
灰度发布，观察 Crash 和 ANR 率。

  一个具体的例子：去年我把一个 SDK 的 targetSdkVersion 从 30 升到 33，主要工作是适配了通知权限申请和前台服务类型。灰度一周后看到广商机型的兼容性问题，紧急修复了 Samsung 系列对 SCHEDULE_EXACT_ALARM 权限的差别处理。

他们之间的关系图

下面这张图展示了三个版本号如何串联起设备、编译和运行时的行为。你可以清晰地看到每个版本影响的环节：

常见的版本升级陷阱

做兼容性适配这么多年，我总结了几条最容易踩的坑：

只升 compileSdkVersion 不升 targetSdkVersion：编译没问题，但运行时旧行为还是生效，等于没适配。我见过有人把 compileSdkVersion 升到 33，targetSdkVersion 还留在 28，结果新 API 能用但通知权限弹不出来——因为系统认为他只适配到 28。
一次性跨太多版本升级 targetSdkVersion：比如从 23 直接升到 33，需要同时处理运行时权限、通知渠道、分区存储、后台限制等一堆行为变更，测试量大得惊人。建议每升一级就发一个版本。
依赖第三方 SDK 不更新：有些第三方还在用老的 targetSdkVersion，你的 App 升级后可能是它们的功能异常。我遇到过一个支付 SDK 在 targetSdkVersion 33 下无法拉起支付宝——因为他们没适配通知权限请求。

曾经吃过的大亏：有次升级 targetSdkVersion 到 30 后，发现部分小米手机上文件下载失败。查了两天才发现是分区存储导致 MediaStore 写入权限不同，而小米的 ROM 对 SAF 做了特殊处理。后来加了个判断：如果用户在旧设备上，还是用旧的存储方式。

日常开发中的小建议

最后分享几个我个人的做法：

在 CI 上跑编译时，额外开一个 compileSdkVersion = 最新 的任务，一旦有新 API 弃用就能提前收到警告。
每次升级 targetSdkVersion 之前，先在模拟器上跑一遍 CTS（兼容性测试套件）中的相关测试。
如果项目里有多模块，确保所有模块的 compileSdkVersion 保持一致，否则可能出现依赖冲突。
用 android:maxSdkVersion 在 manifest 里限制某些权限或 feature 只在特定系统版本上可见，可以避免很多兼容性问题。

嗯，理解了这三个版本号的本质，Android 兼容性适配就算入门了。剩下的就是跟着 Google 的版本节奏，稳扎稳打地升级。