中文

游戏服务器

如何在 Minecraft Paper 服务器上安装和更新插件

将您的 Minecraft 原版服务器迁移到 Paper 而不丢失世界,然后在 VPS 或专用 Linux 服务器上安装和更新插件。

阅读约 9 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

官方 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.3

server.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=180

SuccessExitStatus 可避免服务在正常停止后显示为失败,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 cat
终端
sudo 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 -f
终端
sudo 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/server

mc-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 选项的详细信息,请查阅官方文档。