强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

PaperMC 插件开发完全指南 / 第 17 章:发布与分发

第 17 章:发布与分发

将你的插件发布到主流平台,学习版本管理和推广策略。


17.1 主要发布平台

平台网址特点适合
SpigotMCspigotmc.org最大的插件市场面向服主
Hangarhangar.papermc.ioPaper 官方平台Paper 插件
Modrinthmodrinth.com现代化,支持多类型通用
GitHubgithub.com开源项目开发者
BukkitDevdev.bukkit.org老牌平台已较少更新

17.2 发布到 SpigotMC

注册与准备

  1. 注册 SpigotMC 账号: https://www.spigotmc.org/
  2. 验证邮箱
  3. 准备以下材料:
    • 插件名称和描述
    • 至少一张截图或 Logo
    • 编译好的 JAR 文件
    • 源代码链接(可选)

资源页面编写

# MyPlugin - 自定义插件

## ✨ 功能
- 功能一:经济系统
- 功能二:传送系统
- 功能三:商店系统

## 📦 安装
1. 将 JAR 文件放入 `plugins/` 目录
2. 重启服务器
3. 编辑 `plugins/MyPlugin/config.yml`
4. 执行 `/myplugin reload` 重载

## 📋 命令
| 命令 | 说明 | 权限 |
|------|------|------|
| /myplugin | 主命令 | myplugin.use |
| /heal | 治疗 | myplugin.heal |
| /warp | 传送 | myplugin.warp |

## 🔧 配置
```yaml
settings:
  debug: false
  language: zh-CN

📜 依赖

  • Paper 1.20.4+
  • PlaceholderAPI(可选)

💬 Discord

加入我们的 Discord


### 版本号规范

主版本.次版本.修订号

1.0.0 — 首个正式版本 1.1.0 — 新功能 1.1.1 — Bug 修复 2.0.0 — 大版本更新(可能有破坏性变更)


---

## 17.3 发布到 Hangar

Hangar 是 PaperMC 官方的插件发布平台。

### 注册步骤

1. 访问 https://hangar.papermc.io/
2. 使用 GitHub 账号登录
3. 创建新项目

### Hangar 特有功能

| 功能 | 说明 |
|------|------|
| **频道(Channels)** | Release, Snapshot, Beta |
| **版本范围** | 指定支持的 Minecraft 版本范围 |
| **平台选择** | Paper, Velocity, Waterfall |
| **GitHub 集成** | 自动从 GitHub Release 同步 |
| **API** | 程序化管理发布 |

### hangar-publish 插件(Gradle)

```kotlin
// build.gradle.kts
plugins {
    id("io.papermc.hangar-publish") version "0.1.2"
}

hangarPublish {
    credentials {
        apiKey.set(System.getenv("HANGAR_API_KEY"))
    }
    version {
        channel.set("Release")
        // Minecraft 版本范围
        platformVersions.set(listOf("1.20.4", "1.21", "1.21.1"))
    }
}

17.4 发布到 Modrinth

Modrinth 是一个现代化的模组平台,支持插件、Mod、资源包等。

