中文

游戏服务器

如何使用 ViaVersion 接受其他 Minecraft 版本

借助 ViaVersion、ViaBackwards 和 ViaRewind,让更新或更旧的 Minecraft 客户端加入您的 Paper 服务器:安装、限制和故障排除。

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

本页内容

您的参数

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

默认情况下,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.service

Velocity 的现代转发会拒绝低于 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 插件,必要时限制接受的版本,以排除最旧的版本。

如需进一步了解,请查阅安装文档、配置文档以及该项目的插件选择工具。