mavenLocal()必须放在repositories首位，因Gradle按声明顺序查找依赖且找到即停；它指向~/.m2/repository，确保mvn install的SNAPSHOT或私有构件被优先命中，否则将跳过本地直接访问远程仓库。
Gradle配置企业内部Maven仓库的正确顺序
必须把 mavenLocal() 放在第一位，否则本地已安装的 SNAPSHOT 或私有构件永远不会被命中。企业仓库（如 Nexus、Artifactory）紧随其后，最后才是镜像或中央仓库。Gradle 按声明顺序查找依赖，找到即停，顺序错一个，就可能绕过你刚 mvn install 进去的调试包。
典型配置如下：
repositories {
mavenLocal()
maven {
url "https://nexus.example.com/repository/maven-releases/"
credentials {
username = project.findProperty("nexusUsername") ?: ""
password = project.findProperty("nexusPassword") ?: ""
}
}
maven {
url "https://nexus.example.com/repository/maven-snapshots/"
credentials {
username = project.findProperty("nexusUsername") ?: ""
password = project.findProperty("nexusPassword") ?: ""
}
}
maven { url "https://maven.aliyun.com/repository/public" }
mavenCentral()
}
- 两个内部仓库（releases/snapshots）要分开声明，避免权限或策略冲突
-
credentials不写死在脚本里，用project.findProperty()从命令行或gradle.properties读取 - 如果内部仓库启用了 HTTPS 但证书非权威 CA 签发，需额外配置
insecureHttpProtocol = true（仅限测试环境）
为什么 mavenLocal() 必须放在最前？
它指向的是 Maven 默认本地仓库路径（~/.m2/repository），不是 Gradle 自己的缓存目录（~/.gradle/caches/...）。当你在模块中执行 mvn clean install，生成的 .jar 和 .pom 就落在那里。Gradle 只有在 mavenLocal() 声明靠前时，才会优先扫描这个目录——否则它直接跳到远程仓库，根本不会看本地有没有。
常见错误现象：
- 明明
mvn install成功了，但./gradlew build报Could not resolve com.example:my-lib:1.0.0-SNAPSHOT - 改了本地库代码，重新 install 后，Gradle 仍用旧版本——因为没触发重新解析，或
mavenLocal()被放到了mavenCentral()后面
企业仓库 URL 和路径细节容易踩的坑
很多公司 Nexus 配置了多层 repository group（如 company-public），但实际构件只发布在具体 repo（如 company-releases）下。直接配 group 地址可能导致元数据不全、SNAPSHOT 解析失败。
检查要点：
- 打开浏览器访问
https://nexus.example.com/repository/maven-releases/，确认能列出目录且包含com/example/...路径 - 查看该仓库是否启用
Release/Snapshot策略，并与你的依赖坐标版本后缀（-SNAPSHOT）匹配 - URL 末尾不要加
/——虽然多数情况自动处理，但某些 Nexus 版本会因重定向失败导致 401 或 404 - 若使用自签名证书，Gradle 7+ 默认拒绝 HTTP，也拒绝不信任的 HTTPS；此时需在
gradle.properties中添加systemProp.javax.net.ssl.trustStore=...，而非降级用 HTTP
离线构建和 CI 环境下的关键约束
CI 流水线（如 Jenkins、GitLab CI）通常不挂载开发者本机的 ~/.m2，所以 mavenLocal() 在那里基本无效。这时必须确保所有依赖都可从企业仓库拉取，且不能依赖本地 install 的临时构件。
实操建议：
- CI 脚本中显式设置
GRADLE_USER_HOME并清空缓存，避免误用旧缓存干扰验证 - 对内部 SNAPSHOT 依赖，建议在 CI 中禁用动态版本（如
1.0.0-SNAPSHOT），改用时间戳格式（1.0.0-20261019.082345-1）或启用dependencyLocking锁定解析结果 - 若企业仓库未开启元数据聚合（
maven-metadata.xml），Gradle 无法解析版本范围（如[1.0,2.0)），只能用精确版本
真正麻烦的从来不是加几行配置，而是当某天 build.gradle 里多了一个 mavenCentral() 在 mavenLocal() 前面，或者 Nexus 的 maven-snapshots 仓库被误设为只读——这些细节不会报错，只会让依赖悄悄走错路。