Modrinth API 发布

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - run: mvn clean package

      # 发布到 Modrinth
      - name: Upload to Modrinth
        uses: Kir-Antipov/[email protected]
        with:
          modrinth-id: your-project-id
          modrinth-token: ${{ secrets.MODRINTH_TOKEN }}
          files: target/*.jar
          name: MyPlugin v${{ github.ref_name }}
          version: ${{ github.ref_name }}
          game-versions: |
            1.21
            1.21.1
          loaders: |
            paper
            spigot

17.5 CI/CD 自动发布

完整的 GitHub Actions 发布工作流

name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Build
        run: mvn clean package

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: target/*.jar
          generate_release_notes: true
          draft: false
          prerelease: false

      # 发布到多个平台
      - name: Publish to Modrinth
        uses: Kir-Antipov/[email protected]
        with:
          modrinth-id: ${{ vars.MODRINTH_PROJECT_ID }}
          modrinth-token: ${{ secrets.MODRINTH_TOKEN }}
          files: target/*.jar
          loaders: paper,spigot
          game-versions: "1.21.4"

      - name: Publish to Hangar
        uses: WiIIiam278/hangar-publish@v1
        with:
          hangar-token: ${{ secrets.HANGAR_TOKEN }}
          files: target/*.jar
          channel: Release

17.6 版本管理

语义化版本(SemVer)

MAJOR.MINOR.PATCH

MAJOR: 不兼容的 API 变更
MINOR: 向后兼容的功能新增
PATCH: 向后兼容的 Bug 修复

Maven 版本管理

<version>1.2.3</version>

<!-- 开发中 -->
<version>1.3.0-SNAPSHOT</version>

Git 标签工作流

# 开发
git add .
git commit -m "feat: 添加商店系统"
git push

# 发布新版本
git tag -a v1.2.0 -m "版本 1.2.0 - 商店系统"
git push origin v1.2.0

# 补丁版本
git tag -a v1.2.1 -m "版本 1.2.1 - 修复 Bug"
git push origin v1.2.1

17.7 CHANGELOG 编写

# Changelog

## [1.2.0] - 2026-05-10

### Added
- 商店系统
- 排行榜系统
- PlaceholderAPI 支持

### Changed
- 优化传送命令
- 更新依赖版本

### Fixed
- 修复经济系统偶发余额异常
- 修复 GUI 点击延迟问题

## [1.1.0] - 2026-04-01

### Added
- 传送地标系统
- 自定义物品

## [1.0.0] - 2026-03-01

### Added
- 初始发布
- 基础命令系统
- 经济系统

17.8 README 编写

# MyPlugin

[![Build](https://github.com/user/myplugin/actions/workflows/build.yml/badge.svg)]
[![Version](https://img.shields.io/spiget/version/12345)]
[![Downloads](https://img.shields.io/spiget/downloads/12345)]
[![Rating](https://img.shields.io/spiget/rating/12345)]

> 一个功能强大的 Minecraft 插件

## 功能
- 💰 经济系统
- 🏠 传送地标
- 🛒 商店系统
- 📊 排行榜

## 安装
1. 下载最新版本
2. 放入 `plugins/` 目录
3. 重启服务器

## 命令
| 命令 | 说明 | 权限 |
|------|------|------|
| `/myplugin` | 主命令 | `myplugin.use` |

## 开发
```bash
git clone https://github.com/user/myplugin.git
cd myplugin
mvn clean package

License

MIT License


---

## 17.9 推广策略

| 策略 | 方法 |
|------|------|
| **SpigotMC 论坛** | 发布资源、参与讨论 |
| **Discord** | 建立社区服务器 |
| **YouTube** | 制作演示视频 |
| **GitHub** | 开源吸引贡献者 |
| **Wiki** | 完善文档 |
| **示例服务器** | 让用户体验功能 |

---

## 17.10 用户支持

### 支持渠道

- **GitHub Issues**: Bug 报告和功能请求
- **Discord**: 实时交流和社区支持
- **SpigotMC 讨论**: 公开讨论
- **Wiki/文档**: 自助查阅

### Issue 模板

```markdown
## Bug 报告

**描述**
简要描述问题

**复现步骤**
1. 执行 '...'
2. 点击 '...'
3. 报错

**期望行为**
描述期望的行为

**实际行为**
描述实际的行为

**环境**
- 插件版本: 1.2.0
- Paper 版本: 1.21.4
- Java 版本: 21

**日志**
(粘贴相关日志)

17.11 常见问题

问题解决方案
SpigotMC 审核慢确保资源描述完整,耐心等待
低下载量改善描述,添加截图和视频
差评积极回应,修复问题
版权纠纷使用正确的 License,注明来源

17.12 扩展阅读


17.13 本章小结

要点内容
发布平台SpigotMC(最大)、Hangar(Paper 官方)、Modrinth
CI/CDGitHub Actions 自动构建和发布
版本管理语义化版本 + Git 标签
文档README + CHANGELOG + Wiki
推广社区参与 + 内容营销

下一章: 第 18 章:最佳实践 — 代码规范、性能优化、安全建议和兼容性。