Android Studio Gradle 同步失败：Library 为 null 的通用排查指南

在 Android Studio 中执行 Gradle Sync 时，偶尔会遇到下面这类异常：

Cannot invoke "com.intellij.openapi.roots.libraries.Library.getUrls(
com.intellij.openapi.roots.OrderRootType)" because "library" is null

这条错误很容易让人第一时间怀疑 ~/.gradle 全局缓存损坏，但从异常所属模块看，它通常不是 Gradle 下载依赖时直接抛出的错误，而是 Android Studio 将 Gradle 返回的项目结构导入 IDE Workspace Model 时发生的空指针异常。

因此，正确的排查思路不是立即删除整个 Gradle 缓存，而是先确认失败发生在哪个阶段，再按影响范围从小到大处理。

一、先理解 Gradle Sync 的几个阶段

一次 Android Studio Gradle Sync 大致可以分为以下阶段：

1. 读取 settings.gradle、build.gradle、版本目录和插件配置。
2. 启动 Gradle Daemon，配置项目并解析依赖。
3. Gradle Tooling API 将模块、依赖、变体等模型返回给 Android Studio。
4. Android Studio 把模型转换为 IDE 的 Module、Library、SDK 和 Workspace Model。
5. IDE 更新索引、代码提示、资源模型和运行配置。

Library.getUrls(...) because "library" is null 通常发生在第 4 阶段。典型堆栈包含：

java.lang.NullPointerException
    at com.intellij.openapi.externalSystem.service.project.manage
        .LibraryDependencyDataService.importModuleLibraryOrderEntry(...)
    at com.intellij.openapi.externalSystem.service.project.manage
        .LibraryDependencyDataService.importData(...)
    at com.intellij.openapi.externalSystem.service.project.manage
        .ProjectDataManagerImpl.importData(...)

如果日志在异常前已经出现类似内容：

External project [...] resolution task executed in ... ms
Started setup of project '...'
Failed to import project structure

说明 Gradle 已经完成项目解析，失败点在 IDE 的项目结构导入阶段。此时直接删除全部 ~/.gradle/caches 往往代价很大，命中率却不高。

二、最重要的判断：Gradle 失败，还是 IDE 导入失败

1. 用项目 Wrapper 做最小验证

Windows：

.\gradlew.bat help --offline --no-daemon --stacktrace

macOS 或 Linux：

./gradlew help --offline --no-daemon --stacktrace

这个命令会配置整个项目和 buildSrc，但不会编译 APK。使用 --offline 还能验证现有 Gradle 分发包及本地依赖缓存是否足以完成项目配置。

如果结果是：

BUILD SUCCESSFUL

至少可以说明：

• Gradle Wrapper 能正常启动；
• Gradle 脚本能够完成配置；
• buildSrc 能够正常编译或复用缓存；
• 当前异常更可能位于 Android Studio 的导入层，而不是 Gradle 的基础缓存层。

需要注意，help 成功不等于所有构建任务都一定成功。它用于区分“Gradle 无法运行”和“IDE 无法导入模型”，而不是替代完整构建。

2. 查看 idea.log，不要只看同步面板的一行提示

在 Android Studio 中打开：

Help > Show Log in Explorer

然后在 idea.log 中搜索：

Library.getUrls
Failed to import project structure
Gradle sync failed
External project
Could not resolve
BUILD FAILED

判断规则如下：

三、为什么通常不应先删除 Gradle 全局缓存

Gradle 全局缓存通常位于：

Windows: %USERPROFILE%\.gradle\caches
macOS/Linux: ~/.gradle/caches

删除整个目录会产生以下影响：

• 所有项目重新下载依赖和插件；
• Gradle Wrapper、Kotlin DSL 和 transform 缓存需要重建；
• 内网 Maven、已下线仓库或临时凭据失效时，原本可构建的项目可能反而无法恢复；
• 无法针对性证明究竟是哪一层出了问题。

只有出现下列证据时，才应优先怀疑 Gradle 缓存：

• Could not resolve all files for configuration ...；
• JAR、AAR 或 POM 校验失败；
• ZIP/JAR 明确提示损坏；
• 同一个依赖在命令行构建中也持续失败；
• 删除某个依赖的局部缓存后可以重新下载并恢复。

即使确认是依赖缓存问题，也应优先删除具体 group、artifact 或 Gradle Wrapper 分发目录，而不是清空整个 .gradle。

四、推荐的最小化处理顺序

第一步：记录环境和完整堆栈

至少记录以下信息：

• Android Studio 完整版本和 Build 编号；
• 是否为 Canary、Nightly、Beta 或稳定版；
• Gradle、AGP、Kotlin、JDK 版本；
• 首次失败前是否升级过 IDE 或插件；
• idea.log 中第一处完整异常，而不是后续的 Suppressed a frequent exception。

后续相同异常可能被 IDE 折叠，只保留一句摘要，因此第一次完整堆栈最有价值。

第二步：执行 Wrapper 最小任务

.\gradlew.bat help --offline --no-daemon --stacktrace

• 命令失败：沿 Gradle 脚本、JDK、仓库和依赖方向排查。
• 命令成功：继续排查 Android Studio 项目缓存和版本回归。

必要时再执行一个真实但风险较低的任务，例如：

.\gradlew.bat :app:dependencies --configuration debugRuntimeClasspath

配置名需根据项目实际变体调整。

第三步：做交叉对照

以下对照非常有效：

1. 同一个 Android Studio 版本能否同步其他项目；
2. 同一个项目能否在较旧的稳定版 Android Studio 中同步；
3. 同一个项目能否通过命令行完成 Gradle 配置或构建；
4. 是否只有当前 IDE 版本、当前项目组合会失败。

