利用 GitHub 搭建個人 Maven 倉庫：零成本發布與依賴管理實戰

利用 GitHub 搭建個人 Maven 倉庫：零成本發布與依賴管理實戰

許多開源專案選擇 GitHub 作為 Maven 倉庫發布成果，本文記錄從本地部署到 GitHub 託管、再到專案引用的完整流程，助你零成本構建私有依賴管理體系。

第一步：配置本地 File 類型 Maven 倉庫

Maven 支援部署到本地文件系統。在項目 pom.xml 的 <distributionManagement> 中指定本地路徑：

<distributionManagement>
    <repository>
        <id>my-mvn-repo</id>
        <url>file:/home/user/code/maven-repo/repository/</url>
    </repository>
</distributionManagement>

建議使用命令列部署，避免汙染專案配置：

mvn deploy -DaltDeploymentRepository=my-mvn-repo::default::file:/home/user/code/maven-repo/repository/

參考：Maven Deploy Plugin 官方文檔

第二步：將本地倉庫提交到 GitHub

在 GitHub 建立新倉庫（如 maven-repo），將本地 maven-repo 目錄下的所有文件推送：

cd /home/user/code/maven-repo/
git init
git add repository/*
git commit -m 'deploy artifacts'
git remote add origin git@github.com:username/maven-repo.git
git push origin master

推送後，GitHub 上會生成標準 Maven 倉庫目錄結構，包含 JAR、POM、MD5、SHA1 等文件。

第三步：在專案中引用 GitHub Maven 倉庫

GitHub 使用 raw.githubusercontent.com 域名提供原始文件下載。在消費者專案的 pom.xml 中添加：

<repositories>
    <repository>
        <id>github-maven-repo</id>
        <url>https://raw.githubusercontent.com/username/maven-repo/master/repository</url>
    </repository>
</repositories>

目錄瀏覽與搜尋限制

出於安全考慮，raw.githubusercontent.com 不支援目錄瀏覽。若需查看文件結構或搜尋，請直接訪問 GitHub 倉庫頁面：

• 瀏覽頁面：https://github.com/username/maven-repo/blob/master/repository/.../artifact.jar
• 實際下載 URL：https://raw.githubusercontent.com/username/maven-repo/master/repository/.../artifact.jar

Maven 倉庫運作機制深度解析

典型 Maven 依賴目錄下包含三個關鍵元數據文件：

• maven-metadata.xml：記錄最新部署版本、時間戳、構建號
• maven-metadata.xml.md5 / .sha1：校驗文件完整性

<?xml version="1.0" encoding="UTF-8"?>
<metadata modelVersion="1.1.0">
  <groupId>io.github.username</groupId>
  <artifactId>my-library</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <versioning>
    <snapshot>
      <timestamp>20240115.103000</timestamp>
      <buildNumber>1</buildNumber>
    </snapshot>
    <lastUpdated>20240115103000</lastUpdated>
  </versioning>
</metadata>

關鍵點：Maven 編譯時優先請求 maven-metadata.xml 確定最新版本。若缺失此文件，即使加 -U 強制更新也無法拉取最新 SNAPSHOT。因此必須先在本地 deploy 生成元數據，再上傳到 GitHub。

Maven 倉庫關係與本地倉庫配置

Maven 倉庫分為中央倉庫、遠程私服、本地倉庫、鏡像倉庫等層級。若需直接使用本地文件倉庫：

<repositories>
    <repository>
        <id>local-file-repo</id>
        <url>file:/home/user/code/maven-repo/repository/</url>
    </repository>
</repositories>

注意事項與最佳實踐

1. 避免多倉庫並行查找：Maven 無優先級配置，配置多個 repository 會導致首次編譯依次嘗試下載，耗時極長
2. 集中管理依賴：盡量將多個模組發布到同一倉庫，而非每個專案建一個倉庫
3. 版本衝突處理：同一 artifact 不同版本共存時，元數據文件需正確維護

參考資源：Maven Repository 官方指南