{"meta":{"title":"使用 Gradle 发布Java包","intro":"本教程介绍如何使用 Gradle 将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-gradle","title":"使用 Gradle 发布Java包"}],"documentType":"article"},"body":"# 使用 Gradle 发布Java包\n\n本教程介绍如何使用 Gradle 将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有关使用 Gradle 为Java项目创建 CI 工作流的详细信息，请参阅 [使用 Gradle 构建和测试 Java](/zh/actions/automating-builds-and-tests/building-and-testing-java-with-gradle)。\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\nbuild.gradle 文件 `groupId` 部分中的 `artifactId` 和 `MavenPublication` 字段为包创建唯一标识符，注册表使用该标识符将包链接到注册表。 这类似于 Maven pom.xml 文件的 `groupId` 和 `artifactId` 字段。 有关详细信息，请参阅 Gradle 文档中的“[Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html)”。\n\nbuild.gradle 文件还包含 Gradle 将向其发布包的分发管理存储库的配置。 每个仓库必须有名称、部署 URL 和验证凭据。\n\n## 将包发布到 Maven 中心仓库\n\n每次创建新版本时，都可以触发工作流程来发布包。 以下示例中的工作流在 `release` 事件以 `created` 类型触发时运行。 如果 CI 测试通过，工作流程将包发布到 Maven 中心仓库。 有关 `release` 事件的详细信息，请参阅“[触发工作流的事件](/zh/actions/using-workflows/events-that-trigger-workflows#release)”。\n\n你可以在指向包存储库的 *build.gradle* 文件的发布块中定义一个新的 Maven 存储库。 例如，如果通过 OSSRH 托管项目部署到 Maven 中央存储库，则 build.gradle 可以指定名称为 \\_\\_ 的存储库。\n\n```groovy copy\nplugins {\n  ...\n  id 'maven-publish'\n}\n\npublishing {\n  ...\n\n  repositories {\n    maven {\n      name = \"OSSRH\"\n      url = \"https://oss.sonatype.org/service/local/staging/deploy/maven2/\"\n      credentials {\n        username = System.getenv(\"MAVEN_USERNAME\")\n        password = System.getenv(\"MAVEN_PASSWORD\")\n      }\n    }\n  }\n}\n```\n\n使用此配置，可以创建一个工作流，通过运行 `gradle publish` 命令将包发布到 Maven 中央存储库。 在部署步骤中，你需要为用于向 Maven 仓库验证身份的用户名和密码或令牌设置环境变量。 有关详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。\n\n```yaml copy\n\n# 此工作流使用未经 GitHub 认证的操作。\n# 它们由第三方提供，并受\n# 单独的服务条款、隐私政策和支持\n# 文档。\n\n# GitHub 建议将操作固定到提交 SHA。\n# 若要获取较新版本，需要更新 SHA。\n# 还可以引用标记或分支，但该操作可能会更改而不发出警告。\n\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 Java\n        uses: actions/setup-java@v4\n        with:\n          java-version: '11'\n          distribution: 'temurin'\n\n      - name: Setup Gradle\n        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2\n\n      - name: Publish package\n        run: ./gradlew publish\n        env:\n          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}\n          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}\n```\n\n此工作流程执行以下步骤：\n\n1. 检出项目仓库的副本。\n2. 设置 Java JDK。\n3. 设置 Gradle 环境。 [`gradle/actions/setup-gradle`](https://github.com/gradle/actions) 操作负责工作流运行之间的缓存状态，并提供所有 Gradle 执行的详细摘要。\n4. 执行 Gradle `publish` 任务以发布到 `OSSRH` Maven 存储库。\n   `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可以在您的 *build.gradle* 的发布配置块中定义一个新的 Maven 存储库，该存储库指向 GitHub Packages。 在仓库配置中，你也可以利用在 CI 工作流程运行中设置的环境变量。 可以使用 `GITHUB_ACTOR` 环境变量作为用户名，并且可以使用 `GITHUB_TOKEN` 机密设置 `GITHUB_TOKEN` 环境变量。\n\n每当工作流中的作业开始时，`GITHUB_TOKEN` 机密都会设置为存储库的访问令牌。 应在工作流文件中设置此访问令牌的权限，以授予 `contents` 权限的读取访问权限，并授予 `packages` 权限的写入访问权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)”。\n\n例如，如果组织名为“octocat”，存储库名为“hello-world”，则 build.gradle 中的 GitHub Packages 配置类似于以下示例。\n\n```groovy copy\nplugins {\n  ...\n  id 'maven-publish'\n}\n\npublishing {\n  ...\n\n  repositories {\n    maven {\n      name = \"GitHubPackages\"\n      url = \"https://maven.pkg.github.com/octocat/hello-world\"\n      credentials {\n        username = System.getenv(\"GITHUB_ACTOR\")\n        password = System.getenv(\"GITHUB_TOKEN\")\n      }\n    }\n  }\n}\n```\n\n使用此配置，可以创建一个工作流，通过运行 `gradle publish` 命令将包发布到 GitHub Packages。\n\n```yaml copy\n\n# 此工作流使用未经 GitHub 认证的操作。\n# 它们由第三方提供，并受\n# 单独的服务条款、隐私政策和支持\n# 文档。\n\n# GitHub 建议将操作固定到提交 SHA。\n# 若要获取较新版本，需要更新 SHA。\n# 还可以引用标记或分支，但该操作可能会更改而不发出警告。\n\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: Setup Gradle\n        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2\n\n      - name: Publish package\n        run: ./gradlew publish\n        env:\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n此工作流程执行以下步骤：\n\n1. 检出项目仓库的副本。\n2. 设置 Java JDK。\n3. 设置 Gradle 环境。 [`gradle/actions/setup-gradle`](https://github.com/gradle/actions) 操作负责工作流运行之间的缓存状态，并提供所有 Gradle 执行的详细摘要。\n4. 执行 Gradle `publish` 任务以发布到 GitHub Packages。\n   `GITHUB_TOKEN` 环境变量将使用 `GITHUB_TOKEN` 机密的内容进行设置。\n   `permissions` 密钥指定 `GITHUB_TOKEN` 机密允许的访问。\n\n   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。\n\n## 发布包到 Maven 中心仓库和 GitHub Packages\n\n可以通过在 *build.gradle* 文件中配置每个包来将包发布到 Maven 中央存储库和 GitHub Packages。\n\n确保 *build.gradle* 文件包含 GitHub 存储库和 Maven 中央存储库提供程序的存储库。\n\n例如，如果通过 OSSRH 托管项目部署到中央存储库，可能希望在分发管理存储库中指定它，并将 `name` 设置为 `OSSRH`。 如果部署到 GitHub Packages，可能希望在分发管理存储库中指定它，并将 `name` 设置为 `GitHubPackages`。\n\n如果组织名为“octocat”，存储库名为“hello-world”，则 build.gradle 中的配置类似于以下示例。\n\n```groovy copy\nplugins {\n  ...\n  id 'maven-publish'\n}\n\npublishing {\n  ...\n\n  repositories {\n    maven {\n      name = \"OSSRH\"\n      url = \"https://oss.sonatype.org/service/local/staging/deploy/maven2/\"\n      credentials {\n        username = System.getenv(\"MAVEN_USERNAME\")\n        password = System.getenv(\"MAVEN_PASSWORD\")\n      }\n    }\n    maven {\n      name = \"GitHubPackages\"\n      url = \"https://maven.pkg.github.com/octocat/hello-world\"\n      credentials {\n        username = System.getenv(\"GITHUB_ACTOR\")\n        password = System.getenv(\"GITHUB_TOKEN\")\n      }\n    }\n  }\n}\n```\n\n使用此配置，可以创建一个工作流，通过运行 `gradle publish` 命令将包发布到 Maven 中央存储库和 GitHub Packages。\n\n```yaml copy\n\n# 此工作流使用未经 GitHub 认证的操作。\n# 它们由第三方提供，并受\n# 单独的服务条款、隐私政策和支持\n# 文档。\n\n# GitHub 建议将操作固定到提交 SHA。\n# 若要获取较新版本，需要更新 SHA。\n# 还可以引用标记或分支，但该操作可能会更改而不发出警告。\n\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\n        uses: actions/setup-java@v4\n        with:\n          java-version: '11'\n          distribution: 'temurin'\n      - name: Setup Gradle\n        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2\n\n      - name: Publish package\n        run: ./gradlew publish\n        env: \n          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}\n          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n此工作流程执行以下步骤：\n\n1. 检出项目仓库的副本。\n2. 设置 Java JDK。\n3. 设置 Gradle 环境。 [`gradle/actions/setup-gradle`](https://github.com/gradle/actions) 操作负责工作流运行之间的缓存状态，并提供所有 Gradle 执行的详细摘要。\n4. 执行 Gradle `publish` 任务以发布到 `OSSRH` Maven 存储库和 GitHub Packages。\n   `MAVEN_USERNAME` 环境变量将使用 `OSSRH_USERNAME` 机密的内容进行设置，`MAVEN_PASSWORD` 环境变量将使用 `OSSRH_TOKEN` 机密的内容进行设置。\n   `GITHUB_TOKEN` 环境变量将使用 `GITHUB_TOKEN` 机密的内容进行设置。\n   `permissions` 密钥指定 `GITHUB_TOKEN` 机密允许的访问。\n\n   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。"}