如果其他项目在当前 IDE 中正常，而当前项目在旧版 IDE 中也正常，则全局 Gradle 缓存损坏的可能性明显降低。更应怀疑：

• 新版 Android Studio 的导入回归；
• 当前版本为该项目保存的 Workspace Model 状态损坏；
• 某种依赖模型触发了新版 IDE 的边界条件。

第四步：关闭 IDE，清理当前版本的项目级缓存

一般情况下，完全关闭 Android Studio 后，清理当前版本中与故障项目对应的项目级缓存，再重新打开项目同步，就可以解决该问题。

新版本 Android Studio 通常会为每个项目维护独立缓存，Windows 上常见位置是：

%LOCALAPPDATA%\Google\AndroidStudio<版本>\projects\<项目名>.<哈希>

操作前必须完全退出 Android Studio，确认没有同步或索引任务仍在运行。只删除与故障项目对应的目录，然后重新打开项目并同步。

这种处理比删除整个 Android Studio system 目录或 .gradle 全局缓存更精准，也不会影响所有项目。

第五步：使用稳定版 Android Studio 验证

如果问题只出现在 Nightly、Canary 或刚发布的新版本中，优先切回已经验证可用的稳定版本。IDE 内部的 LibraryDependencyDataService 空指针属于工具自身异常，项目配置可能只是触发条件，并不一定代表项目写错。

若旧版本正常、新版本稳定复现，应保留完整 idea.log，再向 Google/JetBrains Issue Tracker 报告。

第六步：必要时重建 .idea

如果清理当前版本的项目级缓存无效，可以在关闭 IDE 后备份并重建项目的 .idea 目录。

注意：.idea 可能包含团队共享的代码样式、运行配置、Gradle JVM 设置等内容。不要直接删除，应先备份或通过 Git 确认哪些文件受版本控制。

第七步：排查容易触发 Library 模型边界条件的依赖

重点检查：

implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])
implementation files('libs/example.aar')
implementation project(':some-module')

以及动态添加依赖的代码：

sdkList.each { sdk ->
    implementation sdk
}

检查内容包括：

• 本地 JAR/AAR 是否真实存在；
• AAR 是否能作为 ZIP 正常读取；
• classes.jar 和 AndroidManifest.xml 是否存在；
• 动态依赖列表中是否含有 null、空字符串或本地失效路径；
• 是否有同一路径被以不同形式重复添加；
• included build、composite build 或 buildSrc 是否生成了异常依赖模型。

可以临时将可疑依赖逐组注释后同步，用二分法确定触发项。但如果旧版 IDE 对完全相同的项目可以正常同步，仍应优先把它视为新版 IDE 的兼容性或健壮性问题。

五、什么时候使用 Invalidate Caches

File > Invalidate Caches 更适合处理：

• 索引不完整；
• 类明明存在但 IDE 报红；
• 搜索结果、资源引用或导航异常；
• 同步已经成功，但编辑器状态不一致。

对于明确发生在 ProjectDataManagerImpl 导入阶段的错误，优先清理当前项目对应的 IDE 缓存目录，通常比全局 Invalidate Caches 更容易控制影响范围。

六、常见误区

误区 1：看到 Sync 失败就删除 ~/.gradle

Sync 同时涉及 Gradle 和 Android Studio 两套系统。必须先根据日志确定失败层级。

误区 2：只看弹窗，不看 idea.log

同步面板常常只显示最后一层包装错误。完整调用栈才能判断是 Gradle、AGP 还是 IntelliJ Platform 导入层。

误区 3：同时删除 .idea、.gradle、IDE 缓存和构建目录

这样即使问题恢复，也无法知道是哪一步生效；如果没有恢复，还会引入大规模下载和重新索引成本。

误区 4：Nightly 版本出现空指针，一定是项目配置错误

项目配置可能触发异常，但 IDE 内部直接空指针通常意味着工具本身缺少边界保护。稳定版对照结果是重要证据。

七、快速决策表

八、可复用的排查记录模板

问题：Android Studio Gradle Sync 失败

Android Studio：
Build 编号：
发布通道：Stable / Beta / Canary / Nightly
Gradle：
AGP：
Kotlin：
Gradle JDK：

命令行验证：
gradlew help --offline --no-daemon --stacktrace
结果：成功 / 失败

idea.log 关键阶段：
- Gradle resolution：成功 / 失败
- Project structure import：成功 / 失败
- 第一处完整异常：

交叉验证：
- 其他项目在当前 IDE：成功 / 失败
- 当前项目在旧版 IDE：成功 / 失败

本地依赖：
- JAR/AAR：有 / 无
- 动态依赖：有 / 无
- composite build/buildSrc：有 / 无

已尝试：
1.
2.
3.

最终根因：
最终处理：

九、结论

遇到 Library.getUrls(...) because "library" is null 时，应优先把它视为 Android Studio 在导入 Gradle Library 模型时发生的异常，而不是直接认定 Gradle 全局缓存损坏。

实践中最常见、成本最低且通常有效的处理方式是：完全退出 Android Studio，只清理当前 Android Studio 版本下与故障项目对应的项目级缓存，然后重新打开项目执行 Gradle Sync。 不必一开始就删除 .idea 或 Gradle 全局缓存。

最可靠的处理路径是：

看完整 idea.log
    -> 用 Gradle Wrapper 验证项目配置
    -> 做 IDE 版本和其他项目交叉对照
    -> 清理当前项目的 IDE 缓存
    -> 使用稳定版验证
    -> 最后才处理具体依赖或 Gradle 局部缓存

按故障层级逐步缩小范围，既能更快恢复开发环境，也能避免无依据地清空全局缓存。