釋出jar包到maven中央倉庫

是禿子遲早會發光的發表於2023-12-12
JARMaven

1. 環境

在網上找的很多文章中寫得都有很多問題，這裡記錄一下最近一次成功地釋出jar包到maven中央倉庫的過程。並附帶上每一個步驟官方的指導連結。

  • 系統：mac（windows系統在下載輔助工具時不太一樣，在配置上和mac系統沒有區別）
  • IDE：IntelliJ IDEA
  • JDK：1.8
  • maven：3.8.1（IDEA自帶的版本）
  • 程式碼：上傳到github上（使用gitee也行）
  • 釋出形式：以jar包釋出release版本（非SNAPSHOT版本）

2. 專案配置

官方對釋出的專案做了一些必需的要求，如果不按要求來，釋出可能會報錯。

2.1. javadoc和source

以非pom方式打包的專案（pom.xml配置檔案中可以透過標籤配置打包方式，預設就是jar），在打包完成後，target目錄下必須要包含***-sources.jar和***-javadoc.jar。如下圖：
釋出jar包到maven中央倉庫
為了達成以上效果，需要在pom.xml中依賴兩個外掛：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <version>2.2.1</version>
            <executions>
                <execution>
                    <id>attach-sources</id>
                    <goals>
                        <goal>jar-no-fork</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.9.1</version>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

參考：https://central.sonatype.org/publish/requirements/#supply-javadoc-and-sources

2.2. 使用 GPG/PGP 簽署檔案

打包完成後，target目錄下必須要包含***.jar.sac。如下圖：
釋出jar包到maven中央倉庫
為了達成以上效果，需要在pom.xml中依賴外掛（加完外掛不要急著構建，還要下載GPG生成金鑰，後面會說）：

<build>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-gpg-plugin</artifactId>
        <version>3.1.0</version>
        <executions>
            <execution>
                <id>sign-artifacts</id>
                <phase>verify</phase>
                <goals>
                    <goal>sign</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</build>

參考：https://central.sonatype.org/publish/requirements/#sign-files-with-gpgpgp

2.3. 專案名稱和版本配置

  • groupId：使用正確的反向域名。如果有私人域名，可以配置成私人域名（後面配置起來比較麻煩）。如果沒有私人域名，可以直接使用github的域名：io.github.{account}（gitee同理，推薦使用這種方式， account是github註冊的登入賬號）。
  • artifactId：專案名稱，可以隨意發揮。
  • version：版本，可以使用1.1.1這種格式，不推薦帶-SNAPSHOT，快照版本不會直接釋出到中央倉庫。
釋出jar包到maven中央倉庫

參考：https://central.sonatype.org/publish/requirements/#correct-coordinates

2.4. 專案名稱、描述和 URL

這個是為了增加可讀性。

  • name：推薦使用這種格式：<name>${project.groupId}:${project.artifactId}</name>，當然也可以自定義。
  • description：專案描述，自己發揮。
  • url：專案地址，直接使用github（或gitee）上專案的地址即可。
釋出jar包到maven中央倉庫

參考：https://central.sonatype.org/publish/requirements/#project-name-description-and-url

2.5. 許可證照

可以使用Apache/MIT的許可證照，直接複製下面的即可：

<licenses>
        <license>
        <name>The Apache Software License, Version 2.0</name>
        <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
    </license>
</licenses>

參考：https://central.sonatype.org/publish/requirements/#license-information

2.6. 開發人員資訊

留你自己的藝名和郵箱：

<developers>
        <developer>
        <name>你的藝名</name>
        <email>你的郵箱</email>
    </developer>
</developers>

參考：https://central.sonatype.org/publish/requirements/#developer-information

2.7. SCM 原始碼管理系統資訊

可以使用github（或gitee）的專案地址。

<scm>
    <connection>scm:git:git://github.com:maidoubaobao/easy-tool.git</connection>
    <developerConnection>scm:git:ssh://github.com:maidoubaobao/easy-tool.git</developerConnection>
    <url>https://github.com/maidoubaobao/easy-tool/tree/master</url>
</scm>

參考：https://central.sonatype.org/publish/requirements/#scm-information

2.8. 檔案簽名校驗（非必需）

官網說必需要包含.md5和.sha1簽名校驗檔案，但我沒有特地去配置這個，也是可以釋出的。可以跳過這一步。

