Gradle无法从GitHub仓库解析项目？求解决方案

我有一个托管在GitHub的Gradle库项目，还有一个依赖该库的应用项目。因为库还没稳定到可以发布的程度，所以尝试用sourceControl块直接依赖Git仓库。

应用项目的settings.gradle.kts配置如下：

sourceControl {
    gitRepository(uri("https://github.com/user/repo")) {
        producesModule("group:project")
    }
}

build.gradle.kts的依赖配置：

implementation("group:project") {
    version {
        branch = "main"
    }
}

执行./gradlew build时构建失败，报错信息：

FAILURE: Build failed with an exception.

* What went wrong:
Could not determine the dependencies of task ':distTar'.
> Could not resolve all dependencies for configuration ':runtimeClasspath'.
   > Git repository at https://github.com/user/repo did not contain a project publishing the specified dependency.             
Required by:
         root project :

奇怪的是，把仓库地址换成本地路径（file://path/to/repo）后，构建就能成功完成。请问这是什么原因？

可能的原因及排查方向 #

• 远程分支的模块坐标不匹配
  你在producesModule里指定的group:project必须和远程main分支中库项目的build.gradle.kts里的group、name完全一致。比如库项目配置的是group = "com.myteam"、name = "core-lib"，那producesModule就得写成com.myteam:core-lib。本地能成功是因为本地代码的坐标是对的，但远程分支可能有未推送的配置改动，或者你写错了坐标。

• 远程仓库缺少Gradle模块元数据
  Gradle拉取Git依赖时，需要读取项目的模块元数据（如gradle-module-metadata.json）。本地路径下Gradle可以直接解析项目的构建脚本，但远程仓库如果没有生成并提交这些元数据，或者库项目没有配置maven-publish插件（哪怕只是本地发布配置），Gradle就无法识别到可发布的模块。

• 远程仓库访问权限或网络问题
  如果是私有GitHub仓库，Gradle可能没有正确的认证信息，导致拉取的仓库内容不完整，找不到对应的模块。可以手动克隆远程仓库测试能否正常获取代码，或者在~/.gradle/gradle.properties里配置GitHub个人访问令牌：

  githubUsername=你的用户名
  githubPassword=你的个人访问令牌
  

• 分支名称不匹配
  确认远程仓库的默认分支是不是main，有些仓库仍使用master作为默认分支。如果远程分支是master但你配置的是branch = "main"，Gradle就会找不到对应分支的模块内容。

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