我去年年底接手一个从同事那里拷过来的Android项目第一件事就是被这个报错糊了一脸failed to load include path C:\Users\xxx\AppData\Local\Android\Sdk\platforms\android-35\android.jar。当时整个人是懵的android.jar就在那个路径躺着文件管理器和命令行都能正常读取可Android Studio编译就是卡死在这条include path上。后来我把项目从构建缓存到SDK目录整个排查了一圈才搞明白这类报错背后其实藏着好几种完全不同的病根。如果你也正在被这个报错折磨这篇博文应该能帮你少走很多弯路。不管你是刚装好Android Studio的新手还是被历史项目折腾的老手只要编译时出现failed to load include path尤其是路径末尾指向android-35\android.jar都可以照着下面的思路一步步定位和解决。我会拆开讲清楚报错原因、排查顺序以及我从实际踩坑中总结出来的处理顺序和注意事项。1. 报错现场与底层原因拆解1.1 报错信息长什么样很多人在搜索引擎里看到的是简化版本实际编译时AS的Build窗口输出的日志会比标题里那段长得多。完整报错一般长这样Execution failed for task :app:compileDebugJavaWithJavac. Could not open init script C:\Users\xxx\AppData\Local\Temp\asd....gradle: failed to load include path C:\Users\xxx\AppData\Local\Android\Sdk\platforms\android-35\android.jar for project :app.关键信息有三个一是失败任务通常是compileDebugJavaWithJavac这个Java编译任务二是Android Studio在临时目录生成并加载一个init脚本三才是我们关心的核心——加载android.jar时失败。日志第一行往往被忽略实际上它决定了你排查的方向。1.2 android.jar在编译链路里扮演的角色要彻底解决这个报错得先理解android.jar是干什么的。简单来说它是Android框架层的结构描述文件包含android.app.Activity、android.view.View这些公开API的类定义和接口。我们在Java/Kotlin代码里写import android.app.Activity时javac需要依靠android.jar来确认这些类的存在和方法签名然后才能把源码编译成class文件。Gradle编译时会把对应compileSdkVersion的android.jar通过include path参数传递给javac。之所以叫include path而不是classpath是因为这个jar只用于编译验证不会真的打进APK真正运行时用的是设备/模拟器里的framework。官方文档里把这种行为叫“编译时引用运行时剥离”所以platforms\android-35\android.jar必须存在且可读否则android.*开头的所有import全部会解析失败。1.3 为什么报错信息这么“粗鲁”Gradle的报错内容确实不友好它没有直接说“你SDK没装”或者“你路径配错了”而是抛出一个泛化的“failed to load include path”。这背后原因是Gradle在解析init脚本时把路径当作一个资源来加载任何导致加载失败的情况文件不存在、权限不足、路径编码问题、文件被锁都会抛出同一类错误。这意味着报错信息本身只能告诉你“加载某个路径失败”不能告诉你为什么失败。所以我一直强调看到这个报错先别急着改代码第一反应应当是检查路径对应的文件是否存在其次才是考虑权限、缓存和版本兼容问题。没有这个判断顺序很容易像无头苍蝇一样乱试。2. 问题根源对症自查根据我自己的踩坑经历和帮朋友解决问题的经验failed to load include path这个报错至少能拆出五类常见根源每类的处理方式完全不一样自行排查时建议按下面的顺序逐项检查。2.1 最常见SDK Platform根本没装这个原因占了大概一半的比例。很多人新建项目时compileSdkVersion选了35但SDK Manager里压根没有安装“Android SDK Platform 35”。新建项目时Android Studio会提示安装缺失的SDK但如果你在命令行同步、或者从别的电脑拷贝项目时自动触发了同步Gradle并不会自动帮你下载Platform只会抛这个加载失败。另一种情况是Platform装了但是只装了Sources for Android 35没勾选真正的Platform。SDK Manager的SDK Platforms选项卡中每一项下展开Show Package Details才能看到子选项很多人只勾了“Sources”、漏勾了“Android SDK Platform 35”视觉效果上看着像装了实际连platforms\android-35这个文件夹都没有。2.2 路径指向错乱如果Platform确实存在那就要检查路径了。local.properties文件里有一个sdk.dir它记录着当前项目使用的Android SDK路径。团队协作时如果local.properties被误提交到Git仓库别人拉下来后这个路径还是你本机的路径自然找不到文件。我自己就遇到过同事把文档提到一半的项目传到Git结果local.properties里写的是他自己的用户名我这边跑起来就报错。还有一种是环境变量ANDROID_HOME或ANDROID_SDK_ROOT指向了旧SDK目录而Android Studio读取路径的顺序又和环境变量相关。特别是用命令行执行Gradle任务时环境变量优先级常常高于local.properties最终指向一个没有android-35的旧目录。2.3 缓存与临时文件污染Gradle是个缓存狂魔它会缓存大量中间产物和处理过的脚本。如果.gradle缓存目录里残留了旧的路径映射或者上次构建时某个jar被部分写入后进程被杀再次构建时就可能读到一个坏掉的路径引用。这类问题最典型的表现是android.jar存在、路径正确、SDK Manager里也显示已安装但每次build都报同样错误Clean Project也没用。这种时候就轮到“Invalidate Caches”和手动删缓存出场了。2.4 JDK/AGP/Gradle版本三角关系Android构建工具链里有一个隐藏的“三角关系”Android Gradle PluginAGP版本、Gradle版本、JDK版本必须互相兼容。AGP 8.x要求JDK 17AGP 7.x要求JDK 11新版Android Studio自带JBRJetBrains Runtime本质上是JDK版本可能和项目的AGP不匹配。如果版本组合不对Gradle在编译早期阶段就可能出现奇奇怪怪的加载错误include path加载失败也是其中之一。尤其是从旧项目升级到新版Android Studio后AS默认给项目配的是自己内置的高版本JDK而项目里还是老的AGP这种隐形不兼容往往以“路径加载失败”的假象出现实际上原因根本不是路径。2.5 中文路径与杀软Windows用户名的中文问题算是特色坑。如果系统用户名是“张三”Android SDK默认会出现在C:\Users\张三\AppData\Local\Android\Sdk这部分路径里含中文。某些Gradle版本在解析非ASCII路径时会出现编码错乱编译时读取include path就会失败。杀毒软件也经常掺一脚尤其Windows Defender会在文件第一次被频繁读取时做实时扫描。如果SDK目录里大量jar被扫描、暂时锁定编译线程读取android.jar就会失败表现就是“刚才还好好的重启电脑后第一次编译必挂”。为了方便对照我列了一个简单的速查表故障表现最可能根因优先排查方向platforms目录下没有android-35文件夹SDK Platform 35未安装SDK Manager勾选安装文件存在但报错local.properties或环境变量路径错误核对sdk.dir和ANDROID_HOME路径正确且文件存在Clean无效Gradle缓存污染Invalidate Caches 删.gradle刚升级或刚换新AS后出现JDK/AGP/Gradle版本不兼容对齐工具链版本Windows中文用户名或杀软编码/文件锁定迁移SDK路径或加白名单3. 最细解决方案一步步照着做下面按排查顺序给出一套完整的解决方案每一步都有具体的操作路径。你不需要全做完从第一步开始做完同步一次能过就直接结束。3.1 第一步确认目标android.jar存在先做最原始、最直接的检查这个报错里提到的文件到底在不在。打开文件资源管理器进入Android SDK目录。默认路径一般是C:\Users\你的用户名\AppData\Local\Android\Sdk或者你自定义的SDK路径找到platforms文件夹看看里面有没有android-35文件夹再点进去确认android.jar是不是真实存在。不要只看文件夹要看文件本身。如果文件夹或文件缺失打开Android Studio工具栏里的SDK Manager新版AS在欢迎页或Settings里的Languages Frameworks Android SDK切到SDK Platforms选项卡勾选Android SDK Platform 35然后点Apply安装。这里有个非常容易踩的细节要展开Show Package Details确认勾选的是“Android SDK Platform 35”本身而不是旁边的“Android SDK Sources 35”或“Google APIs”这类扩展包。只勾Sources不会生成platforms\android-35\android.jar。3.2 第二步对齐SDK路径与环境变量文件存在的话接着检查Gradle实际会读取哪个SDK路径。用记事本打开项目根目录下的local.properties看sdk.dir这一行sdk.dirC\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk注意Windows下反斜杠要写成双反斜杠转义。把这个路径和实际SDK路径逐一比对确认完全一致。同时打开命令行分别执行echo %ANDROID_HOME% echo %ANDROID_SDK_ROOT%如果这两个环境变量存在且指向的路径和local.properties不一致建议统一改成同一个路径。在Windows上设置用户环境变量然后重启Android Studio让新环境变量生效。对从其他电脑拷贝过来的项目还要注意local.properties是不是被一起拷过来了。如果里面写的是旧电脑的用户名果断改成当前机器的SDK路径或者直接删除这个文件让Android Studio重新生成一份。3.3 第三步清理项目缓存强制重建路径确认无误后还是报错那就是缓存问题。Android Studio的缓存和Gradle的缓存都要清。先在AS里执行Build Clean Project这只能清理编译产物对Gradle的init脚本缓存完全无效。接下来需要关闭Android Studio。打开项目根目录删除以下文件夹如果有.ideabuildapp/build.gradle进入用户目录下的.gradle文件夹默认是C:\Users\你的用户名\.gradle把caches子文件夹重命名或者删除。注意这会让你下次构建时重新下载依赖国内网络环境下建议先配好Gradle镜像源否则重下依赖可能要等很久。重新打开Android Studio等待Gradle Sync完成再编译一次。这套“删四个文件夹删caches”的操作能解决绝大多数缓存导致的“文件明明存在却加载失败”的问题。如果过程中下载依赖特别慢可以给项目的build.gradle或全局init.gradle配置阿里云镜像源这个对国内开发者几乎是标配操作。3.4 第四步核对JDK与Gradle版本组合缓存清了还报错就要怀疑工具链版本兼容性了。按下图路径打开设置File Project Structure SDK Location查看Gradle JDK设置。常见组合参考AGP版本Gradle最低版本JDK要求AGP 8.0Gradle 8.0JDK 17AGP 7.xGradle 7.xJDK 11AGP 4.xGradle 6.xJDK 8或11如果你的AGP是8.x但Gradle JDK指向的是JDK 11或者反过来项目里还是老AGP但JDK被设成了21就先把这个对齐。Android Studio 2023以后自带的是JBR 17或21对大多数新项目够用但老项目建议手动下载一个JDK 11并在Project Structure里指定。另外检查一下gradle-wrapper.properties里的distributionUrl对应的Gradle版本和AGP版本匹配了这个三角关系才稳定。3.5 第五步终极重置必要时如果以上四步全走完还是同样报错说明问题藏得比较深需要做一次“从零开始”级别的重置。具体操作是把全局Gradle缓存彻底清空删除C:\Users\你的用户名\.gradle整个目录然后重新打开项目让Gradle完全重新初始化。这一步代价很大全部依赖重新下载慢的话半小时起步所以一定放在最后。另一个可以考虑的路径是把compileSdkVersion改成另一个已存在的版本比如35降到34重新同步后再改回来。这个操作有时候能绕开由于SDK Platform 35文件本身损坏导致的问题——如果你发现35这个目录存在但就是读不了很可能platform没下载完整重装一次Platform也行。4. 疑难杂症专项排查实录4.1 “SDK明明在却说找不到”的几种诡局有一个情况特别折磨人android.jar就在那里路径也完全正确文件管理器打开毫无障碍但Gradle就是报错。我最后发现问题是local.properties里路径末尾多了一个空格。千万别笑这种肉眼几乎看不出来的字符错位非常常见尤其是Windows记事本编辑过的文件。另一种是路径大小写问题。Windows文件系统不区分大小写但Gradle在某些场景下做字符串匹配时是区分的。如果你的SDK路径实际是D:\android-sdk但local.properties里写成了D:\Android-SDKWindows下文件访问没问题Gradle的路径解析却可能出岔子。修正大小写后问题立刻消失。还有一个更隐蔽的Gradle读取android.jar并不是freestyle的文件读取它是在解析init脚本时把路径当作配置项加载。如果项目的build.gradle里有脚本动态拼接了这个路径比如用了${sdkDir}这种占位符占位符值为空时就会生成一个不存在的路径。这时候要找的是Gradle脚本里的路径拼接逻辑而不是SDK本身。4.2 第一遍编译必失败、第二遍就好的怪现象这个现象我最早在一次Windows服务器上构建时遇到后来帮一个网友排查时又碰到一次。规律是电脑重启后第一次打开AS编译必定报include path加载失败然后什么都不改再Build一次又成功了。这类“周期性必现”的问题十有八九和杀毒软件的文件扫描锁有关。第一次编译时android.jar刚从磁盘读入杀毒软件实时监控扫描这个文件在扫描完成前Java进程尝试打开文件流被拒绝于是报加载失败。第二次编译时文件已经在系统缓存里或杀软白名单里就能正常读取。解决方式是把整个Android SDK目录加入杀毒软件排除列表。Windows Defender的操作为设置 更新和安全 Windows安全中心 病毒和威胁防护 管理设置 排除项把SDK目录加进去。如果公司内网装了第三方杀软找到白名单设置同样处理。4.3 从一个报错牵扯出的版本升级连锁问题有些情况下这个报错只是表象真正的病根是AS版本或依赖库升级后SDK版本没跟上。尝试把一个库升级到最新版本后库内部强制要求compileSdkVersion35但本地没装Platform 35从而报错。这种场景下错误信息里的路径确实指向android-35但你项目里可能没有任何文件写着35这个数字——依赖库通过传递依赖把编译SDK版本抬上去了。遇到这种情况最简单的方法是项目根目录的build.gradle里给所有子项目统一指定android.compileSdkVersion或者直接改成依赖库要求的版本并安装对应平台。一个更保险的做法是在gradle.properties里加上android.suppressUnsupportedCompileSdk35然后规划升级SDK Platform到35。注意这个属性只是压制警告真正编译还是要靠安装Platform 35。4.4 排查流程速查表把整个分析总结成一张可直接参考的排查表操作命令/位置什么时候做检查platforms\android-35\android.jar是否存在文件资源管理器任何情况下第一步安装缺失的PlatformSDK Manager SDK Platforms Android SDK Platform 35文件不存在时核对local.properties的sdk.dir项目根目录文件存在且报错时检查环境变量ANDROID_HOME/ANDROID_SDK_ROOT命令行 echo命令行构建或路径不一致时清理项目缓存删除.idea、build、.gradle目录路径正确但反复报错时清理全局Gradle缓存C:\Users\用户名.gradle\caches项目缓存清理无效时对齐JDK/AGP/Gradle版本Project Structure Gradle JDKgradle-wrapper.properties刚升级AS或老项目时杀软排除SDK目录Windows安全中心/第三方杀软出现周期性失败时我自己后来养成了个习惯每次新建或接手项目第一件事就是看一眼local.properties和SDK Manager里安装的Platform版本避免等编译到一半才被这种报错教做人。工具链这东西靠经验记住一套固定的检查顺序比每次瞎试高效得多。如果是团队协作项目建议把local.properties加进.gitignore这个文件本来就属于本机配置不应该提交到版本库。我之前被同事提交的local.properties坑过一次之后对所有项目的第一轮改动就是确认git忽略规则从源头上杜绝路径错乱的问题。