如何使用 ViaVersion 接受其他 Minecraft 版本
借助 ViaVersion、ViaBackwards 和 ViaRewind,让更新或更旧的 Minecraft 客户端加入您的 Paper 服务器:安装、限制和故障排除。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
默认情况下,Minecraft 服务器只接受与其版本相同的客户端。ViaVersion 及其附加插件会转换客户端与服务器之间的通信,让仍在使用其他版本的玩家也能连接。
本指南是在 Paper 上安装和更新插件的延续,沿用其中的 /opt/minecraft/server 文件夹、minecraft.service 服务和 mc-console 命令。
完成本指南后,您将了解:
- 根据要接受的版本应安装哪些插件
- 如何安装和更新这些插件,并校验其完整性
- 如何限制允许的版本以及如何回退
前提条件
- 一台带有
mc-console的 Paper 服务器,已按照 Paper 指南安装,并具备curl和jq - 使用具有
sudo权限的用户进行 SSH 访问 - 一个其他版本的 Minecraft 客户端,用于最后的测试
选择插件
要安装的插件取决于客户端版本相对于服务器的新旧:
| 要接受的玩家 | 所需插件 |
|---|---|
| 客户端新于服务器 | ViaVersion |
| 客户端旧于服务器,最低至 1.9 | ViaVersion + ViaBackwards |
| 1.7 或 1.8 客户端 | ViaVersion + ViaBackwards + ViaRewind |
了解限制
ViaVersion 转换的是协议,游戏内容仍以服务器为准。在开放其他版本之前,请考虑以下几点:
- 较新的内容:旧版客户端不认识新的方块、物品和生物,它们会以近似的形式呈现
- 世界高度:低于 1.17 的客户端看不到也无法触及
y=0以下和y=255以上的方块 - 物品栏:低于 1.17 的客户端在某些点击操作时可能出现错位
- 锻造台:在 1.20 或更高版本的服务器上,低于 1.19.4 的客户端无法使用锻造台,除非安装附加模块
- 声音:部分较新的声音在旧版客户端上没有对应项
- 反作弊:不同版本之间的行为差异可能引发误报。请测试您的配置
- 新版本:ViaVersion 通常在 Minecraft 更新几天后发布
- 基岩版:ViaVersion 仅适用于 Java 版。主机和移动设备请使用 Geyser 和 Floodgate
备份插件
ViaVersion 不会修改世界,但备份插件可以让您快速恢复到当前状态:
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server plugins
sudo ls -lh /opt/minecraft/backups安装插件
创建一个脚本,用于从 Hangar 下载插件,确认它们支持您的 Paper 版本,并校验其哈希值:
sudo nano /opt/minecraft/via-get.sh#!/bin/bash
# 从 Hangar 下载 Via 插件并校验其哈希值
set -euo pipefail
CIBLE="${1:?请指定目标文件夹}"
MC_VERSION="${2:?请指定服务器版本,例如 26.3}"
shift 2
if [ "$#" -eq 0 ]; then
echo "请至少指定一个插件,例如 ViaVersion。" >&2
exit 1
fi
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
mkdir -p "$CIBLE"
cd "$CIBLE"
for PLUGIN in "$@"; do
API="https://hangar.papermc.io/api/v1/projects/$PLUGIN/versions?limit=1&channel=Release&platform=PAPER"
VERSION=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c '.result[0]')
if ! echo "$VERSION" | jq -e --arg mc "$MC_VERSION" '.platformDependencies.PAPER | index($mc)' > /dev/null; then
echo "$PLUGIN 未声明支持 Paper $MC_VERSION" >&2
exit 1
fi
NOM=$(echo "$VERSION" | jq -r '.downloads.PAPER.fileInfo.name')
URL=$(echo "$VERSION" | jq -r '.downloads.PAPER.downloadUrl')
SHA256=$(echo "$VERSION" | jq -r '.downloads.PAPER.fileInfo.sha256Hash')
curl -fL -H "User-Agent: $UA" -o "$NOM.new" "$URL"
echo "$SHA256 $NOM.new" | sha256sum -c -
mv "$NOM.new" "$NOM"
echo "$NOM 已就绪。"
done替换 UA 这一行中的 your-domain.com,然后使脚本可执行:
sudo chmod 755 /opt/minecraft/via-get.sh安装您选择的插件。以下是最常见的情况,用于接纳较旧的客户端:
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/server/plugins 26.3 ViaVersion ViaBackwards如需支持 1.7 和 1.8 客户端,请在命令末尾加上 ViaRewind。如果只想接受比服务器更新的客户端,则只需指定 ViaVersion。
重启服务器,并等待出现 Done 这一行:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f验证结果
sudo mc-console plugins
sudo journalctl -u minecraft.service --since "10 minutes ago" --no-pager | grep 'ViaVersion detected server version'这些插件应出现在列表中,日志也应显示您的服务器版本。然后使用其他版本的客户端连接,并显示正在使用的版本:
sudo mc-console viaversion list您的玩家名应显示在客户端版本的对应位置。如果没有人在线,该命令会返回 No players found!。
最后试试玩家的常见操作:放置和破坏方块、打开箱子、使用您的命令和主要插件。
限制接受的版本
block-versions 设置可拒绝特定版本。此示例会阻止所有低于 1.20.5 的版本:
sudo -u minecraft sed -i 's/^block-versions: .*/block-versions: ["<1.20.5"]/' /opt/minecraft/server/plugins/ViaVersion/config.yml
sudo grep '^block-versions:' /opt/minecraft/server/plugins/ViaVersion/config.yml
sudo systemctl restart minecraft.service支持 < 和 > 前缀,也可以连续列出多个值:["<1.16", "1.16.4", ">1.17.1"]。被拒绝的玩家会看到 block-disconnect-msg 设置中的文本。
配合 Velocity 代理使用
如果您使用 Velocity,请将 ViaVersion 安装在代理或服务器其中之一,切勿两处都安装。
建议安装在 Paper 服务器上:ViaVersion 文档指出,在代理上进行转换时,反作弊插件可能无法正常工作。请为每台服务器重复安装,并更改文件夹:
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/lobby/plugins 26.3 ViaVersion ViaBackwards
sudo systemctl restart minecraft-lobby.serviceVelocity 的现代转发会拒绝低于 1.13 的客户端,因此在此配置下,ViaRewind 无法让这些客户端进入服务器。
更新
Paper 会在启动时通过 plugins/update 文件夹替换插件。请先备份,放入新版本,然后重启:
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server plugins
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/server/plugins/update 26.3 ViaVersion ViaBackwards
sudo systemctl restart minecraft.service请同时更新所有 Via 插件,因为它们的版本相互配套。Minecraft 发布新版本后,请等待这些插件提供支持。
回退
移除这些插件。世界不受影响,使用其他版本的玩家将再次被拒绝:
sudo systemctl stop minecraft.service
sudo rm -f /opt/minecraft/server/plugins/ViaVersion-*.jar /opt/minecraft/server/plugins/ViaBackwards-*.jar /opt/minecraft/server/plugins/ViaRewind-*.jar
sudo systemctl start minecraft.service配置文件夹会保留在 plugins 中,如果您不打算重新安装这些插件,可以将其删除。
故障排除
sudo journalctl -u minecraft.service -n 200 --no-pager | grep -iE 'via|error|exception'“Incompatible client! Please use …”
此版本未启用转换。请使用 sudo mc-console plugins 确认插件已正确加载,并将客户端版本与选择插件中的表格进行对照。旧版客户端需要 ViaBackwards。
“You are using an unsupported Minecraft version!”
此版本被 plugins/ViaVersion/config.yml 中的 block-versions 或 block-protocols 阻止。
“This server is only compatible with Minecraft 1.13 and above.”
此消息来自启用现代转发的 Velocity。该客户端无法通过此代理连接。
“ViaVersion does not have any compatible versions for this server version!”
ViaVersion 对您的服务器而言过旧。请更新它。如果该 Minecraft 版本刚刚发布,请等待兼容版本。
脚本提示“未声明支持 Paper”
Hangar 上发布的最新版本未列出您的 Paper 版本。请检查传给脚本的版本号以及项目页面。对于刚发布的 Minecraft 版本,请等待几天。
Via 插件无法加载
| 消息 | 原因 | 解决方法 |
|---|---|---|
Unknown/missing dependency plugins |
ViaBackwards 缺少 ViaVersion,或 ViaRewind 缺少 ViaBackwards | 安装提示的插件 |
Ambiguous plugin name |
plugins 中有同一插件的两个版本 |
只保留一个文件 |
UnsupportedClassVersionError |
Java 版本过旧 | 安装 Java 25 |
幽灵方块或物品栏错位
这些偏差通常来自相差较大的版本之间的转换。请更新 Via 插件,必要时限制接受的版本,以排除最旧的版本。