从GitLab Package Registry拉取Maven包失败求助

我尝试从GitLab Package Registry拉取Maven包时，出现错误提示：Could not find group:package:0.0.18-SNAPSHOT。但该包确实存在于包仓库中，请问是否遗漏了必要配置？我已分别尝试以下Gradle和Maven配置：

尝试的Gradle配置： #

build.gradle:

repositories {
   mavenCentral(),
   maven {
       url "https://gitlab.com/api/v4/groups/<group-id>/-/packages/maven"
       name "GitLab"
       credentials(HttpHeaderCredentials) {
           name = "<deploy-token-username>"
           value = "deploy-token-value"
       }
       authentication {
           header(HttpHeaderAuthentication)
       }
   }
}

dependencies {
    implementation("<group>:<package>:0.0.18-SNAPSHOT") 
}

尝试的Maven配置： #

pom.xml:

<repositories>
    <repository>
        <id>gitlab-maven</id>
        <url>https://gitlab.com/api/v4/groups/<group-id>/-/packages/maven</url>
    </repository>
</repositories>

<distributionManagement>
    <repository>
        <id>gitlab-maven</id>
        <url>https://gitlab.com/api/v4/projects/<project-id>/packages/maven</url>
    </repository>

    <snapshotRepository>
        <id>gitlab-maven</id>
        <url>https://gitlab.com/api/v4/projects/<project-id>/packages/maven</url>
    </snapshotRepository>
</distributionManagement>
<dependencies>
    <dependency>
        <groupId>group</groupId>
        <artifactId>package</artifactId>
        <version>0.0.18-SNAPSHOT</version>
    </dependency>
</dependencies>

.../.m2/settings.xml:

<settings>
   <servers>
     <server>
       <id>gitlab-maven</id>
       <configuration>
         <httpHeaders>
           <property>
             <name>deploy-token-username</name>
             <value>deploy-token-value</value>
           </property>
         </httpHeaders>
       </configuration>
     </server>
  </servers>
</settings>

1. 修正仓库URL路径 #

你当前使用的是组级仓库URL，但如果目标包是上传到单个项目的仓库，组级URL可能无法访问（除非组开启了「组级包仓库共享」）。直接替换为项目级URL：

• Gradle：将仓库url改为 https://gitlab.com/api/v4/projects/<project-id>/-/packages/maven
• Maven（pom.xml）：将<repository>的url替换为上述项目级地址

2. 修复Deploy Token的认证配置 #

你的认证header名称写错了，且需确保token权限正确：

• Gradle修正：

  credentials(HttpHeaderCredentials) {
      name = "Deploy-Token" // 这里必须是固定的"Deploy-Token"，不是你的token用户名
      value = "你的deploy-token-value"
  }
  

• Maven修正：
  要么改用用户名密码模式（更直观）：

  <server>
    <id>gitlab-maven</id>
    <username>你的deploy-token-username</username>
    <password>你的deploy-token-value</password>
  </server>
  

  要么保留header模式，但修正header名称：

  <property>
    <name>Deploy-Token</name>
    <value>你的deploy-token-value</value>
  </property>
  

• 额外检查：确保Deploy Token拥有read_package_registry权限，在GitLab项目/组的「设置→仓库→Deploy tokens」中确认。

3. 处理SNAPSHOT包的缓存问题 #

SNAPSHOT包容易被构建工具缓存，需强制刷新或配置更新策略：

• Maven：在pom.xml的<repository>中添加SNAPSHOT配置：

  <repository>
      <id>gitlab-maven</id>
      <url>https://gitlab.com/api/v4/projects/<project-id>/-/packages/maven</url>
      <snapshots>
          <enabled>true</enabled>
          <updatePolicy>always</updatePolicy> <!-- 每次构建都检查更新 -->
      </snapshots>
  </repository>
  

• Gradle：执行构建时强制刷新依赖：

  ./gradlew clean build --refresh-dependencies
  

4. 校验依赖坐标准确性 #

严格检查groupId、artifactId、version的拼写和大小写，GitLab包仓库对这些字段是严格匹配的，哪怕细微错误都会导致找不到包。

5. 测试仓库连通性 #

用curl直接验证地址和权限是否有效：

curl --header "Deploy-Token: 你的deploy-token-value" https://gitlab.com/api/v4/projects/<project-id>/-/packages/maven/你的groupId/你的artifactId/0.0.18-SNAPSHOT/maven-metadata.xml

如果能返回XML内容，说明地址和权限没问题，问题出在构建工具配置；如果返回403/404，检查token权限或项目ID是否正确。

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