如果你在 Android Studio 的 Build 窗口里看到这么一行报错——failed to load include path 'C:\Users\你的用户名\AppData\Local\Android\Sdk\platforms\android-35\android.jar'——大概率不是你代码写错了，而是 Gradle 在编译的第一步就找不到对应 API Level 的 android.jar。我第一次遇到这个问题时，差点把整个项目重新 clone 了一遍，后来才发现真正原因就是 Android SDK Platform 35 没装。而这个报错最坑的地方在于，它不会明说“请安装 Platform 35”，只会丢给你一个“include path 加载失败”，看起来像是工程配置坏了，实际却不是。
这篇文章我会把这个报错从出现场景、根因拆解、解决手段到防坑习惯完整过一遍，覆盖 Android Studio 图形界面、命令行 Gradle 和 CI 构建三种场景。适合刚拿到别人项目的新手，也适合被这个问题反复折腾的老开发。只要跟着章节走完，基本能一次性解决。
1. 报错现场还原：它究竟在哪个环节冒出来
1.1 三种高频出现场景
这个报错不是只在一个地方出现。我整理了一下自己踩坑和帮别人排查的经验，基本集中在三种场景里：
场景一：打开同事发给你的项目。你本地没有这个项目，clone 下来之后 Android Studio 自动开始 Gradle Sync，Sync 可能都显示成功了，但一跑 Build 就报这个错。这种场景里，问题通常出在同事的compileSdk用的是 35，而你本地 SDK 里根本没有platforms\android-35这个目录。
场景二：手动升级了 compileSdk 版本。原来项目是compileSdk 34，你想用新 API，就把app/build.gradle里的版本改成了 35。改完点 Sync，结果 Build 阶段立刻报错。原因很简单：只改了数字，没让 SDK Manager 把 Platform 35 下载到本地。
场景三：命令行直接跑gradlew.bat assembleDebug。这种最常见于习惯用终端构建的人。Android Studio 在 Sync 的时候有自动补装 SDK 组件的能力，但命令行默认不会做这件事。你如果在命令行环境里直接构建，而本地没有对应 Platform，报错就会非常干脆。
1.2 报错信息的真实含义
要理解这个报错，先要明白android.jar是干什么的。
Android 应用编译的时候，你的代码会引用android.app.Activity、android.os.Bundle这些系统类。这些类不是随便从网上拉的，而是由 SDK 里对应版本的android.jar提供的。Gradle 在编译期会把android.jar加到编译类路径里，作用相当于 JDK 里的rt.jar。所以你看报错信息里的include path，指的就是编译时要引入的系统库路径。
当你的compileSdk被设置为 35，Android Gradle Plugin 就会去 SDK 目录下寻找platforms\android-35\android.jar。找不到，就报failed to load include path。说白了，这不是语法错误，也不是依赖冲突，就是一个简单的“文件不存在”问题。
1.3 哪些人更容易踩中这个坑
我总结了一下，遇到这个问题的人通常有以下特征：
- 刚装好 Android Studio 不久，SDK 里只有默认自带的几个 Platform，比如
android-34或者android-33。 - 电脑上有多个 Android SDK 目录，环境变量
ANDROID_HOME指向的是旧目录。 - 备份系统或者重装系统之后，SDK 是从旧硬盘直接拷过来的，目录不完整。
- 项目是别人维护的，
compileSdk版本高于你本地所有 Platform。
2. 根源拆解：SDK 明明在，为什么就是找不到 android.jar
2.1 compileSdk=35，Platform 35 却没安装
很多人对 SDK 的组成有误解，以为装了 Android Studio 就等于装了所有版本。实际上，Android Studio 安装包只附带一个默认的 SDK Platform。你新建项目时如果选了某个 API Level，它可能帮你补装；但如果是别人建好的项目直接拷过来，就不会自动补。
SDK Manager 里的组件分得很细：Platforms目录下只有一个版本对应一个android-XX文件夹，Build-Tools是独立的一套，Sources for Android XX又是另外一套。你需要的android.jar只存在于Platforms目录下对应的文件夹里。只装了 Build-Tools，或者只装了 Sources，都没用，android.jar不会自己出现。
2.2 local.properties 里的 sdk.dir 指错了位置
local.properties是 Android Studio 在项目根目录自动生成的一个文件，里面记录着本地 SDK 路径，关键字段是sdk.dir。这个文件不纳入版本管理，每个开发者机器上都不一样。
问题来了：如果你的 SDK 实际上装在D:\Android\Sdk，但local.properties里写的却是C:\Users\xxx\AppData\Local\Android\Sdk，那 Gradle 去找D:\Android\Sdk\platforms\android-35时当然找不到。报错信息里的路径可能不是真实存在的路径，而是配置里写错的那个路径。
我见过最夸张的一个例子，是从 Mac 上拷过来的项目，local.properties里还是/Users/xxx/Library/Android/sdk这种 Unix 格式路径。拿到 Windows 上当然一跑一个准。
2.3 环境变量把 Gradle 带偏了
ANDROID_HOME和ANDROID_SDK_ROOT这两个环境变量，在 Android 开发里是老演员了。很多教程让你安装完 SDK 后去系统环境变量里配置ANDROID_HOME，本意是方便命令行使用。但问题在于，环境变量指向的 SDK 目录和 Android Studio 里配置的 SDK 目录可能是两个地方。
Gradle 在解析 SDK 路径时，local.properties里的sdk.dir优先级最高；如果这个文件不存在或者没写，才会去看环境变量。有些老项目压根没生成local.properties，那 Gradle 就会跟着ANDROID_HOME走。一旦ANDROID_HOME指向一个残缺的 SDK，报错就会出现。
2.4 SDK 目录迁移和精简留下的后遗症
还有一类人，电脑磁盘不够用，发现platforms目录下全是“用不上”的旧版本，就手动删掉了几个文件夹，比如删了android-31、android-32，觉得反正没在用。结果下一个项目就要求compileSdk 32，立刻就报错。
另外，从别人那里拷贝的 SDK 也存在这种问题。网上下载的“绿色版 SDK”经常是精简过的，可能只有最新一个 Platform。这种 SDK 平时用着还行，一旦遇到版本跨度大的项目就非常容易出问题。不要问我是怎么知道的，我在一台测试机上吃过同样的亏。
3. 解法 A：把 android-35 Platform 装全，图形界面和命令行都来一遍
3.1 Android Studio SDK Manager 图形安装
这是最省心、也最不容易出错的方法。打开 Android Studio，按顺序走一遍：
- 点击菜单栏
Tools，选择SDK Manager。 - 在弹出的窗口里切到
SDK Platforms标签页。 - 在列表里找到
Android SDK Platform 35，勾选上。 - 点击右下角
Apply，等待下载完成。 - 完成后点
OK关闭窗口。
这里有个细节：列表里有好几项都带“35”，比如Android SDK Platform 35、Sources for Android 35、Google APIs等。你要勾选的是Android SDK Platform 35，没有这个基础包，装其他组件都没意义。Google APIs一般不用单独勾，除非项目明确用到。
安装完成后，去 SDK 目录下检查一下platforms\android-35\android.jar是否存在。如果存在，回到 Android Studio 重新 Sync 一次，再 Build，这个问题基本就消失了。
3.2 命令行 sdkmanager 精确安装
如果你习惯用终端构建，或者在 Android Studio 的 SDK Manager 里因为网络问题下载失败，可以改用命令行工具sdkmanager。
先找到sdkmanager的位置。Windows 上一般在：
你的SDK目录\cmdline-tools\latest\bin\sdkmanager.bat如果你安装了最新版 Android Studio，cmdline-tools通常都已经存在。打开终端，进入这个目录，执行：
sdkmanager.bat "platforms;android-35"如果你用的是 macOS 或 Linux，命令是：
sdkmanager "platforms;android-35"执行过程中如果提示需要接受 license，先运行：
sdkmanager.bat --licenses然后一路输入y接受全部协议。这一步一定要做，因为很多自动安装失败的原因就是 license 没接受，Gradle 的自动补装机制在这种情况下会静默放弃。
装完之后可以用下面的命令确认：
sdkmanager.bat --list_installed或者在 Windows 终端里用dir检查：
dir "你的SDK目录\platforms\android-35\android.jar"能看到文件，就说明装好了。
3.3 安装后的验证与 Gradle 缓存刷新
很多时候装完 Platform，回到 Android Studio 直接 Build 还是报错。别急着怀疑解法不对，大概率是 Gradle daemon 还在用旧的编译环境。我自己的操作顺序是：
- 关闭 Android Studio。
- 在终端执行
gradlew.bat --stop，把 Gradle daemon 停掉。 - 重新打开 Android Studio，执行
File > Invalidate Caches / Restart。 - 等待索引重建，再 Build。
这一套下来，90% 的“装完了还报错”都能解决。Gradle daemon 有时候会缓存旧的 SDK 路径信息，你不主动停掉它，它就一直按老记忆办事。
4. 解法 B：路径和配置问题的逐个修正
4.1 修正 local.properties 里的 sdk.dir
如果你已经确认platforms\android-35\android.jar在某个真实的 SDK 目录下存在，但 Android Studio 还是报错指向另一个路径，那就必须检查local.properties了。
打开项目根目录，找到local.properties，看sdk.dir的值是不是你实际 SDK 的路径。Windows 上的写法要格外注意转义，正确的例子是：
sdk.dir=C\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk这里反斜杠前面都加了转义符。如果你嫌麻烦，也可以把路径里的反斜杠改成正斜杠，Gradle 是认正斜杠的：
sdk.dir=C:/Users/你的用户名/AppData/Local/Android/Sdk如果你的项目没有local.properties，那就手动新建一个，把上面这一行填进去。
这里要劝一句：local.properties是本地环境配置，不要提交到 Git。每次在新机器上 clone 项目之后自己检查一下这个文件，是个好习惯。
4.2 理清环境变量的优先级
环境变量和local.properties之争，是这一类报错的深层原因。Android Gradle Plugin 解析 SDK 路径的顺序大致是：local.properties里的sdk.dir最优先，其次是ANDROID_HOME，最后是ANDROID_SDK_ROOT。
所以我建议你做一次完整排查：
在 Windows 终端里执行：
echo %ANDROID_HOME% echo %ANDROID_SDK_ROOT%看看这两个变量指向哪里。如果它们指向的 SDK 目录里没有android-35，就说明你被环境变量带到沟里去了。
处理方式有两种：要么把环境变量改成正确 SDK 的路径，要么直接在local.properties里明确写死sdk.dir。我比较推荐第二种，因为环境变量是全局性的，改错了会影响其他项目。local.properties只对当前项目生效，隔离性更好。
4.3 路径已经正确仍然报错时的进阶排查
有一种情况比较罕见，但也真实存在：android.jar文件确实存在，路径也正确，但 Gradle 就是读不了文件。
优先级从高到低排查三件事：
- 文件权限问题。Windows 上某些从压缩包解压出来的 SDK 文件夹会被系统标记为“来自其他计算机”，右键点击
android-35文件夹，选择“属性”，在“常规”标签页最下方看有没有“解除锁定”按钮，有的话点掉。 - 杀毒软件拦截。某些安全软件会把
android.jar当作可疑文件隔离。去杀毒软件的隔离区里翻一下，把 SDK 目录加入白名单。 - 磁盘写入保护。老旧的移动硬盘或只读权限的目录也会导致这种情况，把 SDK 拷到本地磁盘再试一次。
5. 解法 C：Gradle 自动下载缺失 Platform 的机制与应急降级
5.1 自动下载机制为什么会失灵
Android Studio 在 Sync 的时候，理论上会自动发现缺失的 SDK Platform，并弹出一个提示框让你确认下载。但实际使用中，这个机制经常“静默失败”。常见原因有三个：
- 网络环境限制，SDK 组件需要从远程仓库下载，下载被中断后没有重试提示。
- 之前点过“不再提示”，之后就一直不自动装了。
- 命令行构建模式下，AGP 不会主动触发 SDK 组件下载，直接报错。
所以不要依赖自动补装。发现问题之后，主动去 SDK Manager 或直接用sdkmanager安装，永远是最稳定的路径。
5.2 应急修改 compileSdk 降级
如果项目不依赖 API 35 的新特性，而你又急需把项目跑起来或打包，可以临时把compileSdk降到本地已有的 Platform 版本。
在app/build.gradle里：
android { compileSdk 34 defaultConfig { targetSdk 34 } }如果用 Kotlin DSL，也就是app/build.gradle.kts：
android { compileSdk = 34 defaultConfig { targetSdk = 34 } }注意：这只是应急。如果项目代码里使用了 API 35 才有的类或方法，降级之后会出现编译错误。到时候你会看到类似error: cannot find symbol的提示，那就没法靠降级逃避了，老老实实安装 Platform 35 才是正解。
5.3 命令行/CI 环境下的 SDK 预装
如果你在 CI 上构建 Android 项目，服务器往往是没有图形界面的，这个报错更容易出现。正确的做法是在构建脚本里先把需要的 Platform 装好。
Windows 批处理示例：
sdkmanager.bat --install "platforms;android-35" sdkmanager.bat --licenses gradlew.bat assembleDebugLinux/macOS 示例：
sdkmanager --install "platforms;android-35" yes | sdkmanager --licenses ./gradlew assembleDebug这一步相当于把本地手动安装的动作自动化了。CI 环境里不要指望 AGP 自动补装，自己动手才能保证每一次构建环境都是完整的。
6. 十分钟排查链路复盘与后续防坑习惯
6.1 五步走快速定位
如果你不想从头看文章，只看这一段就够了。遇到failed to load include path ... android-35\android.jar，按这个顺序排查：
- 看报错路径指向哪个 SDK 目录。记住这个路径，后面所有判断都以它为准。
- 打开 SDK Manager，检查 Android SDK Platform 35 是否已安装。没装就装上，装完重启 Android Studio。
- 检查 local.properties 里的 sdk.dir 是否和报错路径一致。不一致就改过来。
- 检查 ANDROID_HOME 和 ANDROID_SDK_ROOT 环境变量。确认没有指向一个残废的 SDK 路径。
- 确认 android.jar 文件真实存在。存在还报错，就执行 Invalidate Caches / Restart，并停掉 Gradle daemon。
这一套流程走下来，从发现问题到解决基本就是十分钟以内的事。
6.2 实战补充案例：路径里带空格的坑
我在排查过程中还见过一个很有意思的案例。有台机器的 Android SDK 装在D:\Program Files\Android\Sdk，路径里带了空格。部分老版本的 Gradle 和 NDK 对这种路径处理得不好，会间歇性报failed to load include path，有时候重新 Sync 一次又好了，过一阵又犯。
遇到这种问题，最省心的方案是把 SDK 挪到一个没有空格、最好是全英文的路径下，比如D:\Android\Sdk。路径带中文也是一样的道理，虽然不是百分百报错，但为了少浪费人生，建议一开始就避开。
6.3 容易混淆的相似报错一览
实际排查中，有几个报错长得不一样，根因却很接近。这里列个表，方便你对照：
| 报错信息 | 真实原因 | 处理方向 |
|---|---|---|
| failed to load include path ... android-35\android.jar | SDK 里缺 Platform 35，或 SDK 路径配置错误 | 安装 Platform 35，检查 local.properties / 环境变量 |
| Failed to find target with hash string 'android-35' | 构建系统按 compileSdk 找 Platform 35 找不到 | 同上，本质就是缺 Platform |
| Package android.content does not exist | android.jar 没进编译类路径，常见于缺 Platform 或依赖配置错误 | 检查 compileSdk 对应的 Platform 是否完整 |
| SDK location not found. Define a valid SDK location | 完全没有配置 SDK 路径 | 创建 local.properties 并填写 sdk.dir |
6.4 团队协作中的 SDK 版本同步习惯
最后说一个团队协作层面的建议。多人维护同一个项目时，compileSdk版本是所有开发者的硬性要求。你在代码里写了compileSdk 35，就意味着团队里每个人本机都要有 Platform 35。
我自己的习惯是在项目 README 里加一段“环境要求”，写清楚需要的 SDK Platform 版本。新建项目时，也会在提交代码前确认一下local.properties没有被误提交。如果团队经常换人，还可以在仓库里放一个local.properties.example文件，内容写好 sdk.dir 的格式说明，让新同事拷过去改一下路径就能用。
SDK 版本管理这种事，看起来是小事，但每次遇到failed to load include path的人都在同一块石头上绊倒。把这些防坑机制做在前面，省下的调试时间比想象中多得多。
我在实际处理这个报错时，最大的体会是：先看路径，再开 SDK Manager，最后才动配置文件。顺序反了容易越改越乱，尤其是 Windows 环境下，很多问题不是 SDK 没装，而是路径对不上。希望大家看到这个报错时能想起这篇文章，别再被它吓住。
