从私有仓库下载Maven依赖异常：GitLab公共库无法引入

我有一个Spring Boot微服务项目，为避免代码重复，将通用工具类、实体类及仓库类封装为名为common的库，已成功部署到GitLab包仓库。但在其他项目中引入该依赖时出现问题：执行mvn install命令显示成功，却无法导入该包下的类，本地.m2仓库中也找不到该依赖。需求是让Maven优先从GitLab仓库查找依赖，找不到再去Maven中央仓库。

现有配置 #

pom.xml 仓库配置 #

<repositories>
    <!-- Ton repository GitLab -->
    <repository>
        <id>gitlab-maven</id>
        <url>my_url_gitlab_package_registry</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <!-- Maven Central comme fallback -->
    <repository>
        <id>maven-central</id>
        <url>https://repo.maven.apache.org/maven2/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

pom.xml 依赖配置 #

<dependency>
    <groupId>com.packages</groupId>
    <artifactId>common</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

settings.xml 配置（已认证） #

<mirror>
  <id>gitlab-maven</id>
  <name>GitLab proxy of central repo</name>
  <url>my_url_gitlab_package_registry</url>
  <mirrorOf>*</mirrorOf>
</mirror>

尝试的操作与错误 #

执行手动拉取依赖命令：

mvn org.apache.maven.plugins:maven-dependency-plugin:3.1.2:get -Dartifact=com.packages:common:0.0.1-SNAPSHOT -DrepoUrl=my_url_gitlab_package_registry -DrepositoryId=gitlab-maven

得到错误：

Error resolving version for plugin '.bjft:package' from the repositories [local (C:\Users\USER\.m2\repository), central (https://repo.maven.apache.org/maven2)]: Plugin not found in any plugin repository -> [Help 1]

可见Maven仍在尝试从中央仓库查找自定义包，而非GitLab仓库。

解决步骤 #

1. 修正镜像配置，避免覆盖仓库优先级 #

当前settings.xml中<mirrorOf>*</mirrorOf>会强制所有仓库请求转发到GitLab，但GitLab包仓库并非中央仓库的代理，这会干扰依赖拉取逻辑。若要保留GitLab优先的逻辑，删除整个mirror节点即可——Maven会按照pom.xml中仓库声明的顺序（GitLab在前）依次查找依赖。

如果需要GitLab代理中央仓库，可调整镜像范围：

<mirror>
  <id>gitlab-maven</id>
  <name>GitLab proxy of central repo</name>
  <url>my_url_gitlab_package_registry</url>
  <mirrorOf>maven-central</mirrorOf>
</mirror>

2. 确认GitLab仓库地址与认证有效性 #

• 检查my_url_gitlab_package_registry是否为正确的仓库地址：项目级仓库格式为https://gitlab.example.com/api/v4/projects/{项目ID}/packages/maven，群组级为https://gitlab.example.com/api/v4/groups/{群组ID}/packages/maven
• 确认settings.xml中server配置与仓库id匹配，且访问令牌拥有read_api和read_repository权限：

<servers>
  <server>
    <id>gitlab-maven</id>
    <username>你的GitLab用户名</username>
    <password>你的GitLab访问令牌</password>
  </server>
</servers>

3. 清理缓存并强制拉取依赖 #

执行命令清理本地缓存并强制更新：

mvn clean install -U

-U参数会强制Maven忽略本地快照缓存，从远程仓库重新拉取。

4. 修复手动拉取命令的异常 #

出现.bjft:package插件错误大概率是本地Maven插件缓存损坏，先清理插件缓存再重新执行：

# Windows系统
rmdir /s /q C:\Users\USER\.m2\repository\org\apache\maven\plugins\maven-dependency-plugin

# Linux/macOS
rm -rf ~/.m2/repository/org/apache/maven/plugins/maven-dependency-plugin

# 重新执行拉取命令
mvn org.apache.maven.plugins:maven-dependency-plugin:3.1.2:get -Dartifact=com.packages:common:0.0.1-SNAPSHOT -DrepoUrl=my_url_gitlab_package_registry -DrepositoryId=gitlab-maven

5. 验证GitLab仓库中的依赖存在性 #

登录GitLab后台，确认com.packages:common:0.0.1-SNAPSHOT已正确上传，且groupId、artifactId、version与pom.xml中的配置完全一致（Maven对这些字段大小写敏感）。

内容的提问来源于stack exchange，提问作者Tchokouani Edy Michel