必须提交 gradle.lockfile，它是构建契约而非缓存，记录各配置的精确依赖坐标与校验值，保障CI、新环境等场景依赖一致；多模块需每个子模块单独提交，且提交前须运行--write-locks、检查ignoreFailures及清除动态版本。

要提交，而且必须提交。不提交 gradle.lockfile，依赖锁定机制就完全失效——Gradle 会退回到动态解析依赖的行为，构建漂移风险照旧。

为什么必须提交 gradle.lockfile

锁文件不是缓存，而是构建契约：它记录了每个配置（implementation、testImplementation、runtimeClasspath 等）在当前环境解析出的**精确坐标 + 校验值**。CI 构建、新同事拉代码、甚至你换电脑重装环境，都靠这个文件还原一致的依赖树。

不提交的后果很直接：

• CI 流水线每次构建都可能拉到不同小版本（比如 com.squareup.okhttp3:okhttp:4.12.0 → 4.12.3），哪怕你写死的是 4.12.0
• 本地构建成功，别人拉下来报 Could not resolve ...，因为远程仓库里那个“刚好能解析”的版本已被撤回或限流
• 安全扫描工具无法比对已知漏洞版本，因为锁文件缺失导致依赖图不可信

哪些情况可以不提交（极少数例外）

绝大多数项目都应无条件提交。只有以下两类场景可酌情不提交，且需团队明确约定：

GitHub操作助手

用大白话操作当前项目的 Git/GitHub——配置 GitHub（装 gh CLI + 登录 + 建仓库）、备份、拉取下载、查询历史、回滚代码、管理分支。当用户用日常语言表达 git 意图时触发（例如"git备份一下""git下载项目""git拉下来""git看看我改了啥""git回退到上一个版本""git新建个分支搞新功能""git合并到主分支""git

下载

• 纯库项目（如开源 SDK），对外只发布 .jar/.aar，不提供可构建源码 —— 此时使用者本就不该运行 ./gradlew build，锁文件无意义
• 高度动态的原型项目（如内部 PoC），依赖每天都在试错性更换，且明确接受构建不可复现 —— 但此时应禁用锁定，而非留着未提交的锁文件

注意：gradle.lockfile 是按模块生成的（例如 :app/gradle.lockfile、:lib/gradle.lockfile），多模块项目中**每个子模块的锁文件都要单独提交**，漏一个就会导致构建失败。

提交前必须检查的三件事

提交不是简单 git add gradle.lockfile 就完事。容易被忽略的关键点：

• 确认已运行过 ./gradlew dependencies --write-locks，且命令执行成功（无 ERROR 或 WARN 报告“failed to lock”）
• 检查 gradle.properties 中是否设置了 org.gradle.dependency-locking.ignoreFailures=false（默认是 false，但显式声明更稳妥）
• 确保 build.gradle 或 settings.gradle 中没有残留 1.+、latest.release 这类动态版本 —— 它们会让锁定直接失败，而错误可能被静默吞掉

最后提醒一句：锁文件一旦提交，后续所有依赖变更（升级、降级、新增）都必须重新运行 --write-locks 并提交更新后的文件。跳过这步，等于把锁文件当摆设。