Android SDK Platform 34/35 安装、适配与避坑指南

简介Android SDK 平台 34 和 35 是面向 Android 应用开发者的 API 级别组件包对应 Android 14/15 系统版本可用于解决应用在特定系统上的编译、调试与兼容性问题。该资源共包含 2000 个文件以 XML 系统数据与配置说明为主辅以 HTML 格式的 API 文档和少量 TXT 指引文件整体压缩包约 121.6MB。已有 383 人学习浏览适合需要对接新版 SDK 接口、验证新功能以及核查弃用 API 的中高级开发者。通过这套平台文件开发者可以查阅 API 34/35 的类与方法描述、组件定义和示例文档了解新增的 UI 元素、硬件支持及安全机制并借助 AVD 与 Emulator 配置虚拟设备进行兼容性测试。同时资源中的 XML 配置与 HTML 文档有助于梳理平台目录结构为项目迁移、构建脚本调整和后续多版本适配提供直接参考。 盯着 Android Studio 的 SDK Manager 看了半天发现列表里同时出现“Android SDK Platform 34”和“Android SDK Platform 35”两个勾选项这种场景我这两年见得特别多。如果你手上同时维护着两个甚至更多的 App或者刚接手一个从旧仓库升级而来的项目大概率也会碰到同样的疑问。这个标题看起来像个普通文件夹名但背后真正的问题其实是这两个平台包到底是什么、为什么要同时存在、以及它们到底该怎么装、怎么用、怎么排坑。确切地说android-sdk-platforms-34and35 并不是某个官方组件的固定命名而是开发者对platforms;android-34和platforms;android-35这两个 SDK 平台包的合称。前者对应 Android 14 的系统 API后者对应 Android 15。它们决定你的应用能调用哪个版本的 Framework 接口、系统行为和兼容性规则。这篇内容就围绕这两个平台包的安装、工具链匹配、适配要点和排障经验展开适合刚入门 Android 的工程师也适合正在搭建多版本构建环境的团队。先别急着点“Install”我建议你把全文看完再动手因为装错版本或者漏掉配套工具往往比不装更折腾。1. 项目概述为什么大家会同时遇到两个平台版本1.1 SDK 平台包到底是什么我见过不少新人把“SDK”理解成一个又大又全的安装包好像装完就万事大吉。其实 Android SDK 是分层的最底层是 cmdline-tools、platform-tools 这类命令行和调试工具再往上是 build-tools 编译工具而真正决定你项目编译目标的是platforms/android-XX目录。每个平台包的核心是一个android.jar外加一些系统镜像和索引文件。它提供的是这个 Android 版本对外暴露的 API 类与方法签名。你在代码里写compileSdk 34Gradle 就会去 SDK 目录里找platforms/android-34/android.jar来校验调用是否合法。如果你用了某个 API 35 才引入的方法而 compileSdk 还是 34编译阶段就会直接报“找不到符号”。所以升级平台包不只是“多点一个勾”这么简单它决定了整个编译栈的上限。1.2 为什么要常备两个版本理论上只装一个版本也能活但实际项目里 34 和 35 并存是常态。首先是渐进升级的需求应用商店往往要求新版本应用把 targetSdk 提到某个门槛比如 34但你的依赖库可能还没完全适配 35这时候你会想先让 compileSdk 升到 35targetSdk 仍然保持 34等库都跟上了再切换 targetSdk。这个过渡期就需要两个平台包同时在线。其次维护老项目的需求也很常见。有些项目还停在 AGP 7.x如果贸然把 compileSdk 顶到 35会有大量编译异常和 lint 规则需要处理先停在 34 反而更稳妥。另外还要考虑第三方 SDK 的适配节奏在实际项目维护中音视频、地图、推送这类 SDK 的版本更新往往滞后于系统版本主 App 已经在 34 上稳定跑了几个月而某些库到 35 才刚修复 16 KB 对齐问题。所以“34 负责稳定35 负责前瞻”成了不少团队的标准姿势。1.3 适用人群和典型场景原生 Android 应用开发者要根据业务需求在 targetSdk 和 compileSdk 之间反复切换。SDK 厂商或内部基础库维护者需要同时验证自己的库在 API 34/35 上的表现跑矩阵编译。跨平台工具链使用者比如 Flutter、UniApp、React Native 开发者底层依赖 Android SDK 版本还得保证编译端与运行端匹配。CI/CD 维护者流水线里必须预装两个平台包否则不同分支的构建会卡在“SDK location not found”。这里我要提前说明安装平台包只是第一步后续的 build-tools、platform-tools、模拟器镜像版本每一步都可能出问题我放到后面专门讲。2. 环境准备与工具链版本匹配2.1 Android Studio 与 AGP 版本怎么选很多人以为装了最新版 Android Studio 就什么都能编译其实 Android Studio 和 Gradle 插件AGP是两套独立的东西而 AGP 对 compileSdk 上限有要求。网上有个高频问题Android Studio Hedgehog | 2023.1.1 Patch 2 支持 AGP 8 版本吗答案是支持 AGP 8.x但这版 IDE 内置验证范围约在 AGP 8.2拿来编译 compileSdk 34 非常稳硬要编译 35 就会看到类似“This SDK is unsupported by this AGP version”的提示。目标平台包建议 AGP 下限建议 Android Studio 版本android-348.1.1 以上Hedgehog 2023.1.1 或更新android-358.6.0 以上Koala 2024.1.1 或更新上面的配置是我实际跑过的稳妥组合具体支持边界以你安装的 AGP release note 为准。如果你的工程里还有 Kotlin KSP、Hilt、Room 这类代码生成器升级 compileSdk 时最好把它们的版本兼容表一起核一遍否则很容易出现“报错提示在 Kotlin 插件里实际得换 AGP”这种绕圈子的情况。我在实测里就经历过一次单纯加 KSP 版本却一直编译不过最后发现是 AGP 太老换到 8.6 后瞬间通过。2.2 用 sdkmanager 精准安装两个平台包图形界面装 SDK 当然简单但如果你维护的是 CI 服务器或者 Studio 自带的下载通道不太稳我推荐直接命令行操作。Windows、macOS、Linux 下流程一致先确认ANDROID_HOME环境变量指向了 SDK 根目录然后执行cd $ANDROID_HOME/cmdline-tools/latest/bin ./sdkmanager platforms;android-34 platforms;android-35第一次运行会提示同意许可加一句自动接收yes | ./sdkmanager --licenses装完后用./sdkmanager --list_installed检查能看到platforms;android-34和platforms;android-35都出现说明平台包装好了。如果只想装一个就传对应的包名即可。另外需要注意很多人会顺手把build-tools;34.0.0装了这不是必须的Gradle 能用平台包自带的 build-tools 版本兜底但老项目如果有指定构建版本依赖最好把对应 build-tools 也补齐否则打包时会有“failed to find Build Tools revision”的花式报错。2.3 Gradle 工程配置示例平台包装好之后核心配置落在模块级build.gradleandroid { compileSdk 35 defaultConfig { targetSdk 35 minSdk 24 } }这段配置的意思是用 API 35 的接口做编译校验目标设备按 Android 15 的行为运行但最低兼容到 Android 7.0。如果你不想立刻升级 targetSdk可以先保持 34只把 compileSdk 提到 35这在迁移期是常用策略。这里有细节要提醒大家当 compileSdk 比 targetSdk 高时某些 lint 检查会变严格比如后台定位权限、隐私弹窗时机建议在迁移窗口内把 lint 报错降为警告或者分批修复否则团队并行开发时会多出很多“无效”的构建失败。3. 从 34 到 35 的核心差异和适配要点3.1 Android 14API 34必须知道的行为变化API 34 的改动面很大但我做适配时最优先处理的是这几项。第一前台服务类型强制化targetSdk 34 及以上每类前台服务必须声明对应的 foregroundServiceType并且启动前要有对应权限否则直接抛MissingForegroundServiceTypeException。第二广播接收器限制更严静态注册的 receiver 不能再接收大部分系统隐式广播需要改成动态注册或交给 WorkManager。第三精确闹钟权限闹钟、日程提醒类应用要单独申请USE_EXACT_ALARM或SCHEDULE_EXACT_ALARM并且在应用商店后台说明用途否则审核容易被拒。很多团队从 33 升到 34第一个崩溃点往往发生在后台启动 Activity 或读取已安装应用列表上。这类行为变化不是改一行配置就完事的得把业务场景逐个过一遍。我习惯先在测试机上装一份 targetSdk 34 的包跑一遍核心链路把日志里所有和权限、Intent、广播有关的异常都捞出来再统一改代码效率比上线后收到崩溃反馈再修高得多。3.2 Android 15API 35新增和强制项API 35 带来的最大变化我这边排第一的是 16 KB 页面大小支持。简单解释新设备的存储会按更大的页来管理如果你的 App 里包含自己编译的 .so 文件或者接入了带 so 的第三方 SDK这些库必须用 16 KB 对齐的 ELF 格式重新编译否则在 Android 15 设备上很可能直接崩溃日志里经常出现unsupported page size之类的关键词。这个问题在 x86 模拟器上偶尔不明显但放到真机上就很容易复现。第二个值得提前动手的是 edge-to-edge 默认强制执行。targetSdk 35 之后系统不再自动帮你避开状态栏和导航栏应用必须自己处理 insets不然页面内容会被摄像头打孔和手势条遮住。很多项目第一次升 35 都会收到“底部按钮被手势条挡住”的反馈这是新增适配工作量的大头。第三个是预测性返回动画系统推荐开发者迁移到新的返回回调onBackPressed老接口虽然短期还能跑但在 API 35 上表现会有差异。如果没时间细做至少要保证返回逻辑和之前一致再考虑动画跟进。3.3 多版本共存时的编译策略同时装了 34 和 35并不意味着每个项目都要用 35。我的建议是新项目或新模块直接用 compileSdk 35老项目可以再守一轮 34。如果你做的是 SDK 厂商最好针对 compileSdk 34 和 35 各跑一套 CI 矩阵任务因为客户的工程五花八门有的停在 33有的已经冲到 35只验证一个版本很容易埋雷。在多版本代码里尽量不要写“if (Build.VERSION.SDK_INT 35)”这种裸判断更推荐用 androidx 的 compat 系列比如ContextCompat.checkSelfPermission、ActivityCompat.requestPermissions它们内部已经封装好了各版本的行为差异。如果要调用某个版本独有的 API用RequiresApi注解标清楚并在调用处判断版本否则上线的包里可能藏着低版本崩溃的隐患。4. 实际问题排障与避坑记录4.1 安装平台包时的经典报错先说最近我真实遇到的一个报错“An error occurred while preparing SDK package”。很多人一看到这个提示就反复重试下载其实多半和两个因素有关一是本地 SDK 目录没有写权限二是之前下到一半的临时文件损坏。正确做法是关掉 Android Studio删除 SDK 目录下的.temp文件夹然后重新用 sdkmanager 命令安装Windows 上还要注意杀毒软件可能占用或锁定文件导致解压失败。另一个和 API 35 强相关的报错提示文本里会出现“16 kb page size”的字样。这个错误通常不出现在平台包安装阶段而是在创建或启动 API 35 模拟器的时候。原因是对应版本的模拟器系统镜像还没适配新的页面大小机制建议去 SDK Manager 把 Android Emulator 和系统镜像全部更新到最新同时确认模拟器加速模块处于启用状态。顺便回应一个历史问题SDK Tools 里没有 HAXM 怎么办其实 Intel 已经停止维护 HAXMAndroid Studio 早就换了新的加速方案。现在的关键不是装 HAXM而是确认 Windows 下 Android Emulator hypervisor driverAEHD已经启用或者系统虚拟化平台可用不然模拟器会慢到让人崩溃。4.2 编译期和运行期的兼容性问题编译期最容易翻车的是 AGP 版本不够。一升级 compileSdk 到 35就出现类似“Android SDK platform 35 is not supported by this Android Gradle plugin”的提示。这时候不用怀疑平台包装错了就是 AGP 太老按前面 2.1 节的表升级即可。还有个容易忽略的点升级 AGP 后 Gradle 版本也可能要跟着调一般 AGP 8.6 需要 Gradle 8.7 以上否则会有“Minimum supported Gradle version”的提示。运行期还有一类问题虽然跟平台包本身没直接关系但经常会伴随出现targetSdk 到 34 或 35 之后读取某些文件的 URI 会报file://被拒或者读取content://时出现 EACCES。这通常不是 SDK 平台包的问题而是 FileProvider 配置不对或者应用没有声明包可见性。很多开发者习惯在代码里直接拼/android/data/...这类路径去访问另一个应用的目录这在旧版本可能碰巧能用到 API 30 以后基本走不通必须改走 Storage Access Framework 或系统授予的媒体权限。再举一个项目里经常遇到的例子用跨平台工具做 App最后打本地包时提示“本应用使用 HBuilderX 5.24 编译而手机端 SDK 版本是 5.07不匹配”。这个报错跟 Android SDK 平台包没有直接关系但本质上是同一个版本错位问题编译端的 SDK 和运行端容器必须一一对应。升级时不能只更新编译器或只换手机端 SDK两边的版本号要一起对齐否则自定义基座跑不起来连真机调试都会断断续续。4.3 我总结的避坑清单把所有经验浓缩成一张表方便你直接对照检查场景症状做法安装平台包失败“An error occurred while preparing SDK package”清理 .temp、检查 SDK 目录权限、重新安装模拟器启动异常提示 16 KB page size 不兼容更新 Emulator 与系统镜像启用 WHPX/AEHD 加速compileSdk 35 编译失败“not supported by AGP”升级 AGP 到 8.6同步升级 Gradle 和 Android Studio第三方库不兼容老 so 在 Android 15 设备崩溃联系 SDK 厂商更新到 16 KB 对齐版本文件访问被拒EACCES / FileUriExposedException使用 FileProvider 和 SAF不要拼 data 路径跨平台工具端与运行端版本不一致本地包或基座提示 SDK 版本不匹配统一升级编译器与手机端 SDK 版本我个人的习惯是每个季度至少用最新的 compileSdk 建一个 demo 工程跑一遍依赖库升级和典型功能回归让团队的技术储备一直保持热度。这样做的好处是等平台包切换真正来临时不会出现“SDK 都装好了代码却编不过”的尴尬。如果你正在做 34 到 35 的迁移别急着把所有项目一次性全量升级先在测试分支上把 compileSdk 和 targetSdk 分步验证完再逐步铺开。我自己踩过几次坑之后发现很多所谓的“版本不兼容”其实只是升级顺序不对先稳后快才是省心的路线。本文还有配套的精品资源点击获取