{"meta":{"title":"使用 Maven 发布Java包","intro":"本教程介绍如何使用 Maven 将Java包作为持续集成（CI）工作流的一部分发布到注册表。","product":"GitHub Actions","breadcrumbs":[{"href":"/zh/actions","title":"GitHub Actions"},{"href":"/zh/actions/tutorials","title":"教程"},{"href":"/zh/actions/tutorials/publish-packages","title":"发布软件包"},{"href":"/zh/actions/tutorials/publish-packages/publish-java-packages-with-maven","title":"使用 Maven 发布Java包"}],"documentType":"article"},"body":"# 使用 Maven 发布Java包\n\n本教程介绍如何使用 Maven 将Java包作为持续集成（CI）工作流的一部分发布到注册表。\n\n## 简介\n\n本指南介绍如何创建将 Java 包发布到 GitHub Packages 和 Maven Central 仓库的工作流程。 通过单个工作流程，您可以将包发布到一个或多个仓库。\n\n> \\[!WARNING] 本指南中使用的示例指旧版 OSSRH 服务。 请参阅 Maven 中央存储库文档中“[发布](https://central.sonatype.org/faq/what-is-different-between-central-portal-and-legacy-ossrh/#publishing)”。\n\n## 先决条件\n\n建议对工作流程文件和配置选项有一个基本了解。 有关详细信息，请参阅“[撰写工作流程](/zh/actions/learn-github-actions)”。\n\n有关使用 Maven 为 Java 项目创建 CI 工作流的详细信息，请参阅 [使用 Maven 构建和测试 Java](/zh/actions/automating-builds-and-tests/building-and-testing-java-with-maven)。\n\n你可能还发现基本了解以下内容是有帮助的：\n\n* [使用 Apache Maven 注册表](/zh/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)\n* [在变量中存储信息](/zh/actions/learn-github-actions/variables)\n* [在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)\n* [在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)\n\n## 关于包配置\n\npom.xml 文件中的 `groupId` 和 `artifactId` 字段为包创建唯一标识符，注册表使用该标识符将包链接到注册表。 有关详细信息，请参阅 Apache Maven 文档中的[将项目上传到中央存储库的指南](https://maven.apache.org/repository/guide-central-repository-upload.html)。\n\n> \\[!WARNING] Apache Maven 包必须遵循命名约定，因此 `artifactId` 字段应仅包含小写字母、数字或连字符。 有关详细信息，请参阅 maven.apache.org 文档中 [Maven 坐标的命名约定](https://maven.apache.org/guides/mini/guide-naming-conventions.html)。 如果在项目名称中使用大写字母，将收到 *422 Unprocessable Entity* 响应。\n\npom.xml 文件还包含 Maven 将在其中部署包的分发管理存储库的配置。 每个仓库都必须有名称和部署 URL。 可在运行 Maven 的用户主目录中的 .m2/settings.xml 文件中配置这些存储库的身份验证。\n\n可以使用 `setup-java` 操作配置部署存储库以及该存储库的身份验证。 有关详细信息，请参阅 [`setup-java`](https://github.com/actions/setup-java)。\n\n## 将包发布到 Maven 中心仓库\n\n每次创建新版本时，都可以触发工作流程来发布包。 以下示例中的工作流在 `release` 事件以 `created` 类型触发时运行。 如果 CI 测试通过，工作流程将包发布到 Maven 中心仓库。 有关 `release` 事件的详细信息，请参阅“[触发工作流的事件](/zh/actions/using-workflows/events-that-trigger-workflows#release)”。\n\n在此工作流中，可以使用 `setup-java` 操作。 此操作将给定版本的 JDK 安装到 `PATH` 中，但同时会配置 Maven settings.xml 以发布包。 默认情况下，设置文件将配置用于 GitHub Packages，但可以将其配置为部署到另一个包注册表，如 Maven 中心仓库。 如果已在 *pom.xml* 中配置了分发管理存储库，则可在调用 `id`期间指定该 `setup-java`。\n\n例如，如果你通过 OSSRH 托管项目部署到 Maven Central 存储库，你的 *pom.xml* 可以指定分发管理存储库，其 `id` 为 `ossrh`。\n\n```xml copy\n<project ...>\n  ...\n  <distributionManagement>\n    <repository>\n      <id>ossrh</id>\n      <name>Central Repository OSSRH</name>\n      <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>\n    </repository>\n  </distributionManagement>\n</project>\n```\n\n使用此配置，可通过将存储库管理 `id` 指定到 `setup-java` 操作，创建一个将包发布到 Maven 中央存储库的工作流。 您还需要提供包含用户名和密码的环境变量来对仓库进行认证。\n\n在部署步骤中，你需要将环境变量设置为向仓库验证的用户名，以及用密码或令牌配置为进行身份验证的密钥。 有关详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。\n\n```yaml copy\nname: Publish package to the Maven Central Repository\non:\n  release:\n    types: [created]\njobs:\n  publish:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Set up Maven Central Repository\n        uses: actions/setup-java@v4\n        with:\n          java-version: '11'\n          distribution: 'temurin'\n          server-id: ossrh\n          server-username: MAVEN_USERNAME\n          server-password: MAVEN_PASSWORD\n      - name: Publish package\n        run: mvn --batch-mode deploy\n        env:\n          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}\n          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}\n```\n\n此工作流程执行以下步骤：\n\n1. 检出项目仓库的副本。\n2. 设置Java JDK，并配置 Maven *settings.xml* 文件，以使用 `ossrh` 和 `MAVEN_USERNAME` 环境变量为 `MAVEN_PASSWORD` 存储库添加身份验证。\n3. 运行 `mvn --batch-mode deploy` 命令以发布到 `ossrh` 存储库。 `MAVEN_USERNAME` 环境变量将使用 `OSSRH_USERNAME` 机密的内容进行设置，`MAVEN_PASSWORD` 环境变量将使用 `OSSRH_TOKEN` 机密的内容进行设置。\n\n   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。\n\n## 将包发布到 GitHub Packages\n\n每次创建新版本时，都可以触发工作流程来发布包。 以下示例中的工作流在 `release` 事件以 `created` 类型触发时运行。 如果 CI 测试通过，工作流程会将包发布到 GitHub Packages。 有关 `release` 事件的详细信息，请参阅“[触发工作流的事件](/zh/actions/using-workflows/events-that-trigger-workflows#release)”。\n\n在此工作流中，可以使用 `setup-java` 操作。 此操作将给定版本的 JDK 安装到 `PATH` 中，并设置 Maven settings.xml 以将包发布到 GitHub Packages。 生成的 settings.xml 为服务器定义身份验证，该服务器的 \\_\\_ 为 `id`，使用 `github` 环境变量作为用户名，使用 `GITHUB_ACTOR` 环境变量作为密码。\n`GITHUB_TOKEN` 环境变量被分配了特殊 `GITHUB_TOKEN` 机密的值。\n\n每当工作流中的作业开始时，`GITHUB_TOKEN` 机密都会设置为存储库的访问令牌。 应在工作流文件中设置此访问令牌的权限，以授予 `contents` 权限的读取访问权限，并授予 `packages` 权限的写入访问权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)”。\n\n对于基于 Maven 的项目，你可以通过在 *pom.xml* 文件中创建分发存储库来使用这些设置，其 `id` 为 `github`，指向你的 GitHub Packages 终结点。\n\n例如，如果组织名为“octocat”而存储库名为“hello-world”，则 pom.xml 中的 GitHub Packages 配置将类似于下面的例子。\n\n```xml copy\n<project ...>\n  ...\n  <distributionManagement>\n    <repository>\n      <id>github</id>\n      <name>GitHub Packages</name>\n      <url>https://maven.pkg.github.com/octocat/hello-world</url>\n    </repository>\n  </distributionManagement>\n</project>\n```\n\n使用此配置，你可以创建一个工作流，利用自动生成的 settings.xml 将包发布到 GitHub Packages。\n\n```yaml copy\nname: Publish package to GitHub Packages\non:\n  release:\n    types: [created]\njobs:\n  publish:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write\n    steps:\n      - uses: actions/checkout@v6\n      - uses: actions/setup-java@v4\n        with:\n          java-version: '11'\n          distribution: 'temurin'\n      - name: Publish package\n        run: mvn --batch-mode deploy\n        env:\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n此工作流程执行以下步骤：\n\n1. 检出项目仓库的副本。\n2. 设置Java JDK，并自动配置 Maven *settings.xml* 文件，以添加 `github` Maven 存储库的身份验证，以使用 `GITHUB_TOKEN` 环境变量。\n3. 运行 `mvn --batch-mode deploy` 命令以发布到 GitHub Packages。 `GITHUB_TOKEN` 环境变量将使用 `GITHUB_TOKEN` 机密的内容进行设置。 `permissions` 键指定了对 `GITHUB_TOKEN` 授予的访问权限。\n\n   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。\n\n## 发布包到 Maven 中心仓库和 GitHub Packages\n\n可以通过对每个注册表使用 `setup-java` 操作来将包发布到 Maven 中央仓库和 GitHub Packages。\n\n确保你的\\_pom.xml\\_文件中包含用于 GitHub 存储库和你的 Maven 中央存储库提供商的分发管理存储库。 例如，如果通过 OSSRH 托管项目部署到中央存储库，你可以在分发管理存储库中，通过将 `id` 设置为 `ossrh` 来指定它，并且你可能希望通过将 `id` 设置为 `github` 在同一存储库中指定 GitHub Packages。\n\n```yaml copy\nname: Publish package to the Maven Central Repository and GitHub Packages\non:\n  release:\n    types: [created]\njobs:\n  publish:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write\n    steps:\n      - uses: actions/checkout@v6\n      - name: Set up Java for publishing to Maven Central Repository\n        uses: actions/setup-java@v4\n        with:\n          java-version: '11'\n          distribution: 'temurin'\n          server-id: ossrh\n          server-username: MAVEN_USERNAME\n          server-password: MAVEN_PASSWORD\n      - name: Publish to the Maven Central Repository\n        run: mvn --batch-mode deploy\n        env:\n          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}\n          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}\n      - name: Set up Java for publishing to GitHub Packages\n        uses: actions/setup-java@v4\n        with:\n          java-version: '11'\n          distribution: 'temurin'\n      - name: Publish to GitHub Packages\n        run: mvn --batch-mode deploy\n        env:\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n此工作流调用 `setup-java` 操作两次。 每次 `setup-java` 操作运行时，它都会覆盖用于发布包的 Maven *settings.xml* 文件。 为向存储库进行身份验证，settings.xml 文件引用分发管理存储库 \\_\\_ 以及用户名和密码。\n\n此工作流程执行以下步骤：\n\n1. 检出项目仓库的副本。\n2. 第一次调用 `setup-java`。 这将为 \\_\\_ 存储库配置 Maven settings.xml 文件，并将身份验证选项设置为在下一步中定义的环境变量。\n3. 运行 `mvn --batch-mode deploy` 命令以发布到 `ossrh` 存储库。 `MAVEN_USERNAME` 环境变量将使用 `OSSRH_USERNAME` 机密的内容进行设置，`MAVEN_PASSWORD` 环境变量将使用 `OSSRH_TOKEN` 机密的内容进行设置。\n4. 第二次调用 `setup-java`。 这将自动配置 Maven settings.xml 文件以用于 GitHub Packages。\n5. 运行 `mvn --batch-mode deploy` 命令以发布到 GitHub Packages。 `GITHUB_TOKEN` 环境变量将使用 `GITHUB_TOKEN` 机密的内容进行设置。 `permissions` 键指定了对 `GITHUB_TOKEN` 授予的访问权限。\n\n   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。"}