參考：https://central.sonatype.org/publish/requirements/#provide-files-checksums

3. 在 JIRA 上提釋出申請

3.1. 註冊 JIRA

點選如下連結註冊賬號並登入，如果有賬號直接登入即可：
https://issues.sonatype.org/secure/Signup!default.jspa

參考：https://central.sonatype.org/publish/publish-guide/#initial-setup

3.2. 建立專案

點選新建，按照下面的圖示來填寫：
釋出jar包到maven中央倉庫
釋出jar包到maven中央倉庫

  • groupId：要和專案裡對應上，必須是一個可用的域名的反轉字串，如果專案是放在github上，必須使用io.github.{account}的格式，否則會稽核不透過（注意：不能使用com.github）。
  • Project URL/SCM url：直接使用github的專案地址即可。

3.3. 檢視剛剛建立的專案

正常情況下建立好預設就會進入剛剛建立的專案，如果進不去，可以按照路徑專案-檢視所有專案-類別-Central即可看到專案連結，點進去後，切換篩選器我的報告就能看到建立的專案了。
釋出jar包到maven中央倉庫
釋出jar包到maven中央倉庫

3.4. 在github中建立一個空專案

建立好的專案，會分配一個唯一標識OSSRH-***（見上圖），需要用這個標識去github上建立一個空專案，這個是為了向核審管理員證明需要釋出的github專案確實是你自己的專案。
釋出jar包到maven中央倉庫

3.5. 等待管理員稽核

管理員都在國外，因為時差，一般隔天才會核審透過。沒辦法，耐心等著吧。
稽核透過後，會發郵件（郵箱就是註冊JIRA的那個），也會在JIRA專案下出現活動日誌。
釋出jar包到maven中央倉庫

4. 獲取 GPG 金鑰

在等待JIRA專案稽核的同時，可以並行把GPG金鑰搞定。
注意：mac系統和windows系統在獲取GPG金鑰時有些區別，mac全程都是透過命令列搞定的，而windows提供了操作介面，可能會方便一點。這裡只介紹mac系統的配置方式，windows系統可以自行搜配置教程。

4.1. 安裝 GnuPG

  • 用下面的連結下載 GnuPG，選擇系統對應的版本。

https://gnupg.org/download/index.html#sec-1-2
釋出jar包到maven中央倉庫
釋出jar包到maven中央倉庫

  • 驗證安裝是否成功

使用gpg --version命令來驗證，如果輸出了版本則說明安裝成功。
釋出jar包到maven中央倉庫

參考：https://central.sonatype.org/publish/requirements/gpg/#installing-gnupg

4.2. 生成金鑰對

使用命令gpg --full-generate-key生成金鑰對，2年內有效。執行命令後，需要輸入姓名和郵箱（建議和註冊JIRA時用的一致），然後輸入o（注意是字母o）確認生成。隨後會提示輸入一個passphrase口令來保護你的金鑰對，這個口令要記住，後面配置需要使用。
注意：這個命令不建議執行多次，不然生成了多個金鑰對，釋出時還要去配置使用哪個金鑰對，比較麻煩。
釋出jar包到maven中央倉庫

參考：https://central.sonatype.org/publish/requirements/gpg/#generating-a-key-pair

4.3. 釋出公鑰

  • 使用命令gpg --keyserver pgp.mit.edu --send-keys 公鑰來發布。

官網提供了3個地址，有的地址可能不能用，上面這個地址親測有效。（所以官方也不一定靠譜）

釋出jar包到maven中央倉庫
  • 使用命令gpg --keyserver pgp.mit.edu --recv-keys 公鑰驗證是否釋出成功。

注意：驗證的命令要等一會執行才能響應資料，估計釋出可能有點延時，可以多執行幾次。反正如果響應如圖所示，就代表釋出成功了。
釋出jar包到maven中央倉庫

參考：https://central.sonatype.org/publish/requirements/gpg/#distributing-your-public-key

5. JIRA 專案核審透過後的配置

5.1. 倉庫地址

核審透過後，在JIRA上的專案裡可以看到日誌，這代表專案已經擁有釋出許可權了。下圖示記出來的就是倉庫地址。
釋出jar包到maven中央倉庫

5.2. 修改 maven 配置

