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

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

第 17 章:发布与分发

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


17.1 主要发布平台

平台 网址 特点 适合
SpigotMC spigotmc.org 最大的插件市场 面向服主
Hangar hangar.papermc.io Paper 官方平台 Paper 插件
Modrinth modrinth.com 现代化,支持多类型 通用
GitHub github.com 开源项目 开发者
BukkitDev dev.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/CD GitHub Actions 自动构建和发布
版本管理 语义化版本 + Git 标签
文档 README + CHANGELOG + Wiki
推广 社区参与 + 内容营销

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