PaperMC 插件开发完全指南 / 第 2 章：开发环境搭建

第 2 章：开发环境搭建

从零开始配置开发环境，掌握 Maven / Gradle 项目结构与初始化流程。

2.1 前置软件安装

必装软件清单

软件	最低版本	推荐版本	用途
JDK	17	21（LTS）	编译和运行
IDE	任意	IntelliJ IDEA Community	代码编写
Maven	3.8	3.9+	构建工具（Maven 方案）
Gradle	8.0	8.10+	构建工具（Gradle 方案）
Git	2.0	最新	版本控制

JDK 安装（推荐 SDKMAN）

# 安装 SDKMAN
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 安装 JDK 21
sdk install java 21.0.3-tem

# 验证
java -version
# openjdk version "21.0.3" ...

IntelliJ IDEA 配置建议

安装 Minecraft Development 插件（可选，但有语法高亮和模板）
设置 JDK: File → Project Structure → SDKs → 添加 JDK 21
启用注解处理: Build → Compiler → Annotation Processors → Enable

2.2 Maven 项目初始化

pom.xml 完整配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 项目坐标 -->
    <groupId>com.example</groupId>
    <artifactId>my-plugin</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>MyPlugin</name>
    <description>一个示例 Paper 插件</description>

    <!-- 编译属性 -->
    <properties>
        <java.version>17</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
    </properties>

    <repositories>
        <!-- Paper 官方仓库 -->
        <repository>
            <id>papermc</id>
            <url>https://repo.papermc.io/repository/maven-public/</url>
        </repository>
    </repositories>

    <dependencies>
        <!-- Paper API -->
        <dependency>
            <groupId>io.papermc.paper</groupId>
            <artifactId>paper-api</artifactId>
            <version>1.21.4-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>

        <!-- Lombok（可选，减少样板代码） -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.34</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- 编译器插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>

            <!-- Shade 插件（打包依赖用，如果不需要可以不加） -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.6.0</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>

        <!-- 确保 resources 目录下的文件被包含 -->
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>
</project>

注意: <filtering>true</filtering> 会让 Maven 在打包时替换 plugin.yml 中的 ${project.version} 等变量。

Maven 常用命令

# 编译
mvn compile

# 打包（生成 JAR）
mvn package

# 清理并重新打包
mvn clean package

# 跳过测试打包
mvn clean package -DskipTests

# 安装到本地仓库
mvn install

2.3 Gradle 项目初始化

build.gradle.kts（Kotlin DSL 推荐）

plugins {
    java
}

group = "com.example"
version = "1.0.0"

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

repositories {
    mavenCentral()
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
    compileOnly("org.projectlombok:lombok:1.18.34")
    annotationProcessor("org.projectlombok:lombok:1.18.34")
}

tasks {
    // 设置编码
    withType<JavaCompile> {
        options.encoding = "UTF-8"
    }

    // 构建 JAR
    jar {
        from(sourceSets.main.get().resources)
        duplicatesStrategy = DuplicatesStrategy.EXCLUDE
    }
}

Gradle 常用命令

# 编译
./gradlew build

# 清理
./gradlew clean

# 编译并跳过测试
./gradlew build -x test

# 查看依赖树
./gradlew dependencies

Maven vs Gradle 对比

维度	Maven	Gradle
配置语言	XML	Kotlin DSL / Groovy DSL
构建速度	较慢（全量）	快（增量 + 缓存）
灵活性	中等	极高
社区生态	成熟，插件丰富	增长快，Android 标准
学习曲线	低	中等
PaperMC 示例	多	中等

推荐: 如果是新项目，建议用 Gradle (Kotlin DSL)；如果已有 Maven 项目或更熟悉 XML 配置，用 Maven。

2.4 项目主类编写

标准主类模板

package com.example.myplugin;

import org.bukkit.plugin.java.JavaPlugin;

import java.util.logging.Level;

public final class MyPlugin extends JavaPlugin {

    // 静态实例，方便其他类获取
    private static MyPlugin instance;

    public static MyPlugin getInstance() {
        return instance;
    }

    @Override
    public void onLoad() {
        // 此阶段插件刚加载，不要注册事件或命令
        instance = this;
        getLogger().log(Level.INFO, "MyPlugin 正在加载...");
    }

    @Override
    public void onEnable() {
        // 保存默认配置
        saveDefaultConfig();

        // 注册事件监听器
        registerListeners();

        // 注册命令
        registerCommands();

        getLogger().log(Level.INFO, "MyPlugin 已启用！");
    }

    @Override
    public void onDisable() {
        // 保存所有数据
        saveData();

        getLogger().log(Level.INFO, "MyPlugin 已禁用！");
    }

    private void registerListeners() {
        var pm = getServer().getPluginManager();
        pm.registerEvents(new PlayerListener(this), this);
        pm.registerEvents(new BlockListener(this), this);
    }

    private void registerCommands() {
        var mainCmd = getCommand("myplugin");
        if (mainCmd != null) {
            mainCmd.setExecutor(new MainCommand(this));
            mainCmd.setTabCompleter(new MainCommand(this));
        }
    }

