Gradle构建报错，锁定依赖后执行成功的原因排查

可能的原因 #

• 动态版本解析延迟：如果依赖声明用了动态版本（比如implementation 'com.example:lib:+'或latest.release），未锁定时Gradle会在构建时远程查询最新版本，这个查询过程可能滞后于编译任务启动，导致编译时依赖还未就绪；锁定后直接使用build.lock里的精确版本，跳过远程查询，依赖解析瞬间完成。
• 依赖缓存损坏：本地Gradle缓存中该依赖的元数据或jar包损坏，未锁定时Gradle尝试复用缓存失败；锁定依赖时，Gradle会强制校验并下载build.lock指定的精确版本，自动修复缓存问题。
• 依赖冲突调解异常：未锁定时，Gradle会自动调解依赖冲突（比如同依赖不同版本），但调解过程可能出现逻辑偏差，导致最终引入的版本缺失所需类；锁定后固定版本，跳过冲突调解，直接使用验证过的可用版本。
• 多模块构建时序偏差：多模块项目中，未锁定依赖时模块间的依赖解析顺序可能不稳定，导致某个模块编译时依赖的其他模块还未完成依赖导入；锁定后依赖版本固定，Gradle能更稳定地规划任务执行顺序。

关于「编译时依赖尚未可用」的判断 #

你的猜测方向是对的，但更准确的描述是：未锁定依赖时，依赖解析的结果可能未在编译任务启动前完全确定，或者依赖的下载/导入过程滞后于编译任务执行。Gradle理论上会保证编译任务等待依赖解析完成，但如果依赖声明存在歧义（动态版本、冲突依赖），可能导致解析过程出现延迟或异常，使得编译任务拿到的依赖信息不完整，从而触发unresolved reference。

Gradle构建与依赖锁定核心流程 #

常规构建（未锁定依赖） #

1. 初始化阶段：读取settings.gradle，确定参与构建的模块。
2. 配置阶段：解析各模块的build.gradle，处理依赖声明，远程查询动态版本/范围的实际版本，解决依赖冲突，生成最终依赖列表。
3. 执行阶段：按任务依赖顺序执行编译、测试等任务，先下载缺失的依赖到本地缓存，再启动编译。

依赖锁定构建 #

1. 生成锁定文件：执行./gradlew dependencies --write-locks时，Gradle在配置阶段解析所有依赖的精确版本，将这些版本写入build.lock（或模块级gradle.lockfile）。
2. 使用锁定文件构建：开启依赖锁定后，Gradle在配置阶段直接读取build.lock中的精确版本，跳过远程版本查询和冲突调解步骤，直接下载指定版本依赖，再进入执行阶段。

排查建议 #

• 检查原依赖声明是否使用了动态版本，若有，建议替换为锁定后的精确版本。
• 执行./gradlew dependencies查看未锁定时的依赖树，确认是否存在依赖冲突。
• 清理本地Gradle缓存（删除~/.gradle/caches目录）后重新构建，排查缓存问题。

内容的提问来源于stack exchange，提问作者TFJ