企业官网建设流程全解析

干 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 是 23，Android 6.0 以下的存量设备用户你就完全放弃了。做国内应用市场可能还好，但在海外 Google Play，5.x 和 6.0 的老设备虽然占比不高，基数大时也是实实在在的用户。

2.2 minSdk 设高设低的真实代价

minSdk 设低，覆盖用户多，但代价是一项项叠加的。

第一个代价是代码兼容性。你写的代码如果调用了比 minSdk 更高的 API，Android Lint 会直接报错。比如你 minSdk 是 21，却直接调用了 API 26 才引入的 NotificationChannel，Lint 会提示 Call requires API level 26 (current min is 21)。要解决就得在代码里判断：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { // 创建通知渠道 }

这种判断稍微多几个其实还好，烦的是大量第三方库也有自己的 minSdk 要求。比如你用的某个新版本支付 SDK 要求 minSdk 21，而你的项目 minSdk 是 19，Gradle 同步阶段就会报错，要么降低库版本，要么提升项目 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 是写代码时能看到哪些 API

CompileSdkVersion 决定的是你在代码里能引用哪些 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 系统运行时才会读取 targetSdk

TargetSdkVersion 是最有意思的一个，因为它在运行时才发挥作用。它会作为 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 达到某版本后强制启用"的。我把这些年在实际项目里碰到过的、影响最大的行为变更整理成一张速查表，方便你排查问题时对照：

这张表不需要死记，但要养成一个习惯：升级 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 升到 30，Android 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 版本适配之路会顺畅很多。