這裡修改的是maven的setting.xml配置檔案，如果不知道配置檔案在哪裡（那麼你不是一個合格的程式猿），可以在IntelliJ IDEA的settings > Build,Execution,Deployment > Builds Tools > Maven頁面找到User settings file。

  • 配置JIRA賬戶用於釋出
    這裡的<server>-<id>是有用的，一會要在專案的pom檔案配置中要對應上。
<servers>
    <server>
        <id>ossrh</id>
        <username>JIRA使用者名稱</username>
        <password>JIRA登入密碼</password>
    </server>
</servers>
  • 配置GPG用於檔案簽署校驗
    前文2.2小節已經在專案中配置了GPG外掛了，這裡要配置GPG的口令才能進行正常的簽署。
    前文4.2小節生成GPG金鑰對的時候，輸入過一個口令passphrase，就用那個。
<profiles>
    <profile>
        <id>ossrh</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <gpg.executable>gpg2</gpg.executable>
            <gpg.passphrase>GPG口令</gpg.passphrase>
        </properties>
    </profile>
</profiles>

5.3. 配置倉庫地址和外掛

這裡是在專案的pom檔案中配置。

  • 配置釋出的倉庫地址
    這裡的倉庫域名，可以從JIRA專案的日誌裡看到，核審透過後會給你一個地址，就用那個做為域名。按照下面的格式來配：
<distributionManagement>
    <snapshotRepository>
        <id>ossrh</id>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
    </snapshotRepository>
    <repository>
        <id>ossrh</id>
        <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
</distributionManagement>
  • 配置倉庫外掛
    這裡的serverId要和前面maven配置檔案setting.xml中配置的<server>-<id>保持一致。nexusUrl就是倉庫地址，和上面配置的一樣。
<build>
    <plugins>
        <plugin>
            <groupId>org.sonatype.plugins</groupId>
            <artifactId>nexus-staging-maven-plugin</artifactId>
            <version>1.6.13</version>
            <extensions>true</extensions>
            <configuration>
                <serverId>ossrh</serverId>
                <nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
                <autoReleaseAfterClose>true</autoReleaseAfterClose>
            </configuration>
        </plugin>
    </plugins>
</build>

6. 釋出

JIRA 核審透過後，就可以釋出了

6.1. 釋出到中央倉庫

  • 可以直接在IntelliJ IDEA中點選deploy來發布：
釋出jar包到maven中央倉庫
  • 輸出如下結果說明發布成功了：
釋出jar包到maven中央倉庫

6.2. 驗證釋出結果

釋出成功以後，並不能立刻在maven中央倉庫中搜尋到，大概隔一天以後才能搜尋得到，所以不要心急，耐心等待。

  • JIRA 上的回應

執行完釋出動作以後，大概隔了幾分鐘以後，JIRA專案下會多出一條日誌：
釋出jar包到maven中央倉庫
這條日誌給出了兩個地址和兩個時間，反正差不多要等個那麼長的時間才能搜得到。我已經發布到中央倉庫裡了，第一個地址裡還是找不到，但是第二個地址裡能搜到：
釋出jar包到maven中央倉庫
下面這個地址好像是執行完釋出操作後，過一會就能搜得到，可以試試：
https://s01.oss.sonatype.org/content/groups/public/

  • 在中央倉庫裡搜尋

一般是隔天，才能在中央倉庫裡搜得到，在阿里雲的倉庫裡也可以搜得到，阿里雲本來就是從中央倉庫同步的。

建議使用groupId來搜，一搜一個準。用artifactId來搜在第一頁可能找不到，因為maven會對搜尋結果做排序。
釋出jar包到maven中央倉庫

7. 彩蛋

  • JAVA_HOME 報錯

如果遇到這樣的報錯The environment variable JAVA_HOME is not correctly set，不要慌，一般是因為你本地環境變數沒有設定JAVA_HOME或者設定成了jre的目錄。如果是因為前者可以去設定一下JAVA_HOME，如果是因為後者，可以把JAVA_HOME的目錄改成jdk/bin的目錄，或者可以改一下專案的pom配置檔案：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9.1</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <!-- 這裡需要指定jdk的bin目錄下的javadoc執行檔案 -->
                <javadocExecutable>${java.home}/../bin/javadoc</javadocExecutable>
            </configuration>
        </execution>
    </executions>
</plugin>

相關文章