GTO Publish Plugin

可复用的多目标发布 Gradle 插件，支持 Maven、GitHub Release、CurseForge。

项目地址 / Repository: https://github.com/GregTech-Odyssey/GradlePublishPlugin

前置要求 / Prerequisites

消费项目必须满足以下条件才能使用此插件：

1. 应用 maven-publish 插件并配置 publishing {} 块（见下方 配置 章节）

2. 配置凭证（见下方 凭证配置 章节）

3. 版本号格式需符合 x.x.x[-suffix]（见下方 版本格式 章节）

注意：本插件会自动将 archivesName 修改为 {name}-{modLoader}-{mcVersion}（modLoader 自动小写）。例如 archivesName = 'registrylib' + modLoader = 'NeoForge' + minecraftVersion = '26.1' → registrylib-neoforge-26.1。本地 JAR、Maven、GitHub、CurseForge 所有文件名统一为 registrylib-neoforge-26.1-x.x.x.jar。GitHub Release 的 tag/name 使用 {modLoader}-{mcVersion}-{version}，例如 neoforge-26.1-7.0.8。消费者引用：implementation("com.gto:registrylib-neoforge-26.1:7.0.8")。

非 MC 库模式：如果项目是普通 Java 库（不依赖 Minecraft/加载器），只需不填 minecraftVersion 和 modLoader（两者都留空）。此时插件不调用 Mojang API，archivesName 保持原始值，Maven 和 GitHub Release 照常发布（GitHub tag 直接使用版本号），CurseForge 会自动跳过（仅支持 MC 模组）。

安装

在消费项目的 settings.gradle 中配置 pluginManagement：

// settings.gradle
pluginManagement {
    repositories {
        maven { url 'https://maven.gtodyssey.com/releases' }
        gradlePluginPortal()
    }
}

// build.gradle
plugins {
    id 'com.gto.gtopublishgradleplugin' version '1.0.24'
}

版本格式

项目版本必须符合 x.x.x[-suffix] 格式：

• x.x.x：三段数字版本号
• suffix：仅允许小写字母、数字和连字符
• -alpha、-beta、-release 或省略为发布版本（省略等同于 -release）
• 其他后缀为分支版本；执行 gtoPublish 时仅发布到 Maven，不创建 GitHub Release，也不上传 CurseForge

版本号示例	实际发布版本	类型	GitHub 行为	CurseForge releaseType
1.0.0-alpha	1.0.0-alpha	Alpha	Pre-release，名称前缀 [Alpha]	alpha
1.0.0-beta	1.0.0-beta	Beta	Pre-release，名称前缀 [Beta]	beta
1.0.0-release	1.0.0	Release	正式发布	release
1.0.0	1.0.0	Release	正式发布	release
1.0.0-feature-login	1.0.0-feature-login	分支版本	不发布	不发布

注意：-release 后缀会自动从所有发布产物的文件名和版本号中去除。

配置

方式一：通过 gtoPublish 扩展块（推荐）

gtoPublish {
    publishMaven      = true        // 默认 true
    publishGithub     = false       // 默认 false
    publishCurseforge = false       // 默认 false
    mavenRepoName     = 'gtodysseyRepository'  // 默认值
    mavenRepoUrl      = 'releases'  // 必填，可选值: 'releases' 或 'private'
    minecraftVersion      = '26.1'      // 模组必填；普通 Java 库留空
    modLoader         = 'NeoForge'  // 模组必填（NeoForge, Forge, Fabric 等）；普通 Java 库留空
    githubRepo        = 'owner/repo-name'      // GitHub 仓库（启用 GitHub 发布时必填）
    curseforgeProjectId   = '123456'    // CurseForge 项目 ID（启用 CurseForge 时必填）
    curseforgeJavaVersion = 'Java 25'   // Java 版本（启用 CurseForge 时必填，如 Java 8, Java 17, Java 21, Java 25）
    curseforgeEnvironment = 'both'      // Environment 组（默认 both）：both / client / server
}

curseforgeEnvironment 对应 CurseForge 上传时的 Environment 版本组（API 必填，否则 error 1021）：

