Maven引入GitHub Packages中search-api依赖编译失败求助

问题场景 #

我维护两个Spring Boot项目：search-api（对接Elasticsearch）和persistence-api（对接PostgreSQL），需要把search-api作为依赖引入persistence-api。已经按GitHub Packages文档配置了仓库和Maven settings，但执行mvn install -DskipTests时出现一堆编译错误，提示找不到search-api里的包和类。这个依赖之前正常工作，但修改search-api代码生成新的Snapshot版本后就报错了，试过清理本地M2仓库、执行mvn clean install -U -DskipTests，问题还是没解决。

排查与解决步骤 #

1. 核对Snapshot版本与仓库存在性 #

• 登录GitHub Packages后台，确认search-api的新Snapshot版本已经成功推上去了，版本号和persistence-api的pom.xml里写的完全一致（注意Snapshot版本可能带时间戳后缀，比如1.0.0-SNAPSHOT实际存储为1.0.0-20240520.123456-1）
• 检查persistence-api的pom.xml里依赖的search-api版本有没有写错，比如多了空格、版本号拼错

2. 验证Maven settings.xml的仓库配置 #

• 确保settings.xml里的GitHub Packages仓库同时开启了快照和发布仓库支持，Snapshot依赖得从快照仓库拉：

  <repositories>
    <repository>
      <id>github</id>
      <name>GitHub Packages</name>
      <url>https://maven.pkg.github.com/你的用户名/你的仓库名</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
  </repositories>
  

• 检查settings.xml里的server配置，用户名和token有没有read:packages权限，没权限的话拉不到依赖

3. 检查search-api的打包配置 #

• 确认search-api的pom.xml打包类型是jar，而且如果用了Spring Boot插件，得配置classifier生成可被依赖的jar（默认的Spring Boot jar是可执行的，其他项目依赖会找不到类）：

  <packaging>jar</packaging>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <configuration>
          <classifier>exec</classifier>
        </configuration>
      </plugin>
    </plugins>
  </build>
  

• 检查search-api的pom.xml有没有错误的<exclusions>或者把依赖设成<scope>provided</scope>，导致需要的类没被打包进去

4. 彻底清理本地缓存 #

• 手动删掉本地M2仓库里search-api的Snapshot目录，比如~/.m2/repository/com/yourcompany/search-api/1.0.0-SNAPSHOT，然后重新跑mvn clean install -U -DskipTests，-U会强制拉取最新的Snapshot版本

5. 排查镜像优先级问题 #

• 如果settings.xml里配了其他镜像（比如阿里云），可能Maven优先从镜像拉，而镜像没同步这个Snapshot。可以临时注释掉其他镜像，只留GitHub Packages仓库测试

常见修复示例 #

如果是Spring Boot可执行Jar导致的依赖问题，修改search-api的pom.xml后重新推送版本：

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <executions>
        <execution>
          <goals>
            <goal>repackage</goal>
          </goals>
          <configuration>
            <classifier>exec</classifier>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

然后在persistence-api里执行mvn clean install -U -DskipTests即可。

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