📚 课程目录第4章编译选项配置错误

4. 编译选项配置错误：compileSdk、minSdk、targetSdk 不兼容

编译选项这仨参数，说白了就是告诉 AGP：「你的 App 要在哪些 Android 版本上跑、能用哪些新 API、编译时用哪套库。」

它们分别是compileSdk、minSdk、targetSdk。名字看着像，但各管一摊。我见过不少项目因为没理清它们的关系，编译直接崩掉，或者运行时莫名其妙地出问题。

  核心结论：compileSdk ≥ targetSdk ≥ minSdk。这条不等式一旦被打破，轻则报错，重则运行异常。

4.1 三个参数各自干什么

先别急着动手改build.gradle。我们得弄清楚每个参数到底影响了哪个环节。

参数	作用阶段	本质含义
compileSdk	编译阶段	告诉编译器你能用哪个版本的 Android API 来写代码。比如设为 34，你就可以用 Android 14 的新 API。
minSdk	安装阶段	你的 App 最低能跑在哪个 Android 版本上。低于这个版本的系统直接拒绝安装。
targetSdk	运行时行为	告诉系统：“我测试过这个 API level，你按这个版本的兼容规则来运行我。” 说白了，你主动声明「我能适配到哪个版本的行为」。系统会根据这个值来决定是否启用一些行为变更（比如运行时权限、后台限制）。

你想想看，compileSdk 是你写代码时的「武器库」——版本越高，你能调用的新 API 越多。minSdk 是「门槛」——太老的系统不接待。targetSdk 则是「适配声明」——你告诉系统按哪个版本的规则来管你的 App。

4.2 常见的不兼容场景

我在项目中遇到过好几次「编译好好的，一发布就崩」的情况。追根溯源，基本都是这三个参数打架了。

场景一：minSdk 比 compileSdk 还高

这是最直白的错误。你设置 minSdk 31，但 compileSdk 30。这意味着你声明 App 最低支持 Android 12，但你的编译器只能用 Android 11 的 API。凭什么？

编译时 AGP 会直接甩一个错误：

ERROR: The minSdk 31 is greater than the compileSdk 30, which is not supported.

解法很简单：要么把 compileSdk 升到 31+，要么把 minSdk 降到 30 以下。我个人习惯尽量提升 compileSdk 到最新稳定版，这样能用上新 API，而且不丢低版本用户。

场景二：targetSdk 比 minSdk 还低

这个场景有点隐蔽。比如 targetSdk 28、minSdk 29。你告诉系统「请按 Android 9 的规则运行我」，但同时又说「最低支持 Android 10」。系统会怎么处理？嗯，实际上它会把 targetSdk 视为等同于 minSdk，因为不可能用比最低版本更老的规则来跑。

这通常不会直接报错，但会导致你期待的某些行为变更不生效。比如你本想关闭 Android 10 的「后台定位限制」，但因为 targetSdk 设置「不对」，反而让你的 App 在不该开权限的时候开了权限。

曾经有个同事，为了快速适配分区存储，把 targetSdk 从 29 降到 28，以为「低版本不强制」。结果 minSdk 是 29，那 targetSdk 28 完全没用，该适配的还得适配。这种掩耳盗铃的做法，最坑的是自己。

场景三：用了新 API，但 compileSdk 没跟上

你在代码里调用了 ActivityResultLauncher（AndroidX Activity 1.2+ 需要 API 30+），但你的 compileSdk 还是 29。编译时 IDE 会给你红色波浪线，但如果你强行编译……嗯，手动执行 ./gradlew assembleDebug 可能直接报错。

error: cannot find symbol class ActivityResultLauncher

这种情况下，千万别用反射去绕过。老老实实升 compileSdk。我记得有一次为了赶工期，团队想「取巧」用反射调用 Android 12 的 SplashScreen API，结果 compileSdk 还是 30。编译虽然过了，但很多旧手机上反射失败，直接 NPE。最后花了两天擦屁股。

4.3 升级策略与兼容性建议

知道了问题，接下来就是怎么避免。我总结了一套比较稳妥的升级流程。

先升 compileSdk 到最新稳定版。比如现在 Android 14（API 34）已稳定，就设到 34。新 API 随便用，多爽。
评估 minSdk 是否要跟着升。别冲动。看看你用户群体的系统分布。我记得有一次把 minSdk 从 21 升到 23，直接损失了 3% 的用户。如果这个数字你能接受，再升。
targetSdk 跟随 compileSdk，但至少差不超过一个大版本。我个人习惯设为与 compileSdk 相同，因为现在很多新 API 的行为变更与 targetSdk 绑定。如果差得太多，系统可能会把你的 App 当「旧版 App」处理，跳过不少新特性检查——包括你想要的权限管控。

小技巧：在 Android Studio 里，你可以用 Tools → App Inspection → Network Inspector 模拟不同 API level 的设备来测试 targetSdk 变更的影响。不用真机也能跑。

4.4 避坑指南

不要随意降低 targetSdk。Google Play 商店从 2023 年开始要求新 App 必须 target Android 12+。降版本只会让你失去上架资格。我曾经在一个老项目里为了省事把 targetSdk 降到 28，结果审核直接拒了。
minSdk 不要设得太激进。设到 23（Android 6.0）还算合理，但直接设到 31（Android 12）？你想想看，那些还在用 Android 10 的用户怎么办？除非你有充分理由。
依赖库的版本也会影响这三个参数。比如你引入了一个要求 compileSdk 33 的库，你的 compileSdk 就必须 ≥ 33。否则编译报错：uses-sdk:minSdkVersion xx cannot be smaller than version yy。

⚠️ 需要特别小心：升级 compileSdk 时，同步检查所有第三方依赖是否有新 API 适配版本。我遇到过升级 compileSdk 到 34 后，一个老旧的推送 SDK 内部用了已被删除的 API，直接编译不过。最后只能等对方发新版。

4.5 一个典型的配置示例

给你一份我觉得比较稳妥的 build.gradle 片段（假设你的最低用户是 Android 7.0 以上）：

android {
    compileSdk 34  // 使用当前最新稳定版

    defaultConfig {
        minSdk 24                                // Android 7.0
        targetSdk 34                             // 与 compileSdk 保持一致
        versionCode 1
        versionName "1.0"
    }
}

为何选 minSdk 24？因为 Android 7.0 及以上占了目前市场约 98% 以上的份额（根据 2024 年 Google 数据）。低于这个版本的设备你基本可以忽略——真的在用的也跑不动你现在的 App。

嗯，讲到这里，你应该对这三个参数的关系和常见问题心里有数了。简单总结一句话：compileSdk ≥ targetSdk ≥ minSdk，升级时先升 compileSdk，慎动 minSdk，targetSdk 最好跟随 compileSdk 走。做到这三点，绝大部分编译选项相关的坑你都不会踩到。