    private void saveData() {
        // 持久化数据逻辑
    }
}

2.5 快速创建项目的方式

方式一：使用模板仓库

PaperMC 官方提供了项目模板：

# 使用 Git 克隆官方示例
git clone https://github.com/PaperMC/paper-plugin-example.git my-plugin
cd my-plugin

# 修改项目名
# 编辑 pom.xml 中的 groupId、artifactId、version

方式二：Maven Archetype

mvn archetype:generate \
    -DgroupId=com.example \
    -DartifactId=my-plugin \
    -DarchetypeGroupId=org.apache.maven.archetypes \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.4

cd my-plugin
# 然后手动添加 Paper 依赖和 plugin.yml

方式三：IntelliJ IDEA 手动创建

File → New → Project → Maven
设置 GroupId / ArtifactId / Version
填写 pom.xml（参考上文）
创建目录结构
编写 MyPlugin.java 和 plugin.yml

2.6 开发服务器搭建

在开发过程中，需要一个本地测试服务器。

下载 Paper 核心

# 创建测试服务器目录
mkdir -p ~/dev-server && cd ~/dev-server

# 下载 Paper（使用 PaperMC API）
# 访问 https://papermc.io/downloads 获取最新链接
curl -o paper.jar https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/123/downloads/paper-1.21.4-123.jar

# 同意 EULA
echo "eula=true" > eula.txt

# 首次运行（生成配置文件）
java -jar paper.jar --nogui

# 停止后，编辑 server.properties
# 启用离线模式（开发用）
# online-mode=false

启动脚本（start.sh）

#!/bin/bash
java -Xms512M -Xmx2G \
     -XX:+UseG1GC \
     -XX:+ParallelRefProcEnabled \
     -jar paper.jar --nogui

配置 IntelliJ 自动部署

在 IntelliJ 中，可以配置构建后自动复制 JAR 到服务器的 plugins/ 目录：

Run → Edit Configurations
添加 Shell Script 类型的运行配置
命令设置为：

# Maven 构建并复制到服务器
mvn clean package -f /path/to/my-plugin/pom.xml && \
cp /path/to/my-plugin/target/my-plugin-1.0.0.jar ~/dev-server/plugins/

2.7 配置文件处理

默认配置文件

在 src/main/resources/ 下创建 config.yml：

# MyPlugin 配置文件
settings:
  debug: false
  language: zh-CN

messages:
  prefix: "&7[&bMyPlugin&7] "
  no-permission: "&c你没有权限执行此操作！"
  player-only: "&c此命令只能由玩家执行！"

读取配置

// onEnable() 中保存默认配置（如果不存在）
saveDefaultConfig();

// 读取配置
FileConfiguration config = getConfig();
boolean debug = config.getBoolean("settings.debug");
String prefix = config.getString("messages.prefix", "&7[&bMyPlugin&7] ");
String lang = config.getString("settings.language", "zh-CN");

保存配置

// 修改配置
FileConfiguration config = getConfig();
config.set("settings.debug", true);

// 保存到文件
saveConfig();

2.8 常见问题排查

问题	原因	解决方案
`ClassNotFoundException`	Paper API 未标记 `provided`	确认 `<scope>provided</scope>`
`UnsupportedClassVersionError`	JDK 版本不匹配	编译和服务端用同版本 JDK
插件加载报错 `plugin.yml not found`	文件未在 resources 根目录	确认路径为 `src/main/resources/plugin.yml`
中文乱码	编码不一致	设置 `project.build.sourceEncoding=UTF-8`
`NoClassDefFoundError`	Shade 打包的依赖冲突	重定位（Relocate）冲突的包

2.9 扩展阅读

2.10 本章小结

要点	内容
JDK 版本	Paper 1.20.5+ 要求 JDK 17+，推荐 JDK 21
构建工具	Maven 或 Gradle 均可，新手推荐 Maven
依赖范围	Paper API 必须设为 `provided`
项目模板	优先使用 PaperMC 官方示例仓库
测试服务器	本地搭建 Paper 服务器，配置自动部署提高效率

下一章: 第 3 章：插件描述文件 — 深入理解 plugin.yml 的结构、权限声明和命令注册。

PaperMC 插件开发完全指南 / 第 2 章：开发环境搭建

第 2 章：开发环境搭建

2.1 前置软件安装

必装软件清单

JDK 安装（推荐 SDKMAN）

IntelliJ IDEA 配置建议

2.2 Maven 项目初始化

推荐目录结构

pom.xml 完整配置

Maven 常用命令

2.3 Gradle 项目初始化

build.gradle.kts（Kotlin DSL 推荐）

Gradle 常用命令

Maven vs Gradle 对比

2.4 项目主类编写

标准主类模板

2.5 快速创建项目的方式

方式一：使用模板仓库

方式二：Maven Archetype

方式三：IntelliJ IDEA 手动创建

2.6 开发服务器搭建

下载 Paper 核心

启动脚本（start.sh）

配置 IntelliJ 自动部署

2.7 配置文件处理

默认配置文件

读取配置

保存配置

2.8 常见问题排查

2.9 扩展阅读

2.10 本章小结