User Tools

Site Tools


zh_cn:tutorial:publishing_mods_using_github_actions

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

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

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

什么是 GitHub Actions?

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

本段落本质上并不完整,如要有全面的了解可以 检查 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_TOKENMODRINTH_TOKENGITHUB_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 }}

完整的 .yml 例子

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.ymlVERSION: 1.1.0+1.19.2RELEASE_NAME: 用于 Minecraft 1.19.2 的示例模组 1.1.0
  • 更新 CHANGELOG.md 中的更新记录
  • (如果你使用推荐的工作流程)将更新分支合并到当前默认分支

处理依赖

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

上传到 Modrinth 的错误

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

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

zh_cn/tutorial/publishing_mods_using_github_actions.txt · Last modified: 2023/02/17 14:44 by solidblock