如何在 Minecraft Paper 服务器上安装和更新插件
将您的 Minecraft 原版服务器迁移到 Paper 而不丢失世界,然后在 VPS 或专用 Linux 服务器上安装和更新插件。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
官方 Minecraft 服务器(原版)无法加载插件。本指南介绍如何在保留世界的前提下将其替换为 Paper,以及如何规范地安装和更新插件。
本指南是创建 Minecraft 服务器的延续,并沿用其中的内容:minecraft 用户、/opt/minecraft/server 文件夹、server.jar 文件和 minecraft.service 服务。
完成本指南后,您将拥有:
- 取代原版服务器的 Java 25 和 Paper,且世界完好无损
- 一条
mc-console命令,用于与 systemd 启动的服务器控制台交互 - 第一个已安装的插件,以及一套安全的更新方法
前提条件
- 已按照创建 Minecraft 服务器指南安装好的服务器
- 使用具有
sudo权限的用户进行 SSH 访问 - 足够的磁盘空间,可存放服务器文件夹的完整副本
检查当前服务器
先查看正在运行的 Minecraft 版本,以及服务器是否已在使用 Paper:
sudo grep -m1 'Starting minecraft server version' /opt/minecraft/server/logs/latest.log
unzip -l /opt/minecraft/server/server.jar | grep -q 'io/papermc/paperclip/Main.class' && echo Paper || echo Vanilla如果第二条命令显示 Paper,说明您的服务器已完成迁移:请先备份,然后直接跳到启用服务控制台。
停止并备份服务器
停止服务器,检查可用空间,然后创建完整归档:
sudo systemctl stop minecraft.service
sudo du -sh /opt/minecraft/server
df -h /opt/minecraft
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-paper-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backups如果您在 screen 中运行服务器,请在其控制台中输入 stop,以代替第一条命令。
安装 Java 25
Paper 推荐使用 Amazon Corretto,它提供 Debian 和 Ubuntu 版本。添加其软件源,然后安装 Java 25:
sudo apt update
sudo apt install -y ca-certificates apt-transport-https gnupg wget curl jq
wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor --yes -o /usr/share/keyrings/corretto-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list
sudo apt update
sudo apt install -y java-25-amazon-corretto-jdk libxi6 libxtst6 libxrender1服务会运行 /usr/bin/java。如果系统中还安装了 Java 21,请将此命令指向 Java 25:
sudo update-alternatives --set java "$(update-alternatives --list java | grep -m1 'java-25')"
java --version输出应以 openjdk 25 开头。
迁移到 Paper 而不丢失世界
迁移的做法是用 Paper 的文件替换 server.jar。由于文件名不变,systemd 服务无需修改,您的 world 文件夹、server.properties 和玩家列表也都保持原位。
创建一个脚本,用于下载最新的稳定构建、校验其哈希值并替换 server.jar。之后每次更新都会用到它:
sudo nano /opt/minecraft/paper-update.sh#!/bin/bash
# 下载 Paper 的最新稳定构建并替换 server.jar
set -euo pipefail
MC_VERSION="${1:?请指定 Minecraft 版本,例如 26.3}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://fill.papermc.io/v3/projects/paper/versions/$MC_VERSION/builds"
cd /opt/minecraft/server
BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
echo "未找到稳定构建:Minecraft $MC_VERSION" >&2
exit 1
fi
URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')
curl -fL -H "User-Agent: $UA" -o server.jar.new "$URL"
echo "$SHA256 server.jar.new" | sha256sum -c -
if [ -f server.jar ]; then
mv server.jar server.jar.old
fi
mv server.jar.new server.jar
echo "Paper $MC_VERSION 构建 $(echo "$BUILD" | jq -r '.id') 已就绪。"在 UA 这一行中,将 your-domain.com 替换为您的网站地址或联系方式:Paper 的 API 要求 User-Agent 能标识您的项目并提供联系方式。
使脚本可执行,然后以 minecraft 用户身份运行:
sudo chmod 755 /opt/minecraft/paper-update.sh
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3server.jar.new: OK 这一行表示下载的文件完好无损。旧的服务器文件会保留为 server.jar.old。
启用服务控制台
基础指南中的服务包含 StandardInput=null,因此没有控制台,而许多插件需要通过命令进行配置。您将使用命名管道为它提供一个控制台,无需开放任何网络端口。
创建承载该管道的单元:
sudo nano /etc/systemd/system/minecraft.socket[Unit]
Description=Minecraft 服务器控制台
PartOf=minecraft.service
[Socket]
ListenFIFO=/run/minecraft.stdin
SocketMode=0600只有 root 可以写入此管道,因此 mc-console 前需要加 sudo。
接着为服务添加补充配置。此文件会附加到 minecraft.service 上,而不会修改它:
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/console.conf[Unit]
Requires=minecraft.socket
After=minecraft.socket
[Service]
Sockets=minecraft.socket
StandardInput=socket
StandardOutput=journal
StandardError=journal
SuccessExitStatus=130 143
TimeoutStopSec=180SuccessExitStatus 可避免服务在正常停止后显示为失败,TimeoutStopSec 则为服务器保存世界留出三分钟时间。
最后创建 mc-console 命令,它会向服务器发送命令并显示其响应:
sudo nano /usr/local/bin/mc-console#!/bin/bash
# 向 Minecraft 控制台发送命令,并显示日志中的响应
if [ "$#" -eq 0 ]; then
echo "用法:mc-console <命令>" >&2
exit 1
fi
if ! systemctl is-active --quiet minecraft.service; then
echo "minecraft.service 服务未启动。" >&2
exit 1
fi
DEBUT=$(date '+%Y-%m-%d %H:%M:%S')
printf '%s\n' "$*" > /run/minecraft.stdin
sleep "${MC_CONSOLE_WAIT:-2}"
journalctl -u minecraft.service --since "$DEBUT" --no-pager -o catsudo chmod 755 /usr/local/bin/mc-console
sudo systemctl daemon-reload启动 Paper
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -f首次启动耗时较长:Paper 会下载 Minecraft 文件,然后转换世界。它会显示 World storage migration is required during startup 并等待 30 秒后继续,如果您没有备份,可以趁此时中断启动。
当出现 Done (…)! For help, type "help" 这一行时,服务器即已就绪。按 Ctrl+C 退出日志跟踪:服务器会继续运行。
验证结果
sudo mc-console version
sudo mc-console plugins
sudo ls /opt/minecraft/server /opt/minecraft/server/world您应该看到:
- 一行
This server is running Paper version 26.3-… Server Plugins (0),因为尚未安装任何插件- 新的
bukkit.yml、spigot.yml文件和config文件夹,以及您的world文件夹
plugins/spark 和 plugins/bStats 文件夹由 Paper 自行创建,这是正常现象。最后,使用 Minecraft 客户端连接服务器,确认您的建筑都还在。
安装插件
选择兼容的插件
下载插件前,请在其页面上确认三点:
- 它适用于 Paper(或 Spigot/Bukkit),而不是 Fabric 或 Forge,后两者属于模组
- 它声明支持您的 Minecraft 版本
- 其依赖项(如有)已列出,因为这些依赖也必须安装
请仅从可靠来源下载:Paper 的插件仓库 Hangar、Modrinth,或项目的官方网站和官方 GitHub 仓库。插件以 minecraft 用户的权限运行,可以读取整个服务器文件夹。
从 Hangar 安装
下面的示例安装 Chunky,这是一款世界预生成插件。先查看其最新版本和支持的 Minecraft 版本:
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://hangar.papermc.io/api/v1/projects/Chunky/versions?limit=1&channel=Release&platform=PAPER"
curl -fsSL -H "User-Agent: $UA" "$API" | jq '.result[0] | {version: .name, minecraft: .platformDependencies.PAPER, fichier: .downloads.PAPER.fileInfo.name}'如果您的 Minecraft 版本在列表中,请下载文件并退出 minecraft 会话:
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
ls -l
exit如果地址为 null,说明该插件托管在其他位置:请按照其 Hangar 页面上的链接操作。
从您的电脑安装
将 .jar 文件上传到服务器,然后以正确的所有者将其放入 plugins 文件夹:
scp MonPlugin.jar 您的用户名@服务器IP:/tmp/sudo install -o minecraft -m 644 /tmp/MonPlugin.jar /opt/minecraft/server/plugins/该文件必须直接位于 plugins 中:Paper 不会读取子文件夹。如果下载的是 .zip 压缩包,请解压并保留适用于 Paper 或 Bukkit 的 .jar。
加载插件
重启服务器,等待出现 Done 这一行,然后列出插件:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fsudo mc-console plugins已加载的插件在游戏中使用 /plugins 时显示为绿色。在日志中,它会被列出,且启动时没有错误消息。
其配置随后位于 /opt/minecraft/server/plugins/<插件名称>/。请以 minecraft 用户身份修改,然后重启服务器或使用该插件自带的重载命令。
更新插件
Paper 可以通过 plugins/update 文件夹在启动时替换插件,因此您无需手动删除任何文件。
先备份插件及其配置:
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server plugins然后将新版本放入 update。以 Chunky 为例:
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://hangar.papermc.io/api/v1/projects/Chunky/versions?limit=1&channel=Release&platform=PAPER"
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
exit最后重启服务器:
sudo systemctl restart minecraft.service启动时,Paper 根据插件文件中声明的名称(而非 .jar 的文件名)来识别插件。它会替换旧版本,保留新文件的名称,并清空 update 文件夹。
更新 Paper
Paper 经常发布修复,并建议至少每周更新一次。但它不建议自动更新,因为可能会与插件发生冲突。
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/avant-maj-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -f请留意启动过程:插件冲突会在此时显现。
调整自动备份
基础指南的 backup.sh 脚本会归档服务器上现有的世界文件夹。要同时备份插件,请将 /opt/minecraft/backup.sh 中的 for 行替换为:
for item in world world_nether world_the_end plugins config server.properties; do恢复备份
如果迁移出现问题,请恢复开始时创建的归档。将文件名替换为 ls 显示的名称:
sudo systemctl stop minecraft.service
sudo ls -lh /opt/minecraft/backups
sudo mv /opt/minecraft/server /opt/minecraft/server-echec
sudo tar -xzf /opt/minecraft/backups/avant-paper-YYYY-MM-DD-HHMM.tar.gz -C /opt/minecraft
sudo systemctl start minecraft.service一切恢复正常后,可以删除 server-echec 文件夹。
故障排除
请始终先阅读日志的开头部分,插件就是在那里加载的:
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/server/logs/latest.log“Minecraft 26.1 and newer requires running the server with Java 25 or above”
服务仍在使用旧版 Java。请检查 java --version,然后重新运行安装 Java 25一节中的 update-alternatives 命令。UnsupportedClassVersionError 错误的原因相同,包括涉及插件的情况。
“Server attempted to load chunk saved with newer version of minecraft!”
世界是由比已安装的 Paper 更新的版本保存的。请使用 paper-update.sh 安装正确的版本,或恢复备份。
paper-update.sh 脚本失败
curl: (22) … 404:Paper 没有此 Minecraft 版本,请检查版本号未找到稳定构建:该版本存在,但尚无稳定构建sha256sum: WARNING:下载的文件已损坏,请重新运行脚本。您的server.jar未被修改
插件无法加载
在日志中搜索插件名称。最常见的消息有:
| 消息 | 原因 | 解决方法 |
|---|---|---|
Unknown/missing dependency plugins 或 UnknownDependencyException |
缺少依赖项 | 安装提示的插件 |
Ambiguous plugin name |
同一插件有两个文件 | 只保留一个 .jar |
Invalid plugin.yml 或 zip END header not found |
这不是 Paper 插件,或文件不完整 | 重新下载正确的文件 |
Unsupported API version |
插件面向的版本高于您的服务器 | 更新 Paper,或选用兼容的插件版本 |
AccessDeniedException 或 “Permission denied”
某个文件是用 sudo 创建的,不属于 minecraft。请将文件夹的所有权交还给该用户。基础指南创建的是没有专用组的系统账户,因此只需指定用户:
sudo chown -R minecraft /opt/minecraft/servermc-console 没有响应
minecraft.service 服务未启动:使用sudo systemctl start minecraft.service启动服务器- 未显示任何响应:服务器仍在启动,或命令耗时较长。请等待
Done这一行出现,或使用sudo MC_CONSOLE_WAIT=10 mc-console version延长等待时间 Socket service minecraft.service already active, refusing:创建管道时服务器正在运行。请使用sudo systemctl stop minecraft.service停止服务器,然后重新启动
进一步了解
您的服务器已可以安装更多插件:
如需了解 Paper 选项的详细信息,请查阅官方文档。