使用 MC-Publish 将模组发布到 Curseforge、Modrinth 和 Github

本页翻译自 publishing_mods_using_github_actions，如有过时的地方可参考原文。

MC-Publish 是一个 GitHub action，由 Kir-Antipov 制作，可以在 GitHub、CurseForge 和 Modrinth API 中交互，以上传您的模组文件。本页面会大致描述基本的设置过程，你需要 阅读 GitHub 文档以了解详细信息。

Github Actions 本质上是由 GitHub 服务器执行的命令，可以免费试用，只要你的 GitHub 存储库是公开的，且有限制，如果不是那么就不会妨碍您的使用。在软件开发中，Github Actions 和类似的工作流自动化系统是标准场所，并且极大地帮助您使得部署过程（例如发布新版本的模组）尽可能无缝衔接。

如果您不愿手动将您的模组上传到多个平台上，那么这就是解决方案。

您需要已完成以下操作：

1. 在 GitHub 上，创建您的模组的存储库
2. 将您的模组的一个版本上传到 Curseforge 和 Modrinth 上并且被批准

如果需要让 GitHub 为我们做点什么，我们需要告诉服务器，我们到底需要什么。因此，我们需要在 /.github/workflows 中创建一个 .yml 文件。你可以将这个 .yml 文件想象成您的 GitHub Action 的配置文件。文件的命名方式不重要，但您应该选择一个相关的名称。YAML 的概念与 JSON 的类似，但是语法不同。就像 Python 那样，你不需要使用花括号 {}，而只需要使用缩进来声明你的结构。

你的 .yml 文件的基本结构看上去应该像这样：

name: 发布到 Github、Curseforge 和 Modrinth    #你的 github.com 上的 GitHub Action 的名称
 
on: [ pull_request, workflow_dispatch ]           #何时执行你的 GitHub Action，'pull_request' -> 在每次合并（拉取）请求，'workflow_dispatch' -> 允许通过 github.com 手动执行

env:                                              #环境变量，后续可以使用 ${{ env.MINECRAFT_VERSION }} 引用，可以用作重复的信息并允许后续模组新的更新中快速更改
  MINECRAFT_VERSION: 1.19.2                        
  JAVA_VERSION: 17                   

permissions:
  contents: write

jobs:                                             #在这里你就会实际告诉 GitHub 的服务器需要做什么
  build:                                          #要发布你的模组，你只需要一个 job，这里称为 build。
    runs-on: ubuntu-latest                        #'runs-on' 指定了操作系统（linux）。
    steps:                                        #在 'steps' 中你会列举出所有单独的命令，例如 Kir-Antipov 的 MC-Publish。
      ...

我建议保持 on: [ pull_request, workflow_dispatch ] 并相应地使用 git 分支。这意味着，在每个分支上开发自己的更新，并在准备发布的时候合并到主分支中。如果这个确实无法满足你的需求，可以检查不同的触发或者直接使用 workflow_dispatch。记住，设置的时候你不需要意外地运行你的 GitHub Action。

基本的环境变量应该包括：

• Minecraft 版本
• Java 版本
• 你的模组版本
• 你的模组发行名称
• 发布令牌（后面讲到）

这可以说是你的 .yml 文件中最重要的部分！

首先我们需要看看一个步骤的语法，准备所有的先行步骤，然后在走 MC-Publish。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 示例设置
        if: ${{ condition is met }}
        uses: actions/common-action
        with: 
          variable1: 一些值
          variable2: 另一些值
        run: ls -a
        
      - name: 另一个示例设置
 
        ...

• name 步骤的名称，应该准确描述该步骤。
• if 需要返回 true 的条件，符合条件才执行步骤。
• uses 这里你可以指定额外的 GitHub Action。你应该自己编写一切，但如果已经有人帮你写好了呢？Kir-Antipov 的 MC-Publish 就是其中一个例子。
• with 如果你指定 GitHub Action 时使用了 uses，你可以输入预先定义的变量以及各自的值。
• run 在命令行中执行命令。

以下步骤复制了你能够在电脑上开发模组之前需要完成的步骤，就想象一下你是一个简单的 linux 服务器，突然有人想要你上传他们的 minecraft 模组，你甚至不知道 Java 是什么。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检查环境变量
        run: env

      - name: 签出存储库
        uses: actions/checkout@v3
        with:
          submodules: true

      - name: 设置 Java
        uses: actions/setup-java@v2
        with:
          distribution: "temurin"
          java-version: 17

      - name: 使 Gradle Wrapper 可执行
        if: ${{ runner.os != 'Windows' }}
        run: chmod +x ./gradlew

      - name: 构建
        run: ./gradlew clean build
 
        ...

虽然上面这些步骤是必要的，但是你不需要完全理解。如果你有兴趣想要完全理解的话，我建议你入门 linux。

执行“Build”步骤可能要最长时间（大概 3 分钟），所以不要担心是否出错，出错了会提示的。

本段落本质上并不完整，如要有全面的了解可以 检查 MC-Publish 的官方 GitHub 文档。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ...
      
      - name: 发布（CurseForge/Modrinth/Github）
        uses: Kir-Antipov/mc-publish@v3.2                                   #指定 MC-Publish Github Action 版本 3.2
        with:
          curseforge-id: 123456                                             #你的 curseforge 项目的 id
          curseforge-token: "${{env.CURSEFORGE_TOKEN}}"
          
          modrinth-id: 1q2w3e4r                                             #你的 modrinth 项目的 id
          modrinth-token: "${{env.MODRINTH_TOKEN}}"
          
          github-tag: "v${{env.VERSION}}"
          github-token: "${{env.GITHUB_TOKEN}}"

          name: "${{env.RELEASE_NAME}}"                             
          version: "${{env.VERSION}}"
          version-type: release
          changelog-file: CHANGELOG.md                                      #指定新更新的内容的文件（路径从项目根目录开始）

          loaders: fabric
          game-versions: "${{env.MINECRAFT_VERSION}}"
          java: "${{env.JAVA_VERSION}}"

