离线构建生效需满足两个前提：本地已缓存全部依赖且Gradle发行版就位；仅勾选Offline work不保证生效，必须状态栏显示“Gradle offline mode is enabled”，并确保此前已成功在线sync，使implementation和classpath依赖均存入~/.gradle/caches/。
Gradle 离线构建不是“一键开启就能用”的功能，它依赖两个前提：本地已有全部依赖缓存 + Gradle 发行版已就位。否则开启后直接报 Could not resolve 或 Could not install Gradle distribution 错误。
怎么确认离线模式已生效
Android Studio 状态栏出现 Gradle offline mode is enabled 提示，才是真生效。仅勾选设置里的 Offline work 复选框，不代表当前构建会走离线——必须确保此前已成功在线同步过一次，所有 implementation 和 classpath 依赖都进过本地缓存（路径通常是 ~/.gradle/caches/modules-2/files-2.1/）。
命令行下验证更直接：./gradlew --offline build —— 如果失败，错误里出现 Could not resolve，说明某个依赖没缓存；./gradlew --offline -v —— 如果能正常输出版本号，说明 Gradle 二进制本身已就位，问题只在依赖侧。
Gradle wrapper 的 distributionUrl 怎么改成本地路径
编辑项目根目录下的 gradle/wrapper/gradle-wrapper.properties，把 distributionUrl 改成 file:// 协议的绝对路径：
distributionUrl=file:///Users/yourname/.gradle/wrapper/dists/gradle-8.3-all.zip
注意要点：
- Windows 路径需用正斜杠或双反斜杠，例如：
file:///D:/gradle/gradle-8.3-all.zip - 路径必须指向解压前的
.zip文件，不是解压后的目录 - 文件必须真实存在，且权限可读；AS 同步时不会校验，但构建时会因找不到文件而卡在
Could not install Gradle distribution - 推荐用
-all.zip而非-bin.zip，避免离线时 IDE 无法跳转源码或查文档
为什么开了离线还报 Could not resolve
这是最常踩的坑：以为开了离线就万事大吉，其实 Gradle 只是跳过远程仓库检查，但不会帮你补缺失的依赖。常见原因有：
- 项目第一次打开，没点过
Sync Now，~/.gradle/caches/下压根没有对应模块 - 依赖用了
SNAPSHOT版本，且上次在线构建后远程有更新，本地缓存被标记为“过期”，离线时 Gradle 拒绝使用（即使文件还在） -
build.gradle里新增了依赖，但没重新在线 sync 过 - 用了自定义 Maven 仓库（如私有 Nexus），其 URL 没加进
mavenLocal()或本地镜像未配置
补救方法只有一次：断网前，先确保 ./gradlew build 能完整跑通；或者临时连网，执行 ./gradlew --refresh-dependencies build 强制拉全量。
离线构建时 plugins 和 dependencies 的区别对待
Gradle 7.0+ 开始，plugins { } 块和 dependencies { } 块的解析机制不同：
-
plugins块里的插件（如com.android.application）必须通过插件仓库解析，离线时若没缓存，会直接失败，且不走mavenLocal() - 而
dependencies块默认支持mavenLocal()，只要你在repositories里显式声明了它，就能从~/.m2/repository或自定义路径读取
所以，如果你导出过本地 Maven 仓库，记得在 build.gradle 顶部加上：
repositories {
mavenLocal()
// 其他仓库可注释掉
}
但对 plugins 块无效——它只认 pluginManagement { repositories { } }，这个块也得提前缓存好插件 JAR（通常随 AS 自动完成，但纯 CLI 构建需手动处理）。
离线构建真正难的不是开关，而是依赖状态的确定性。每次换环境、升级 AGP 或添加新库，都要重新验证缓存完整性，否则“离线”只是个自我安慰的假象。
