ViaVersion 跨版本兼容插件

ViaVersion - 跨版本兼容插件
让高版本客户端连接低版本服务器

插件标识

| 项目 | 信息 |
| :--- | :--- |
| 当前版本 | v5.11.0（2026年7月15日） |
| 作者 | kennytv（维护者）、FormallyMyles（创始人）、creeper123123321、florianreuth |
| 许可证 | GPL-3.0-or-later |
| 首发时间 | 2016年 |
| 官方下载 | Hangar / Modrinth / SpigotMC / GitHub Releases |
| 开发构建 | Jenkins CI |
| 文档 | https://docs.viaversion.com |
| Discord | https://viaversion.com/discord |

概述

ViaVersion 是一个协议转换插件，核心功能是让高版本 Minecraft 客户端能够连接到低版本服务器。例如服务器运行在 1.20.4，安装了 ViaVersion 后，使用 1.21.x 甚至 26.x 客户端的玩家都能正常进入服务器。

它通过在服务端拦截和重写网络数据包，将新版协议"翻译"成旧版格式，对服务端逻辑、玩家数据、世界文件零修改。
核心优势
十年持续维护：自 2016 年起由 FormallyMyles 创立，至今活跃开发
支持版本跨度极大：覆盖 1.8.9 ~ 26.2（最新版），超过 60 个 Minecraft 版本
多平台支持：Paper / Spigot / Folia / Velocity / BungeeCord / Sponge / Fabric / Forge
开箱即用：默认配置即可工作，无需复杂设置
内置安全机制：数据包限制器（Packet Limiter）防止恶意客户端发包攻击
性能优异：v5.11.0 区块读写性能提升最高 90%
完全免费开源：GPL-3.0 协议，代码公开透明

支持的版本范围
客户端 → 服务器（ViaVersion 核心功能）

| 服务器版本 | 可连接的客户端版本 |
| :--- | :--- |
| 1.8.x | 1.8.x ~ 26.2 |
| 1.9.x ~ 1.20.4 | 对应版本 ~ 26.2 |
| 1.20.5 ~ 1.21.11 | 对应版本 ~ 26.2 |
| 1.21.11+ | 对应版本 ~ 26.2 |
完整支持列表：1.8.9, 1.9~1.12.2, 1.13~1.16.5, 1.17~1.21.11, 26.1.x, 26.2
支持的服务端平台

| 平台 | 说明 |
| :--- | :--- |
| Paper / Spigot / CraftBukkit | 最推荐，直接放 plugins 文件夹 |
| Folia | Paper 的多线程分支，完全支持 |
| Purpur / Pufferfish 等 Paper 分支 | 兼容 |
| Velocity | 代理端安装，统一管理后端 |
| BungeeCord / Waterfall | 代理端安装 |
| Sponge | 支持 |
| Fabric / Forge | 通过 ViaFabric / ViaForge 集成 |
Java 版本要求
官方构建：需要 Java 17+
Java 8 降级构建：可从 Jenkins CI 下载（不推荐长期使用）
未来计划：后续版本将要求 Java 21+

核心功能详解
协议翻译引擎

ViaVersion 的核心是一个高效的协议翻译层。当高版本客户端发送数据包到旧版服务器时：

高版本客户端 (26.2) --> 数据包拦截 --> 协议降级转换 --> 旧版服务器 (1.20.4)
旧版服务器 (1.20.4) --> 数据包拦截 --> 协议升级转换 --> 高版本客户端 (26.2)

转换内容包括：方块 ID、物品 NBT、实体数据、世界数据、聊天组件、音效、粒子效果等。
数据包限制器（Packet Limiter）

防止恶意客户端通过发送大量数据包导致服务器崩溃：
瞬时限制：默认每秒超过 800 个数据包即踢出
持续监控：默认每秒超过 150 个数据包持续 4/7 秒即踢出
数据包大小限制：可限制每秒传输的 KB 数
所有阈值和踢出消息均可自定义
全息图补丁（Hologram Patch）

为 1.9+ 客户端在旧版服务器上修正全息文字的高度显示问题。
自动组队（AutoTeam）

1.8 客户端在 1.9+ 服务器上会出现玩家碰撞问题，AutoTeam 自动将玩家分配到不同队伍来避免。
版本探测（Velocity 专属）

在代理端自动探测后端服务器的协议版本，智能路由玩家连接。
诊断与调试工具
/viaver dump：生成诊断报告（paste 链接），方便反馈 Bug
/viaver debug：控制台输出所有数据包，用于排查问题
/viaver pps：查看每个玩家的每秒数据包数
/viaver displayleaks：启用 Netty 内存泄漏检测

命令列表

所有命令默认需要 viaversion.admin 权限（通常 OP 自动拥有）。

| 命令 | 说明 |
| :--- | :--- |
| /viaver | 显示插件版本和可用命令 |
| /viaver list | 列出所有在线玩家及其客户端版本 |
| /viaver player [玩家] | 显示指定玩家（或所有玩家）的连接详细信息 |
| /viaver pps | 显示所有玩家的每秒数据包数 |
| /viaver autoteam | 切换自动组队功能（解决 1.8 碰撞问题） |
| /viaver debug | 切换调试模式（仅在排查问题时使用） |
| /viaver displayleaks | 切换 Netty 内存泄漏检测 |
| /viaver dontbugme | 切换登录时的更新通知 |
| /viaver dump | 生成诊断报告链接（反馈 Bug 时提供） |
| /viaver reload | 重新加载配置文件（部分选项需重启生效） |
| /viaver probe | 探测后端服务器版本（仅 Velocity） |