CURSEFORGE_TOKEN、MODRINTH_TOKEN 和 GITHUB_TOKEN 本质上是用来验证你自己的密码，这意味着对应了你的账号，而不是你的模组。这可以确保只有你能通过 API 来推送更新。当你正常上传的时候，你会在登录的时候验证自己。在哪里找到这些令牌呢？每个平台有不同的步骤：

Github Settings > Developer Settings > Personal access tokens > Tokens (classic) ⇒ 按 “Generate new token” and choose classic ⇒ select the 'repo' scope (write a descriptive note, 90 days expiration is recommended, you will need to generate a new token afterwards) ⇒ 按“Generate token”

Modrinth Settings ⇒ Authorization token

Curseforge Settings > My API Tokens ⇒ 选择一个描述性的名称并点击 “Generate Token”

It is strongly recommended that you save the authentication tokens somewhere safe, e.g. a password manager. Github won't let you access your token after you have generated it! 强烈建议将这些令牌存储在安全的地方，例如密码管理器。GitHub不会在你生成之后让你访问这些令牌！

现在你有了需要的所有令牌，你需要让 GitHub Action 能够访问这些令牌。到你的 GitHub 模组存储库的 Settings 页面，并前往 Secrets > Actions。将所有的令牌添加为 secrets。你需要在你的 .yml 文件中引用你在这里提供的名称。例如，命名为 PUBLISH_CURSEFORGE_TOKEN 的 secret 可以这样引用：

${{ secrets.PUBLISH_CURSEFORGE_TOKEN }}

name: 发布到 Github、Curseforge 和 Modrinth    
 
on: [ pull_request, workflow_dispatch ]           

env:                                              
  MINECRAFT_VERSION: 1.19.2                        
  JAVA_VERSION: 17      
  VERSION: 1.1.0+1.19.2  
  RELEASE_NAME: 用于 Minecraft 1.19.2 的示例模组 1.1.0
  MODRINTH_TOKEN: ${{ secrets.PUBLISH_MODRINTH_TOKEN }}
  CURSEFORGE_TOKEN: ${{ secrets.PUBLISH_CURSEFORGE_TOKEN }}
  GITHUB_TOKEN: ${{ secrets.PUBLISH_GITHUB_TOKEN }}           

permissions:
  contents: write

jobs:                                             
  build:                                          
    runs-on: ubuntu-latest                        
    steps:                                        
      - name: 检查环境变量
        run: env

      - name: 签出存储库
        uses: actions/checkout@v3
        with:
          submodules: true

      - name: 设置 Java
        uses: actions/setup-java@v2
        with:
          distribution: "temurin"
          java-version: 17

      - name: 使 Gradle Wrapper 可执行
        if: ${{ runner.os != 'Windows' }}
        run: chmod +x ./gradlew

      - name: 构建
        run: ./gradlew clean build
        
      - name: 发布（CurseForge/Modrinth/Github）
        uses: Kir-Antipov/mc-publish@v3.2                                   
        with:
          curseforge-id: 123456                                             
          curseforge-token: "${{env.CURSEFORGE_TOKEN}}"
          
          modrinth-id: 1q2w3e4r                                             
          modrinth-token: "${{env.MODRINTH_TOKEN}}"
          
          github-tag: "v${{env.VERSION}}"
          github-token: "${{env.GITHUB_TOKEN}}"

          name: "${{env.RELEASE_NAME}}"                             
          version: "${{env.VERSION}}"
          version-type: release
          changelog-file: CHANGELOG.md                                      

          loaders: fabric
          game-versions: "${{env.MINECRAFT_VERSION}}"
          java: "${{env.JAVA_VERSION}}"

回顾一下，这是您现在应该拥有的：

• Wie每个平台新生成的验证令牌
• 验证令牌存储在你的 GitHub 存储库的 secrets 中
• 在 /.github/workflows 的一个 .yml 文件，并推送到你的 GitHub 存储库中
• 你的项目根目录中的空白 CHANGELOG.md 文件

如果你拥有所有这些，你就完成了！您现在可以使用新创建的 Github Action 为您的模组部署更新！

以下是不适合一般教程的有用资源列表。

更新你的模组时，你需要看看的几个地方。

• 更新版本号
  • 在 src/fabric.mod.json，中，在 “version”: “1.1.0+1.19.2”
  • 在 gradle.properties（通常情况），在 mod_version = 1.1.0+1.19.2
  • 在 .github/workflows/publish.yml 在 VERSION: 1.1.0+1.19.2 和 RELEASE_NAME: 用于 Minecraft 1.19.2 的示例模组 1.1.0
• 更新 CHANGELOG.md 中的更新记录
• （如果你使用推荐的工作流程）将更新分支合并到当前默认分支

请检查官方文档。我建议使用 fabric.mod.json 方法。

由于 Modrinth 更新了 API，一些人可能在通过这些 API 上传时会遇到问题，这种情况下可以将 modrinth 的部分从 GitHub 和 Curseforge 分开。你可以复制 MC-Publish 步骤并删除 with 中的现在不必要的输入部分来轻松完成此操作。你现在应该有两个独立的步骤。

将发布到 modrinth 的步骤的版本更改为 2.1 → uses: Kir-Antipov/mc-publish@v2.1