干 Android 开发这么多年几乎每次面试或者带新人都要被问一遍 compileSdk、minSdk、targetSdk 的关系。坦白说这几个参数在 build.gradle 里一行一个看着平淡无奇但它们管事范围完全不同。尤其是刚上手的新人经常出现这种场景依赖库引进来报错照着提示把 compileSdk 调高编译过了没两天测试机安装失败又有人让把 minSdk 调低再后来 Google Play 后台提示 targetSdk 必须达到某个版本又得吭哧吭哧改代码改完发现通知不弹了、权限流程也崩了。这三兄弟到底谁说了算、什么时候能动谁、动了以后得跟着做什么很多人其实是靠试错试出来的不是真明白。今天这篇不聊虚的我按自己多年的排查习惯把 MinSdkVersion、CompileSdkVersion、TargetSdkVersion 拆开揉碎讲清楚。从它们各自管什么、为什么这样设计到实际项目里怎么配置、报错怎么排查全部一次说透。文章尽量照顾零基础读者也保留一些只有踩过坑才懂的经验细节希望对你有用。1. 三个配置项一眼看明白它们各管一段路1.1 用一个生活化比喻迅速建立框架先打一个比方。假设你的 App 是一个开在商场里的餐厅厨房做菜用的是最新版国家菜谱这份菜谱就是 CompileSdkVersion你手里有的菜谱越新能做的菜越多这是后厨那摊子事和顾客无关。餐厅门口挂着一块牌子写着最低接待六年级以上学生那这就是 MinSdkVersion低于这个年级的顾客根本不进店门。而 TargetSdkVersion 更像是你对所有顾客的承诺我这家店完全遵守2023 年食品安全管理条例。商场的物业呢就按你承诺的版本来决定怎么管你——你承诺遵守新规物业就按新规严管你你没承诺物业就睁一只眼闭一只眼按老黄历办。对应到安卓系统里逻辑几乎一模一样compileSdk 决定你写代码时能调用哪些 API它只在编译期生效不会写进 APK手机上也看不到它。minSdk 决定哪些设备有资格安装你的 App手机系统版本低于它安装直接被拒绝。targetSdk 决定系统运行时对你采用哪一套行为规则系统会读取这个值并决定给你新规则还是老规则。这个框架一建立后面所有细节都围绕它展开。1.2 三个参数在 build.gradle 里的真实长相先说配置位置。不管是老项目还是新项目这三个值都定义在 app 模块的 build.gradle 里。用 Groovy 写是这样的android { compileSdk 34 defaultConfig { applicationId com.example.demo minSdk 23 targetSdk 34 versionCode 1 versionName 1.0 } }注意一点老版本 AGP 里经常写 compileSdkVersion、minSdkVersion、targetSdkVersion 这种带 Version 后缀的写法AGP 7.0 之后官方推荐去掉 Version 后缀两种写法目前都兼容。你要是看到网上教程两种混着写不用太纠结跟着你项目用的 AGP 版本走就行。在 Android Studio 里也可以打开 File - Project Structure - Modules - app - Default Config 面板可视化查看和修改这三个值。这个面板就是读取 build.gradle 里的配置展示出来的本质上还不如直接改 gradle 文件直观。注意compileSdk 需要本机安装对应的 SDK Platform否则构建时 Android Studio 会提示缺少组件一般点提示按钮就能自动下载。这里先把三个值的职责范围和生效时机分开理解后面每个值展开讲时就不会糊涂。2. MinSdkVersion决定你能接住多少用户2.1 它到底拦住了什么MinSdkVersion 是 App 支持的最低 Android 系统版本用 API Level 表示。比如 minSdk 23对应 Android 6.0意味着所有运行 Android 5.1 及以下系统的设备都不能安装这个 App。这个拦截发生在两个层面安装时系统 PackageManager 会读取 APK 里的 uses-sdk 标签把其中的 minSdkVersion 与设备系统版本对比设备版本低于 minSdk 就拒绝安装常见报错是 INSTALL_FAILED_OLDER_SDK。分发时Google Play 等应用商店会读这个值自动在低版本设备上隐藏 App用户根本搜不到。这两个拦截都发生在安装之前和用户转移之前所以 minSdk 直接影响你的用户盘子有多大。举个例子如果你的 minSdk 是 23Android 6.0 以下的存量设备用户你就完全放弃了。做国内应用市场可能还好但在海外 Google Play5.x 和 6.0 的老设备虽然占比不高基数大时也是实实在在的用户。2.2 minSdk 设高设低的真实代价minSdk 设低覆盖用户多但代价是一项项叠加的。第一个代价是代码兼容性。你写的代码如果调用了比 minSdk 更高的 APIAndroid Lint 会直接报错。比如你 minSdk 是 21却直接调用了 API 26 才引入的 NotificationChannelLint 会提示 Call requires API level 26 (current min is 21)。要解决就得在代码里判断if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { // 创建通知渠道 }这种判断稍微多几个其实还好烦的是大量第三方库也有自己的 minSdk 要求。比如你用的某个新版本支付 SDK 要求 minSdk 21而你的项目 minSdk 是 19Gradle 同步阶段就会报错要么降低库版本要么提升项目 minSdk两者都难受。第二个代价是方法数。Dalvik 时代 65535 方法数限制催生了 multidex 方案而 minSdk 21 以上系统原生支持 multidex不需要额外配置。现在很多项目 minSdk 直接定 21其实就是在降低构建和运行时的复杂度。第三个代价是开发成本。维护低版本意味着你得在旧系统上反复测试而 Android 6.0、7.0 时代的碎片化问题比现在严重得多。我见过不少团队被 Android 7.0 的共享文件、Android 8.0 的后台限制坑过低版本系统上的行为差异远比想象中多。所以 minSdk 是一个需要权衡的值不能一味求低。新项目建议从 21 或 23 起步如果是纯内部工具或者目标用户明确的 App甚至可以定到 26 以上能省掉大量老机型适配工作。2.3 设置 minSdk 的操作与 lint 配合实际操作的时候设置 minSdk 只是改一个数字但改完之后要配合 Lint 检查。在 build.gradle 里配置lint { abortOnError true }这样构建时遇到 minSdk 相关的 API 级别错误会直接终止构建把问题堵在开发阶段。我个人的习惯是本地构建保持 abortOnError false让 Lint 问题以警告形式显示release 构建再开启严格模式避免为了跑通本地调试被一堆 Lint 报错拦住。还有一个经验设置 minSdk 之前先查一下你依赖的主要第三方库当前要求的最低版本。为什么因为库的 minSdk 往往比你以为的高。比如新版 AndroidX 核心库早就有 minSdk 21 的要求很多厂商 SDK 也把门槛提到 21 甚至 23。你的项目 minSdk 如果比它们低Gradle 会提示你提升 minSdk或者要求启用 desugaring。与其被动改不如定项目前先摸底。3. CompileSdkVersion编译器的工具书版本3.1 compileSdk 是写代码时能看到哪些 APICompileSdkVersion 决定的是你在代码里能引用哪些 Android framework API。它不参与安装判断也不决定运行行为纯粹是编译期的视野范围。你 compileSdk 是 34就可以调用 Android 14 引入的新 API比如 API 34 里一些关于前台服务类型的方法。如果 compileSdk 是 33那在代码里写这些 API 会直接编译不过更准确说是找不到符号的报错。打个通俗的比方compileSdk 就是开发者手里的官方文档版本。文档越新你了解到的功能越多你可以在代码里调用它们。但手机运行时根本不看你的文档新旧只看你打包进去的代码在它系统上是否兼容。正因为 compileSdk 不写进 APK所以你把它调高一般不会伤害老设备用户——哪怕你的 compileSdk 是 35只要 minSdk 还是 23在老设备上运行时那些新 API 只有在老设备上不存在的仍然不存在代码里如果没做判断一样会崩溃。这也解释了为什么调高 compileSdk 通常是最安全的升级动作。3.2 为什么 compileSdk 调高通常最安全很多人不敢动 compileSdk怕升完出乱子。实际上 compileSdk 调高带来的一般都是甜蜜的烦恼。甜蜜是指你能用新 API 了构建时关于依赖库需要更高 compileSdk 的报错也消失了。烦恼是指编译期可能出现大量 deprecation 警告比如你之前用的某个方法在新版本文档里已被标记为废弃。注意这些只是警告不影响编译执行。真正需要注意的是 Lint 行为。compileSdk 调高以后Lint 认为你有能力使用新 API但它同时看你 minSdk 还是老版本于是会在你直接使用新 API 的地方报错。这不是 compileSdk 造成的而是 compileSdk 与 minSdk 之间的信息差造成的。解决办法就是标准的三段式处理if (Build.VERSION.SDK_INT Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { // 使用 API 34 的新方法 } else { // 走老逻辑 }或者给方法加上 RequiresApi(34) 注解声明这个方法只能在特定版本以上调用调用方自己负责判断。3.3 依赖库和 compileSdk 的博弈最常见的报错真实项目中compileSdk 不匹配的报错里90% 来自第三方依赖库。典型报错长这样Dependency androidx.core:core:1.13.0 requires libraries and applications that depend on it to compile against version 34 or later of the Android APIs.这个报错的意思是androidx.core 1.13.0 这个库是拿 compileSdk 34 编译的它内部用到了 API 34 的新符号你项目 compileSdk 低于 34编译时解析不到这些符号所以构建系统强制你升级。很多人第一次遇到这个报错第一反应是把库版本降回去。确实能解决问题但那等于永远被库版本绑架。更合理的思路是把你项目 compileSdk 升到足够高的版本。为什么因为库作者已经替你做了一轮新系统适配你升级 compileSdk 只是跟上节奏。我个人的建议是compileSdk 尽量保持高于或等于当前最新稳定版的前一代不要常年停留在老版本否则你每引一个新库都可能撞上这种报错。升级 compileSdk 时顺手看一下 AGP 的版本要求AGP 8.x 时代对 compileSdk 的最低要求也在逐年提高构建工具和编译版本要配套升级。注意compileSdk 必须大于等于 targetSdk否则打包工具会直接报错。这也是三兄弟里最硬性的约束之一。4. TargetSdkVersion系统按你的承诺决定用哪套行为4.1 系统运行时才会读取 targetSdkTargetSdkVersion 是最有意思的一个因为它在运行时才发挥作用。它会作为 uses-sdk 的一部分写进 APK 的 manifest 里系统启动 App 时读取它并根据这个值和设备系统版本的关系决定要不要对 App 启用某些新行为。这里有一个很多人没想明白的关键点App 代码里通过 Build.VERSION.SDK_INT 读到的值是设备系统的真实版本和 targetSdk 没有任何关系。而系统判断是否启用行为变更时看的是 targetSdk。举个例子。设备是 Android 10系统版本是 API 29。如果你的 App targetSdk 是 28系统读取到 targetSdk 29就会在分区存储这个问题上给你走老逻辑App 依然可以任意读写公共目录。但 App 自己代码里 Build.VERSION.SDK_INT 读出来是 29如果你在代码里判断SDK_INT 29 就按分区存储来适配反而会自己把自己绕进去。所以理解 targetSdk 的正确姿势是把系统行为开关和设备版本号看成两套独立的东西。系统用你的 targetSdk 做决策你的代码用 Build.VERSION.SDK_INT 做决策两者不一定同步。再说直白一点同一台 Android 10 设备装一个 targetSdk 28 的 App 和装一个 targetSdk 29 的 App系统给它们的行为规则可能不一样。这就是为什么有些人反馈同机型上微信能直接读所有文件我的应用却不行大概率就是 targetSdk 版本的差异。4.2 历届版本行为变更速查表targetSdk 升级之所以痛苦是因为每次新版本系统都会带来一批行为变更而且这些变更全都是targetSdk 达到某版本后强制启用的。我把这些年在实际项目里碰到过的、影响最大的行为变更整理成一张速查表方便你排查问题时对照系统版本API LeveltargetSdk 达标后的关键行为变更Android 6.023危险权限需在运行时动态申请不能只靠安装时授权Android 7.024跨应用共享 file:// Uri 会被拒绝必须用 FileProviderAndroid 8.026通知必须绑定通知渠道否则通知不显示Android 9.028默认禁止明文 HTTP 流量需要单独配置允许Android 1029强制分区存储公共目录读写逻辑必须重写Android 1130包可见性限制查询已安装应用需要声明查询范围Android 1231前台服务启动受限PendingIntent 必须指定可变性Android 1333通知需要 POST_NOTIFICATIONS 运行时权限Android 1434前台服务必须声明类型隐式 Intent 和广播使用受限这张表不需要死记但要养成一个习惯升级 targetSdk 之前先去官方文档看一遍对应版本的 Behavior changes 页面把和自己功能相关的条目单独拿出来列成待办清单。4.3 升级 targetSdk 的完整操作步骤升级 targetSdk 是整个 SDK 版本管理里最需要谨慎的动作。我建议按照下面这套流程走可以少踩很多坑第一步先升 compileSdk。无论你最终 targetSdk 目标是多少compileSdk 必须先到那个版本否则编译期间会有 API 缺失的报错。第二步把 targetSdk 改成目标版本同时保持 minSdk 不变。这一步改完先不要急着处理代码先把项目完整编译一遍看看有多少报错和老代码需要清理。第三步处理编译期问题。这包括新版 API 的强制要求、废弃 API 的替代方案、第三方库版本的对应关系。这一步通常需要替换掉一些老接口。第四步逐个核对行为变更清单。建议把上表当成参考主流程先自查一遍。通知、权限、文件读写这几个高风险区域必须重点测试。第五步在目标系统版本的真机或模拟器上跑完整回归。有条件的话用 Android 版本矩阵测试最低 minSdk 版本、新 targetSdk 版本、以及中间几个主流版本各跑一遍主流程。第六步灰度发布观察线上崩溃和用户反馈。尤其注意崩溃统计平台里有没有新增的权限异常、文件读写异常、Activity 启动异常。这些往往是行为变更直接导致的。我见过很多团队升级 targetSdk 只在最新系统上测一遍就发版结果 Android 8.0、9.0 上的用户大面积反馈异常。原因就是行为变更的触发条件是设备系统版本 目标版本比如你把 targetSdk 从 29 升到 30Android 11 以下的设备行为其实不变但 Android 10、9 上也可能有涉及 targetSdk 30 的边界逻辑。版本矩阵测试越多风险越低。5. 三者关系与配置场景实战5.1 正确关系minSdk targetSdk compileSdk三个值之间有一个公认的约束关系minSdkVersion targetSdkVersion compileSdkVersion这个约束既有自然逻辑也有工程工具层面的强制。targetSdk 大于 compileSdk 没有意义因为你都无法编译对应版本的 API何谈让系统按那个版本的行为规则运行构建工具也确实会拦截这种配置。minSdk 小于等于 targetSdk 是硬约束反过来就是逻辑错乱。你声称支持的最低系统版本比自己承诺适配的版本还高那等于 minSdk 以下的设备装上了 App却拿到了一套承诺新规的系统行为极容易出兼容性问题。工程上还有一个隐藏关系targetSdk 最好和 compileSdk 保持一致或者相差不超过一个大版本。为什么因为 Android Studio 新建项目的默认配置就是 compileSdk、targetSdk 同版本。保持两者一致你写的代码都来自新 API系统行为也是新规则逻辑上最自洽排查问题也最省心。5.2 常见场景的配置方案我整理了三种最常见的项目状态你可以直接对照参考。新项目起步没有历史包袱建议直接当前稳定版三件套拉满compileSdk 和 targetSdk 都是最新稳定版minSdk 根据用户画像定一般 21 或 23 起步。这样做的好处是以后的适配债务最少。老项目维护中暂时没精力做新系统适配那你可以先只升 compileSdk让项目能继续编译新依赖库targetSdk 暂时不动。这是一种过渡状态可以短期维持但不能一直拖。因为 Google Play 每年都会更新要求新应用和更新应用必须在指定时间内把 targetSdk 提升到门槛版本拖得越久一次性跨版本升级的阵痛越大。一些厂商定制 ROM 或者系统应用不受应用商店约束targetSdk 可以比较随意但我还是建议保持在一个合理版本。有些国产系统的权限管控比原生更激进低 targetSdk 反而可能被系统当作不兼容应用特殊对待限制后台活动或者弹警告。5.3 通过 ADB 和界面验证 APK 里的真实值光说不练不对这里教你怎么验证 APK 里实际打进去的值。第一种方法用 Android Studio 的 APK Analyzer。Build - Analyze APK选择要分析的 APK打开 AndroidManifest.xml可以看到 uses-sdk 标签下有两个属性minSdkVersion 和 targetSdkVersion。compileSdkVersion 不会出现在 APK manifest 里它只存在于构建过程。第二种方法用命令行工具 aapt。Android SDK 的 build-tools 目录下自带 aapt执行aapt dump badging your-app.apk | grep sdk输出面板里会看到类似内容sdkVersion:23 targetSdkVersion:34这两行就是打进 APK 的真实 minSdk 和 targetSdk。如果你发现实际值和你 build.gradle 里配置的不一致大概率是某个构建脚本在打包时动态修改了配置这种问题在大型工程里偶尔会出现。提示如果 grep 不到结果路径可能不对建议去 Android SDK 的 build-tools 目录下找到对应版本的 aapt或者用完整路径执行。6. 避坑实录升级 SDK 版本时的典型问题6.1 安装 APK 报 INSTALL_FAILED_OLDER_SDK 怎么办这个报错的含义非常明确你的 App 要求的 minSdk 比测试设备的系统版本高。比如你的 minSdk 是 26但测试机是 Android 7.1也就是 API 25安装时直接被拒。遇到这个报错先别急着调低 minSdk。正确做法是查一下测试设备的系统版本用命令adb shell getprop ro.build.version.sdk输出 25 就代表设备系统是 API 25。然后问自己一个问题这个设备是不是必须要支持如果是那 minSdk 确实要调低如果不是比如这台设备就是一个老旧的备用机那直接换测试设备更合理没必要让全体用户为测试环境买单。另一个容易混淆的报错是 INSTALL_FAILED_UPDATE_INCOMPATIBLE出现这个说明设备上已经装了一个签名不一致的旧版本 App卸载重装就能解决别把它和 minSdk 混在一起。6.2 compileSdk 报错为何总是依赖库先跳出来这是很多人升级 compileSdk 时的困惑明明我只改了一个数字报错的全是第三方库自己的代码反而安静。为什么因为每个依赖库在发布时都用自己当时的 compileSdk 编译库 A 用 34 编译库 B 用 33 编译你的项目 compileSdk 是 33那库 A 在合并依赖时就会报requires compileSdk 34。这类报错其实是个善意提醒你的一个或多个依赖比你项目本身更超前。处理思路按优先级排序首先把 compileSdk 升到报错要求的版本这是最直接的方案。然后检查是不是所有依赖都能在目标 compileSdk 下正常工作部分老库可能会触发新的 lint 检查。最后才是考虑降依赖版本。只有当某个库在新 compileSdk 下出现明确冲突且找不到替代实现时才建议回退版本。另外升完 compileSdk 之后建议顺手跑一遍查依赖的命令./gradlew :app:dependencies --configuration debugCompileClasspath看看依赖树里有没有多个版本冲突的老库这种版本蔓延问题在大型项目里很常见。6.3 targetSdk 升级后最容易翻车的三个行为变更按我自己这些年从 targetSdk 29 一路升到 34 的经验有三个坑出现频率最高几乎每个项目都会撞上。第一是通知权限。targetSdk 升到 33 之后Android 13 设备上通知必须动态申请 POST_NOTIFICATIONS 权限你没有在代码里申请用户装完 App 后一条通知都看不到而且系统不会弹窗询问。很多 App 的通知服务悄悄失效排查半天才发现是少加了权限声明和运行时申请。第二是前台服务限制。targetSdk 升到 31 及以上后后台启动前台服务的限制更严格了如果 App 在后台状态下尝试 startForegroundService会直接抛 ForegroundServiceStartNotAllowedException。这个必须是真机复现才明显模拟器上很多时候反而没问题。适配方案是合理安排启动时机或者用 WorkManager 等延迟执行机制。第三是文件读写变化。如果你把 targetSdk 升到了 29 以上就要面对分区存储。不要以为把 requestLegacyExternalStorage 设成 true 就能一劳永逸这个标志只对 Android 10 有效且 targetSdk 30 以上版本直接被忽略。正确做法是尽早把文件逻辑迁移到 MediaStore、SAF 或者应用专属目录。这三个坑的共同特点是它们都只在设备系统版本达标时触发所以你手上的测试机如果都还是老系统可能完全测不出来问题。发版前一定确保有一台接近最新系统版本的设备专门用来验证 targetSdk 行为变更。最后说点个人感想。SDK 版本这事其实没什么玄学核心就是理清三条线索编译期看 compileSdk安装门槛看 minSdk运行行为看 targetSdk。只要你每次动任何一个值之前先问一句这个值会影响编译、安装还是运行基本就不会犯大错。我见过太多线上事故都是只顾着编译通过、没顾运行行为变更加剧出来的。把这三个参数的关系始终放在心里你的 Android 版本适配之路会顺畅很多。