本文详解如何将 GitHub 用作私有 Maven 仓库，重点解决 raw.githubusercontent.com URL 配置、SNAPSHOT 版本解析失败、认证失效等常见问题，并提供可直接复用的 POM 和 settings.xml 配置范例。
本文详解如何将 github 用作私有 maven 仓库，重点解决 `raw.githubusercontent.com` url 配置、snapshot 版本解析失败、认证失效等常见问题，并提供可直接复用的 pom 和 settings.xml 配置范例。
在 Maven 生态中，GitHub 并非原生支持的远程仓库（如 Maven Central 或 Nexus），但通过合理利用 raw.githubusercontent.com 的静态文件托管能力，完全可以构建轻量级、零运维成本的私有构件仓库。然而，实践中常因 URL 格式错误、SNAPSHOT 版本机制误解或认证配置不当导致依赖解析失败——正如问题中出现的 Could not find artifact 错误。
✅ 正确的仓库 URL 格式
关键误区在于：不能使用 github.com/[ORG]/[REPO]/raw/[BRANCH]/。该路径返回的是 HTML 页面（触发重定向或 404），而非原始二进制文件。Maven 下载器需要直连 raw 内容服务：
<repositories><repository><id>github-mvn-repo</id><url>https://raw.githubusercontent.com/your-org/your-repo/mvn-repo/</url><snapshots><enabled>true</enabled><updatepolicy>always</updatepolicy></snapshots></repository></repositories>
⚠️ 注意事项：
- mvn-repo/ 是你手动在 GitHub 仓库中创建的目录（例如 https://github.com/your-org/your-repo/tree/mvn-repo），用于存放 com/fooditsolutions/Util/1.0-SNAPSHOT/... 等标准 Maven 目录结构；
- URL 必须以 / 结尾，否则 Maven 会拼接错误路径（如 .../mvn-repocom/...）；
- 不要对 URL 中的 [ORGANISATION]、[Repository name] 等占位符做 HTML 编码（如 []），这会导致 404 —— 上述错误日志中的 %5C%5C%5C[ORGANISATION%5C%5C%5C] 即为模板未替换的典型痕迹。
? SNAPSHOT 依赖必须使用真实时间戳版本
Maven 对 *-SNAPSHOT 版本有特殊处理逻辑：本地构建时会生成带时间戳的唯一版本（如 1.0-20230308.203114-2），并写入 maven-metadata.xml。但 GitHub raw 服务不支持动态重定向或元数据解析，因此：
❌ 错误写法（无法解析）：
<dependency><groupid>com.fooditsolutions</groupid><artifactid>Util</artifactid><version>1.0-SNAPSHOT</version><!-- Maven 尝试解析 metadata，失败 --></dependency>
✅ 正确写法（显式指定已发布的快照版本）：
<dependency><groupid>com.fooditsolutions</groupid><artifactid>Util</artifactid><version>1.0-20230308.203114-2</version><!-- 从 mvn-repo 目录中实际存在的 JAR 名称获取 --></dependency>
? 提示：可通过浏览器访问 https://raw.githubusercontent.com/your-org/your-repo/mvn-repo/com/fooditsolutions/Util/ 查看可用版本列表，或使用 mvn deploy 后检查 target/ 下生成的 maven-metadata.xml 获取最新时间戳。
? 认证配置说明（仅限私有仓库）
若你的 GitHub 仓库为私有，需在 ~/.m2/settings.xml 中配置服务器凭据：
<settings><servers><server><id>github-mvn-repo</id><username>your-github-username</username><password>ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</password><!-- 注意：此处 password 为 GitHub Personal Access Token（需开启 read:packages 权限） --><configuration><httpheaders><property><name>Authorization</name><value>Basic base64-encoded-username:token</value></property></httpheaders></configuration></server></servers></settings>
? 关键点：
必须与 POM 中 完全一致（本例为 github-mvn-repo）； - Token 推荐使用 GitHub Fine-grained Token，权限至少包含 read:packages；
- Base64 编码格式为 username:token（不含空格），例如 echo -n "user:ghp_abc123" | base64；
- 公共仓库无需认证，可直接移除 settings.xml 中相关配置以避免干扰。
✅ 完整验证步骤
- 确保 mvn-repo/ 目录存在且结构符合 Maven 规范（含 groupId、artifactId、version 子目录及 .jar + .pom 文件）；
- 在依赖项目 POM 中配置正确的
URL（结尾 / + mvn-repo/）； - 显式声明依赖的完整时间戳版本号；
- （私有库）确认 settings.xml 中 server.id 匹配，Token 有效；
- 执行 mvn clean compile -U 强制更新快照，观察日志是否成功下载 JAR。
⚠️ 补充建议：生产环境推荐使用 GitHub Packages（maven.pkg.github.com）替代 raw 方案，它原生支持 SNAPSHOT 解析、metadata 管理和 OAuth 认证，更稳定可靠。而 raw.githubusercontent.com 方案适合原型验证或极简场景。
通过以上配置，即可稳定地将 GitHub 作为 Maven 依赖源，摆脱中央仓库限制，实现团队内部构件的高效共享。
