使用Maven拉取GitHub包时遭遇401未授权错误求助

settings.xml的正确存放位置 #

Maven会读取两个优先级不同的settings.xml位置：

• 用户级配置：Linux/macOS下为~/.m2/settings.xml，Windows下为C:\Users\<你的用户名>\.m2\settings.xml，你当前使用的这个位置是完全正确的。
• 全局配置：Maven安装目录下的conf/settings.xml，优先级低于用户级配置。

可以执行mvn help:effective-settings命令，查看Maven实际生效的配置，确认你的settings.xml是否被正确加载。

配置错误排查要点 #

1. 服务器ID必须严格匹配 #

GitHub Packages的服务器ID必须设为github，同时你的pom.xml中对应仓库的id要和settings.xml里<server>的id完全一致——Maven是通过ID匹配凭证的，不一致就会导致凭证无法生效。

正确的settings.xml核心片段：

<settings>
  <servers>
    <server>
      <id>github</id>
      <username>你的GitHub用户名</username>
      <password>你的PAT（个人访问令牌）</password>
    </server>
  </servers>
</settings>

pom.xml中对应的仓库配置：

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

2. PAT权限不足 #

确保你的PAT至少拥有read:packages权限（拉取包场景），如果是推送包还需要write:packages权限。创建PAT时必须勾选对应权限，同时确认PAT没有过期、未被撤销。

3. 配置结构错误 #

检查settings.xml的标签嵌套是否合规：<server>必须放在<servers>标签内部，<servers>必须属于<settings>根标签的子节点——任何层级错误都会导致Maven直接忽略凭证配置。

4. 镜像或代理干扰 #

• 如果配置了镜像（<mirrors>），需要避免GitHub仓库被镜像覆盖。可以给镜像添加<mirrorOf>!github</mirrorOf>，让GitHub仓库的请求跳过镜像：

  <mirrors>
    <mirror>
      <id>mirrorId</id>
      <mirrorOf>central,!github</mirrorOf>
      <url>https://你的镜像地址</url>
    </mirror>
  </mirrors>
  

• 如果使用代理，确认代理服务器允许访问maven.pkg.github.com，且代理配置中没有拦截GitHub域名的规则。

5. 密码加密问题 #

如果你对密码进行了加密，必须确保Maven配置了对应的加密密钥（通过mvn --encrypt-master-password生成并配置），否则Maven无法解密密码，会直接触发401错误。如果没加密，直接明文填写PAT即可（注意不要泄露PAT）。

调试方法 #

执行mvn install -X开启调试日志，查看请求GitHub Packages时的Authorization头是否正确生成，或者有没有重定向、代理错误等异常信息——这些日志能帮你精准定位问题。

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