配置值	上传到 CurseForge 的 gameVersions	适用场景
both（默认）	Client + Server	双端模组
client	Client	仅客户端模组
server	Server	仅服务端模组

别名：client-only、server-only、client-server、all（等同 both）。

mavenRepoUrl 支持以下简写值：

简写	实际 URL
releases	https://maven.gtodyssey.com/releases
private	https://maven.gtodyssey.com/private

本插件会自动将 modLoader(小写) 和 MC 版本编入 archivesName，所有文件名统一：

{repoUrl}/{group}/{name}-{modLoader}-{mcVersion}/{version}/{name}-{modLoader}-{mcVersion}-{version}.jar

例如：https://maven.gtodyssey.com/releases/com/gto/registrylib-neoforge-26.1/7.0.8/registrylib-neoforge-26.1-7.0.8.jar

本地 JAR：build/libs/registrylib-neoforge-26.1-7.0.8.jar

GitHub Release tag/name：neoforge-26.1-7.0.8

消费者引用方式：implementation("com.gto:registrylib-neoforge-26.1:7.0.8")

完整配置示例

以下示例展示了一个 Minecraft 26.1、模组版本 0.0.2、NeoForge 加载器、Java 25、发布到 releases 仓库并同时发布到 GitHub 和 CurseForge 的完整配置：

// build.gradle
plugins {
    id 'maven-publish'
    id 'com.gto.gtopublishgradleplugin' version '1.0.0'
}

version = '0.0.2'
group = 'com.gto'
base.archivesName = 'my-mod'

publishing {
    repositories {
        maven {
            name = 'gtodysseyRepository'
            url = 'https://maven.gtodyssey.com/releases'
            credentials {
                username = findProperty('gtodysseyRepositoryUsername')
                password = findProperty('gtodysseyRepositoryPassword')
            }
        }
    }
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }
}

gtoPublish {
    publishMaven      = true
    publishGithub     = true
    publishCurseforge = true
    mavenRepoUrl      = 'releases'
    minecraftVersion  = '26.1'
    modLoader         = 'NeoForge'
    githubRepo        = 'GregTech-Odyssey/my-mod'
    curseforgeProjectId   = '123456'
    curseforgeJavaVersion = 'Java 25'
    curseforgeEnvironment = 'both'   // 双端；客户端模组用 'client'，服务端用 'server'
}

注意：publishing {} 块中的仓库 name 必须与 gtoPublish.mavenRepoName 一致（默认 gtodysseyRepository）。

发布后，所有文件名统一为 my-mod-neoforge-26.1-0.0.2.jar： https://maven.gtodyssey.com/releases/com/gto/my-mod-neoforge-26.1/0.0.2/my-mod-neoforge-26.1-0.0.2.jar

GitHub Release tag/name：neoforge-26.1-0.0.2

消费者引用：implementation("com.gto:my-mod-neoforge-26.1:0.0.2")

非 MC 库配置示例（普通 Java 库）

不依赖 Minecraft/加载器的库（如通用工具库、API 库）无需填写 minecraftVersion 和 modLoader。此时插件不校验 Mojang 版本，archivesName 保持原始值，Maven / GitHub Release 照常发布：

// build.gradle
plugins {
    id 'maven-publish'
    id 'com.gto.gtopublishgradleplugin' version '1.0.0'
}

version = '1.2.3'
group = 'com.example'
base.archivesName = 'mylib'

publishing {
    repositories {
        maven {
            name = 'gtodysseyRepository'
            url = 'https://maven.gtodyssey.com/releases'
            credentials {
                username = findProperty('gtodysseyRepositoryUsername')
                password = findProperty('gtodysseyRepositoryPassword')
            }
        }
    }
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }
}

gtoPublish {
    publishMaven      = true
    publishGithub     = true
    mavenRepoUrl      = 'releases'
    githubRepo        = 'GregTech-Odyssey/mylib'
    // 不设置 minecraftVersion / modLoader → 非 MC 库模式
}

发布后文件名保持 mylib-1.2.3.jar，Maven 坐标为 com.example:mylib:1.2.3，GitHub Release tag/name 直接使用 1.2.3。

