GitLab Maven仓库无法自动拉取Java库的sources与javadoc包问题

核心原因 #

GitLab Maven包注册表遵循标准Maven仓库规范，Gradle需要通过构件的POM文件来识别sources和javadoc附属包。你的问题本质是：上传到GitLab的lib-name库缺少正确配置的POM文件，或者POM中没有关联对应的源码和文档包，导致Gradle无法自动发现这些附属构件。

具体验证与修复步骤 #

1. 检查GitLab包中的POM文件 #

进入GitLab服务器的maven组包注册表页面，找到lib-name:0.0.1版本，确认是否存在lib-name.pom文件：

• 如果没有POM文件：必须重新上传包含正确POM的构件集合。
• 如果有POM文件：打开POM查看是否包含sources和javadoc的关联配置（参考下方示例）。

2. 确保上传构件时遵循Maven规范 #

无论是用构建工具（Gradle/Maven）自动上传，还是手动上传，都要保证：

• 主包lib-name.jar、源码包lib-name.sources.jar、文档包lib-name.javadoc.jar和对应的lib-name.pom必须属于同一版本（0.0.1）。
• POM文件中需明确关联附属构件，或通过构建插件自动生成包含关联信息的POM。

用Gradle上传库的正确配置

如果你的lib-name是用Gradle构建的，添加以下配置确保生成并上传源码、文档包及正确POM：

plugins {
    id 'java'
    id 'maven-publish'
}

java {
    // 自动生成sources.jar和javadoc.jar
    withSourcesJar()
    withJavadocJar()
}

publishing {
    publications {
        maven(MavenPublication) {
            from components.java // 自动关联主包、源码包、文档包到POM
        }
    }
    repositories {
        maven {
            url "https://gitlab.server.com/api/v4/groups/maven/-/packages/maven"
            credentials(HttpHeaderCredentials) {
                name = "Private-Token"
                value = System.getenv("GITLAB_TOKEN")
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
}

执行publish任务后，GitLab会收到完整的构件集合，POM中会自动包含附属包的元信息。

手动上传的注意事项

如果手动上传到GitLab UI，需确保：

• 上传lib-name.pom，且POM中包含以下插件配置（用于关联附属包）：

<project>
    <groupId>org.company.tool</groupId>
    <artifactId>lib-name</artifactId>
    <version>0.0.1</version>
    <packaging>jar</packaging>

    <build>
        <plugins>
            <!-- 关联源码包 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <version>3.2.1</version>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <goals>
                            <goal>jar-no-fork</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <!-- 关联文档包 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.4.1</version>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

• 将lib-name.jar、lib-name.sources.jar、lib-name.javadoc.jar和lib-name.pom全部上传到同一版本目录下。

3. 验证修复效果 #

重新上传构件后，在你的项目中执行：

./gradlew clean build --refresh-dependencies

此时Gradle应能自动拉取源码和文档包，IDEA也会正常加载这些内容。

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