GitLab部署Maven库后同组项目无法引用的问题排查

1. 核对依赖坐标完全一致 #

确保引用项目的pom.xml里的groupId、artifactId、version和你部署的库完全匹配，包括大小写、是否带-SNAPSHOT后缀（你打了正式标签0.0.1，所以version不要加SNAPSHOT）。示例：

<dependency>
    <groupId>com.your.group</groupId>
    <artifactId>your-library</artifactId>
    <version>0.0.1</version>
</dependency>

2. 确认GitLab仓库配置正确性 #

项目级仓库配置 #

如果你的库部署在单个项目的Packages下，引用项目的pom.xml或settings.xml里要配置项目级仓库地址：

<repositories>
    <repository>
        <id>gitlab-maven</id>
        <url>https://gitlab.example.com/api/v4/projects/[你的项目ID]/packages/maven</url>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>gitlab-maven</id>
        <url>https://gitlab.example.com/api/v4/projects/[你的项目ID]/packages/maven</url>
    </pluginRepository>
</pluginRepositories>

组级仓库配置 #

如果是部署在组级仓库，替换url为组地址：

<url>https://gitlab.example.com/api/v4/groups/[你的组ID]/packages/maven</url>

认证信息配置 #

在settings.xml里添加GitLab的认证，确保令牌拥有read_package权限：

<servers>
    <server>
        <id>gitlab-maven</id>
        <username>你的用户名或deploy token用户名</username>
        <password>个人访问令牌或deploy token密码</password>
    </server>
</servers>

注意：id要和仓库配置里的id完全一致。

3. 验证GitLab上的包是否存在 #

登录GitLab，进入你的库项目，打开Packages & Registries > Maven Repository，确认0.0.1版本的包已存在，且包含.jar和.pom文件。如果缺失文件，重新触发流水线部署。

4. 检查Maven仓库优先级和镜像规则 #

如果引用项目配置了Maven镜像（比如阿里云镜像），要确保GitLab仓库不会被镜像覆盖。可在settings.xml里添加镜像例外：

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>central,!gitlab-maven</mirrorOf>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

这样Maven会优先从GitLab仓库拉取对应id的依赖，其他依赖走镜像。

5. 清理本地Maven缓存 #

执行以下命令清理本地缓存，强制重新拉取依赖：

mvn clean install -U

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