权限节点

| 权限 | 说明 | 默认 |
| :--- | :--- | :--- |
| viaversion.admin | 所有管理命令的权限 | OP |
| viaversion.command.<子命令> | 单个命令的精细权限控制（新版支持） | - |

安装步骤
单服务器（Paper / Spigot）
从 Hangar 或 SpigotMC 下载最新版 jar
将 jar 文件放入服务器 plugins/ 文件夹
启动服务器（不要用 /reload，会导致问题）
检查控制台日志确认 ViaVersion 成功加载
使用 /viaver list 验证功能正常
Velocity 代理端
在 Velocity 服务器上下载 ViaVersion jar 放入 plugins/
启动 Velocity，它会自动探测后端服务器版本
如需手动指定，编辑 config.yml 中的 velocity-servers 部分
后端服务器不需要再安装 ViaVersion
BungeeCord 代理端
将 ViaVersion jar 放入 BungeeCord 的 plugins/
启动后它会自动 ping 后端服务器获取版本信息
调整 bungee-ping-interval 控制探测频率
升级 ViaVersion
下载新版本 jar
完整重启服务器（不要 /reload）
检查启动日志确认新版本加载成功

与 Via 系列插件的关系

ViaVersion 是整套跨版本方案的核心，但单独使用只能让高版本客户端进低版本服务器。要完整覆盖所有方向，需要组合使用：

| 插件 | 功能 | 依赖 | 版本覆盖 |
| :--- | :--- | :--- | :--- |
| ViaVersion | 高版本客户端 → 低版本服务器 | 无 | 1.8.9 ~ 26.2 |
| ViaBackwards | 低版本客户端 → 高版本服务器 | ViaVersion | 1.9 ~ 最新 → 1.10 ~ 最新 |
| ViaRewind | 更老的 1.7/1.8 客户端 → 新服务器 | ViaVersion + ViaBackwards | 1.7.x/1.8.x → 1.8 ~ 1.16.2 |
| ViaFabric | 在 Fabric 端集成 ViaVersion | - | 同 ViaVersion |
| ViaFabricPlus | 增强版 Fabric 集成，支持更多特性 | - | 同 ViaVersion |
| ViaProxy | 独立代理程序，支持任意版本互连 | - | 极广（含 Classic/Alpha/Beta） |
| ViaAprilFools | 支持愚人节快照版本 | ViaVersion | 愚人节版本 |
典型组合方案

方案 A：服务器 1.20.4，希望支持 1.8 ~ 26.2 所有客户端
→ 安装 ViaVersion + ViaBackwards + ViaRewind

方案 B：服务器 1.21.11，希望支持 1.9 ~ 26.2
→ 安装 ViaVersion + ViaBackwards

方案 C：Velocity 代理网络，统一管理版本
→ 仅在 Velocity 上安装 ViaVersion（或 + ViaBackwards）
重要：所有 Via 插件必须保持相同的构建频道（都使用正式版或都使用 Dev 版），否则可能不兼容。

更新记录
v5.11.0（2026-07-15）
大量性能改进，区块读写性能最高提升 90%
新增 26.2 客户端支持
发送挥动手臂数据包，支持旁观者左键检测（26.1→26.2）
修复 26.1+ damage_resistant 物品哈希计算
修复 1.21.11→26.1 自定义维度环境光失效
修复 1.18.2→1.19 织布机无法工作
修复 1.17.1→1.18 Pigstep 唱片播放错误音效
新增 multi-reddust-color-fix 配置选项
提示：未来版本将要求 Java 21+
v5.10.0（2026-06-20）
新增 26.2 客户端支持
修复配置阶段数据包限制问题
修复 1.21.11→26.1 缺失的钟表和乐器键
修复 1.12→1.13 头颅旋转处理
v5.9.1（2026-05-13）
性能改进
v5.9.0（2026-04-20）
Bug 修复

如何阻止特定版本连接？
在 config.yml 中设置 block-versions，例如：

block-versions: ["<1.16", ">1.21.11"]
性能影响大吗？
v5.11.0 经过大量优化，区块处理性能提升 90%。正常情况下对 TPS 影响极小。如果担心性能，可以调整 packet-limiter 参数。

已知不兼容

| 插件 | 问题 | 建议 |
| :--- | :--- | :--- |
| ProtocolLib | /reload 时会导致服务器崩溃 | 使用完整重启，不要 /reload |
| SkinRestorer | 某些版本有兼容性问题 | 确保更新到最新版 |
| Citizens2 | 1.8 上可能有实体问题 | 避免使用 MONSTER_EGG durability 0 |
| Orebfuscator | 1.8 专用版本需要特殊构建 | 使用 专用构建 |
| BKCommonLib | 1.8.8 需要特殊构建 | 使用 专用构建 |

感谢 ViaVersion 团队十年来的持续维护，让 Minecraft 服务器告别了版本碎片化的困扰。