Maven无法从Google Artifact Registry下载父依赖问题排查

问题背景 #

我们的项目从自建Nexus仓库迁移到Google Artifact Registry（GAR）时，碰到了父依赖的下载问题。所有操作都在GitHub Actions的ubuntu-22.04环境中执行。

已经成功通过以下命令将POM父包部署到GAR：

mvn deploy:deploy-file -Dpackaging=pom -Dfile=$svcname-$version.pom -DrepositoryId=${{ inputs.maven-registry-type }} -Durl=${{ inputs.maven-registry }} -DgroupId="$grpname" -DartifactId="$svcname" -Dversion="$revision"

该父包在GAR中正常显示，但其他项目在pom.xml中配置它作为父依赖时，始终无法下载对应的POM文件。项目pom.xml的相关配置如下：

<parent>
        <groupId>com.company.name</groupId>
        <artifactId>common-parent</artifactId>
        <version>VERSION</version>
</parent>

    <repositories>
        <repository>
            <id>common-parent</id>
            <url>artifactregistry://region-maven.pkg.dev/project/common-parent</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

    <build>
        <extensions>
            <extension>
                <groupId>com.google.cloud.artifactregistry</groupId>
                <artifactId>artifactregistry-maven-wagon</artifactId>
                <version>2.2.1</version>
            </extension>
        </extensions>
    </build>

报错信息 #

Cannot access artifactregistry://region-maven.pkg.dev/project/common-parent with type default using the available connector factories: BasicRepositoryConnectorFactory and 'parent.relativePath' points at wrong local POM @ line 10, column 10'

本地环境也存在同样问题，必须手动执行mvn install:install-file安装父依赖才能正常构建，但在使用Nexus时完全不需要这个操作。另外发现，该包作为普通<dependency>可以正常从GAR下载，只有作为<parent>父依赖时会失败。

已尝试的无效方案 #

• 在<parent>节点中添加空的<relativePath />：

<parent>
  ...
  <relativePath />
</parent>

• 执行Maven命令时添加强制更新快照的-U参数：

mvn install -U

解决方案 #

问题的核心原因是Maven解析父依赖的时机早于项目pom.xml中build扩展的加载——当Maven尝试下载父依赖时，artifactregistry-maven-wagon扩展还没被加载，无法识别artifactregistry://协议的仓库地址，导致无法连接到GAR获取父POM。

解决方法是将GAR仓库和wagon扩展的配置移到Maven的settings.xml中，确保Maven在初始化阶段就能加载扩展并识别仓库地址：

1. 在settings.xml的<profiles>节点下添加GAR仓库配置：

<profile>
  <id>gar-maven-repo</id>
  <repositories>
    <repository>
      <id>common-parent</id>
      <url>artifactregistry://region-maven.pkg.dev/project/common-parent</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>
</profile>

2. 在settings.xml的<activeProfiles>节点中激活上述profile：

<activeProfiles>
  <activeProfile>gar-maven-repo</activeProfile>
</activeProfiles>

3. 在settings.xml的<build>节点下配置wagon扩展：

<build>
  <extensions>
    <extension>
      <groupId>com.google.cloud.artifactregistry</groupId>
      <artifactId>artifactregistry-maven-wagon</artifactId>
      <version>2.2.1</version>
    </extension>
  </extensions>
</build>

如果是在GitHub Actions环境中，可以通过actions/setup-java动作指定自定义的settings.xml文件，或者直接在动作参数中配置仓库和扩展。

配置完成后，Maven在启动时就会加载wagon扩展，解析父依赖时就能正确处理GAR的仓库地址，无需手动安装父依赖即可正常构建。

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