单Gradle构建文件配置多个GitLab Maven仓库时依赖解析失败

问题根因 #

你碰到的单仓库配置正常、一旦配置超过1个私有仓库就全量构件解析失败的问题，本质是两个机制叠加导致的：

• Gradle默认的凭证匹配逻辑存在缺陷：同一repositories块下多个使用HttpHeaderCredentials的私有仓库，不会为每个仓库独立绑定认证规则，会将第一个注册的凭证全局化，导致后续其他仓库的请求要么不携带认证头、要么错配凭证，触发403响应。Gradle对这类私有仓库的权限类错误不会直接提示403状态，会统一返回找不到对应jar包的误导性报错。
• GitLab项目级Maven仓库的路由逻辑：每个项目ID对应的仓库是完全独立的，不存在跨项目的构件索引，只要某个仓库的认证头不匹配，就会直接返回错误，不会做兜底的构件路径匹配。

可落地配置调整方案 #

1. 为每个仓库独立绑定认证规则，避免凭证冲突 #

不要把凭证配置抽到全局层，在每个maven{}代码块内独立写对应的凭证和认证逻辑，同时通过认证域的绑定，强制Gradle把正确的凭证匹配到对应请求上：

repositories {
    // 第一个项目仓库
    maven {
        name = 'project-1'
        url = uri("https://gitlab.com/api/v4/projects/项目1的实际ID/packages/maven")
        credentials(HttpHeaderCredentials) {
            name = 'Private-Token'
            value = System.getenv("你的GitLab访问Token环境变量")
        }
        authentication {
            header(HttpHeaderAuthentication) {
                // 显式指定认证绑定的域，避免Gradle全局串配凭证
                realm = "gitlab.com"
                host = "gitlab.com"
            }
        }
    }
    // 第二个项目仓库
    maven {
        name = 'project-2'
        url = uri("https://gitlab.com/api/v4/projects/项目2的实际ID/packages/maven")
        credentials(HttpHeaderCredentials) {
            name = 'Private-Token'
            value = System.getenv("你的GitLab访问Token环境变量")
        }
        authentication {
            header(HttpHeaderAuthentication) {
                realm = "gitlab.com"
                host = "gitlab.com"
            }
        }
    }
    // 第三个项目仓库
    maven {
        name = 'project-3'
        url = uri("https://gitlab.com/api/v4/projects/项目3的实际ID/packages/maven")
        credentials(HttpHeaderCredentials) {
            name = 'Private-Token'
            value = System.getenv("你的GitLab访问Token环境变量")
        }
        authentication {
            header(HttpHeaderAuthentication) {
                realm = "gitlab.com"
                host = "gitlab.com"
            }
        }
    }
    // 保留Maven中央仓库作为公共依赖兜底
    mavenCentral()
}

注意：如果三个项目使用同一个有跨项目访问权限的Token，不需要拆分为多个环境变量，只要保证每个仓库的凭证块是写在自己的maven{}块内部，不要提到repositories外层全局定义，就能避免凭证串配的问题——多数人踩坑就是把凭证抽成全局变量，导致多仓库时凭证只匹配第一个注册的仓库，触发凭证串配的问题。

2. 关闭错误缓存避免残留干扰 #

Gradle默认会把私有仓库返回的“找不到构件”的结果长时间缓存，哪怕后续配置修正，旧的错误缓存也会导致构建持续失败。可以在项目根目录的gradle.properties中添加如下配置，缩短元数据缓存时间、关闭旧结果缓存：

# 缩短HTTP请求超时时间，方便快速定位连通性问题
org.gradle.internal.http.connectionTimeout=10000
org.gradle.internal.http.socketTimeout=10000
# 禁用动态版本的旧结果缓存
org.gradle.dependency.cache.dynamic.versions=false

3. 调试验证方法 #

配置调整后如果还是不生效，可以执行带详细日志的构建命令，定位实际请求的问题：

• 构建时加参数：./gradlew build --info --stacktrace
• 在日志中搜索对应构件的坐标，就能看到每个仓库实际发起请求时的完整URL、携带的认证头、返回的HTTP状态码——多仓库配置失效的场景下，你会看到除第一个仓库外，其他仓库的请求根本没有携带Private-Token认证头，这就是之前所有构件无法解析的核心原因。

可选优化：从根源减少多仓库配置 #

如果三个托管Maven包的项目都属于同一个GitLab Group层级，完全不需要配置三个独立的项目级仓库，直接使用Group级的Maven索引端点即可：

maven {
    name = 'group-shared-packages'
    url = "https://gitlab.com/api/v4/groups/你的多级Group对应的实际ID/-/packages/maven"
    credentials(HttpHeaderCredentials) {
        name = 'Private-Token'
        value = System.getenv("你的GitLab访问Token环境变量")
    }
    authentication {
        header(HttpHeaderAuthentication) {
            realm = "gitlab.com"
            host = "gitlab.com"
        }
    }
}

这个端点会自动索引Group下所有项目发布的Maven构件，既适配多级Group路径的场景（不需要解析复杂的命名空间路径，直接用Group ID做路由），也因为不需要配置多个私有仓库，从根源上避免了多仓库凭证绑定冲突的问题。之前你使用实例级端点出现适配问题，就是因为老的实例级端点需要按Group的路径命名空间做路由，多级路径会出现解析失败，直接用Group ID对应的API端点就不会有这类问题。 #

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