注意：minecraftVersion 和 modLoader 必须同时填写或同时留空；只填其中一个会报错。CurseForge 仅支持 Minecraft 模组，非 MC 库模式下会跳过 CurseForge 发布（日志中提示）。

方式二：通过 gradle.properties 覆盖

所有扩展属性都可通过项目级或全局 gradle.properties 覆盖：

扩展属性	gradle.properties Key
publishMaven	gtoPublishMaven
publishGithub	gtoPublishGithub
publishCurseforge	gtoPublishCurseforge
mavenRepoName	gtoMavenRepoName
mavenRepoUrl	gtoMavenRepoUrl
githubRepo	gtoGithubRepo
curseforgeProjectId	gtoCurseforgeProjectId
minecraftVersion	gtoMinecraftVersion
modLoader	gtoModLoader
curseforgeJavaVersion	gtoCurseforgeJavaVersion
curseforgeEnvironment	gtoCurseforgeEnvironment

凭证配置

在 ~/.gradle/gradle.properties 中设置（不要提交到项目中）：

:: Windows CMD 一键打开（自动创建目录和文件）
(if not exist "%USERPROFILE%\.gradle" mkdir "%USERPROFILE%\.gradle") & (if not exist "%USERPROFILE%\.gradle\gradle.properties" type nul > "%USERPROFILE%\.gradle\gradle.properties") & notepad "%USERPROFILE%\.gradle\gradle.properties"

# macOS / Linux
mkdir -p ~/.gradle && touch ~/.gradle/gradle.properties && nano ~/.gradle/gradle.properties

# Maven 仓库凭证（联系 xinxinsuried 获取）
gtodysseyRepositoryUsername=你的用户名
gtodysseyRepositoryPassword=你的密码

# GitHub Token
# 获取方式: GitHub → Settings → Developer settings → Personal access tokens → Generate new token
# 需要权限: repo (Full control of private repositories)
gtoGithubToken=ghp_xxxxxxxxxxxx

# CurseForge (如启用)
# 获取方式: https://www.curseforge.com/account/api-tokens
gtoCurseforgeToken=你的API密钥

GitHub Token 也支持环境变量 GH_TOKEN 或 GITHUB_TOKEN。

使用

# 完整发布流程（推荐）
./gradlew gtoPublish

# 仅校验凭证和版本
./gradlew gtoValidate

# 检查 Maven 版本是否已存在
./gradlew gtoCheckMavenVersion

# 单独发布到某个目标
./gradlew gtoPublishMaven
./gradlew gtoPublishGithub
./gradlew gtoPublishCurseforge

推荐发布顺序：Maven → GitHub → CurseForge。GitHub 和 CurseForge 发布前会自动校验本地 JAR 与 Maven 仓库中产物的 SHA-1 一致性，因此 Maven 必须先完成发布。

一键发布说明：使用 gtoPublish 且同时启用了 Maven 时，GitHub 和 CurseForge 任务会自动跳过 Maven SHA-1 一致性校验，因为 Maven 制品已在同一次构建中发布，而部分构建工具（如 NeoForge）会产生非确定性 JAR，重新构建后 SHA-1 会不同。单独执行 gtoPublishGithub 或 gtoPublishCurseforge 时仍会进行校验。

注册的 Task

Task	描述
gtoValidate	校验凭证配置和版本号是否冲突
gtoCheckMavenVersion	检查版本在 Maven 仓库中是否已存在
gtoPublishMaven	通过 maven-publish 发布到 Maven 仓库（archivesName 自动包含 modLoader 和 MC 版本）
gtoPublishGithub	创建 GitHub Release 并上传 JAR（包含 Maven 一致性校验；非 MC 库模式 tag 直接使用版本号）
gtoPublishCurseforge	上传 JAR 到 CurseForge（包含 Maven 一致性校验；仅 MC 模组，非 MC 库模式下跳过）
gtoPublish	总入口：validate → build → 所有启用目标

发布此插件

插件自身版本通过 gradle.properties 中的 gto_plugin_version 配置，同样遵循版本格式规则：

gto_plugin_version=1.0.0-release

./gradlew publish

需要在 ~/.gradle/gradle.properties 中配置 gtodysseyRepositoryUsername 和 gtodysseyRepositoryPassword。