Paper 服务器同时跑 mod 与插件混合部署避坑完整指南【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper刚搭 Paper 服务器的人最常踩的第一坑就是mod 与插件共存权限、家、聊天想用插件新维度、新机器又只能靠 mod。直接告诉你结论——同一个服务器进程里Bukkit 插件和 Forge/NeoForge mod 无法同时加载Paper 本身不内置 mod 加载器。可行的混合部署只有两条路要么在单机内二选一要么用双实例 代理把两套体系拼到一起。本文按先弄清差异 → 再做选型 → 再动手搭 → 上线后调优的顺序把每一步能落地的操作讲清楚并附上冲突排查对照表。一、先把误解摆正单机进程跑不了两套体系很多教程暗示给 Paper 打个补丁就能加载 mod。对照 Paper 仓库的实际结构看整个服务端是通过 Gradle 构建、把 patches 目录 里的补丁打在原版服务端源码上再用 paper-api 对外提供插件 API 的。它的插件加载、事件分发全部围绕 Bukkit API 设计没有任何 mod 容器Mod Container的挂载点。而 NeoForge/Forge 的 mod 靠 mod 加载器在类加载阶段改写游戏代码Fabric 则是字节码注入。两套体系在类加载层面就互斥mod 加载器会替换掉 Paper 依赖的原始类结构Bukkit 插件系统随之失效反过来也一样。所以市面上所谓的桥接真实形态只有两种代理层桥接Paper 和 mod 服务器各跑一个进程用代理在前台做路由本文第四部分详解mod 侧自实现某些 mod 自带 Bukkit 风格的 API 或命令看起来能跟插件交互本质是 mod 内部写的不改变两者不能同进程的事实。不存在官方插件桥接工具能让 Paper 直接吃 mod。遇到宣称Paper 原生支持 NeoForge 补丁的下载站内容先停下来核对。二、两套体系到底差在哪一张表看清选型前先建立正确预期。下面这张表按运维视角对比而不是参数罗列维度Paper插件体系NeoForge / Forgemod 体系工作方式通过 paper-api 的事件和 API 挂钩不改游戏类mod 加载器重写、注入游戏类可触及核心机制能力上限受限于游戏已有 API不能凭空加新实体、新维度可新增维度、实体、配方、渲染逻辑与对方的关系进程内不能再叠 mod 加载器进程内不能加载 Bukkit/Paper 插件版本更新成本换 jar、回归测试即可每个 mod 都要等作者适配并重新编译排障入口/timings对应 TimingsManager看事件耗时crash-report 堆栈 mod 列表做二分两个直接可用的推论管理型功能权限、聊天、经济、反作弊优先选插件升级成本远低于 mod玩法内容新维度、新机器、改核心机制只能放 mod这部分功能没有插件替代品。三、三条路线怎么选决策表 明确推荐你的实际情况推荐路线理由只要管理功能玩法用原版内容纯 Paper 插件零额外维护性能上限最高玩法核心完全依赖 mod如新维度生存NeoForge 单服放弃 Bukkit 插件硬凑插件生态只会引入协议冲突两边都要主世界用插件生态 副玩法用 mod 内容混合部署1 个 Paper 实例 1 个 mod 实例 前台代理下文步骤唯一能同时满足两边的架构第三条路线是本指南的重点。它的代价你要接受两套实例各自维护、各自升级玩家跨服时世界数据不互通。这是架构决定不是配置问题。四、动手搭建双实例 代理的完整步骤 步骤 1先做版本核对三个版本号必须一致客户端、前台代理、两个后端实例。以仓库 gradle.properties 中的mcVersion为准锁定 Paper 目标版本再让 NeoForge 实例和代理对齐同一个 Minecraft 版本。版本号差一个小数点典型症状就是登录循环、进服反复掉线。步骤 2准备 Paper 实例常规做法是直接下载官方发布好的 Paper jar 运行。如果需要用最新提交自己编译仓库给出的是标准流程需要 JDK 25git clone https://gitcode.com/GitHub_Trending/pa/Paper cd Paper ./gradlew applyPatches ./gradlew createPaperclipJar # 产物位于 paper-server/build/libs编译底层就是逐个套用 features 补丁清单 里的优化补丁打补丁脚本逻辑可参考 scripts/apatch.sh。plugins/目录里只放 Bukkit 插件不要放任何 mod 文件。步骤 3准备 mod 实例单独建一个 NeoForge 服务端目录mods/里放 mod。这个实例上不装任何 Bukkit 插件——即使放上去也不会被加载只会让排查时多出噪音。两个实例各配独立的端口和内存mod 侧内存通常要比 Paper 侧多给 20%~30%。步骤 4前台代理做路由用 BungeeCord或同类型代理监听对外端口把两个后端挂上去。最小配置长这样# BungeeCord.yml listeners: - query_port: 25565 motd: 混合部署测试服 servers: paper-main: address: 127.0.0.1:25566 mod-lands: address: 127.0.0.1:25567玩家登录默认落在paper-main跨服切换由服务端命令触发。上线前先用测试客户端把登录 → 跨服 → 回切 → 重连整条链路走一遍。步骤 5划定世界与数据边界最容易翻车的一步两个实例不要共用同一个世界目录。世界文件由各自服务端写入一旦交叉读写chunk 数据互相污染后很难恢复。需要看起来像同一个世界时用各自独立的世界 相近的地形种子来近似而不是硬共目录。五、常见坑冲突排查对照表 症状最先怀疑快速验证处置登录循环 / 进服秒掉客户端、代理、后端三者版本不一致对三处版本号看代理日志统一版本后重试跨服后实体/坐标异常两边世界版本不同实体追踪基线漂移跨服后立刻/tp回原点保持每侧世界只被本侧服务端读写随机断连、只在高峰出现改协议/封包的插件与 mod 自定义数据包互踩临时摘除封包类插件观察只保留一侧修改数据包世界加载报 datafixer 错误世界曾被其他版本服务端写入备份世界查日志中 datafixer 段用单一版本完整跑一遍迁移mod 侧 TPS 明显低于 Paper 侧mod 在主线程重活mod 端 profiler 抓一次精简 mod 列表逐个二分补充一个容易忽视的点玩家身份。两侧如果一个开 online-mode、一个不开代理会报鉴权错误跨服必挂。两侧 online-mode 必须一致代理配置也要对应。六、上线后的调优JVM 与监控清单 ⚙️JVM 参数参考G1 是当前默认选择。以 16G 内存的 Paper 实例为例mod 侧按自己的内存上限等比调整java -Xms16G -Xmx16G \ -XX:UseG1GC -XX:MaxGCPauseMillis100 \ -XX:ParallelRefProcEnabled -XX:AlwaysPreTouch \ -jar paper-*.jar要点-Xms与-Xmx设成一致避免运行期扩缩堆引起停顿mod 实例如果卡顿集中在 mod 更新世界时优先加内存而不是改 GC 参数。日常监控Paper 侧跑/timings重点看Entity tick / Chunk耗时对应仓库里 Moonrise 优化补丁 所覆盖的区块系统热点mod 侧用服务端自带 profiler两周抓一次存档即可看门狗线程Watchdog触发过就立即回查两侧日志不要等玩家反馈。两个补丁值得知道Paper 补丁里有两个对混合环境特别实用超大 chunk 保存补丁区块数据超过区域文件格式 1MB 上限时把溢出部分写到独立文件而不是静默回滚。它的说明里明确提到换 jar 后数据仍可恢复对你这种偶尔要换服务端构建的部署很关键regionfile 头部重算补丁区块文件头损坏时尝试重算恢复而不是让整片区块报废。七、拿到手就能做的行动清单今天把现有插件和 mod 列表过一遍逐条标注哪个功能必须靠它实现删掉能用插件替代的 mod本周按第四部分搭好双实例 代理测试环境完整走一遍登录/跨服/重连流程上线前备份两侧世界确认两侧 online-mode 一致JVM 参数套用后跑 2 小时压力多客户端并发进服上线后每周各跑一次/timings和 mod 侧 profiler把 TPS、GC 停顿记进表格长期规则每新增一个 mod先单独跑 48 小时再进正式服出问题用减半 mod 数二分定位。最后一句直白的建议如果你盘完列表发现 mod 只有两三个且都是内容类 mod认真考虑直接上 NeoForge 单服——双实例的维护成本往往比共存本身更贵。【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Paper 服务器同时跑 mod 与插件：混合部署避坑完整指南
Paper 服务器同时跑 mod 与插件混合部署避坑完整指南【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper刚搭 Paper 服务器的人最常踩的第一坑就是mod 与插件共存权限、家、聊天想用插件新维度、新机器又只能靠 mod。直接告诉你结论——同一个服务器进程里Bukkit 插件和 Forge/NeoForge mod 无法同时加载Paper 本身不内置 mod 加载器。可行的混合部署只有两条路要么在单机内二选一要么用双实例 代理把两套体系拼到一起。本文按先弄清差异 → 再做选型 → 再动手搭 → 上线后调优的顺序把每一步能落地的操作讲清楚并附上冲突排查对照表。一、先把误解摆正单机进程跑不了两套体系很多教程暗示给 Paper 打个补丁就能加载 mod。对照 Paper 仓库的实际结构看整个服务端是通过 Gradle 构建、把 patches 目录 里的补丁打在原版服务端源码上再用 paper-api 对外提供插件 API 的。它的插件加载、事件分发全部围绕 Bukkit API 设计没有任何 mod 容器Mod Container的挂载点。而 NeoForge/Forge 的 mod 靠 mod 加载器在类加载阶段改写游戏代码Fabric 则是字节码注入。两套体系在类加载层面就互斥mod 加载器会替换掉 Paper 依赖的原始类结构Bukkit 插件系统随之失效反过来也一样。所以市面上所谓的桥接真实形态只有两种代理层桥接Paper 和 mod 服务器各跑一个进程用代理在前台做路由本文第四部分详解mod 侧自实现某些 mod 自带 Bukkit 风格的 API 或命令看起来能跟插件交互本质是 mod 内部写的不改变两者不能同进程的事实。不存在官方插件桥接工具能让 Paper 直接吃 mod。遇到宣称Paper 原生支持 NeoForge 补丁的下载站内容先停下来核对。二、两套体系到底差在哪一张表看清选型前先建立正确预期。下面这张表按运维视角对比而不是参数罗列维度Paper插件体系NeoForge / Forgemod 体系工作方式通过 paper-api 的事件和 API 挂钩不改游戏类mod 加载器重写、注入游戏类可触及核心机制能力上限受限于游戏已有 API不能凭空加新实体、新维度可新增维度、实体、配方、渲染逻辑与对方的关系进程内不能再叠 mod 加载器进程内不能加载 Bukkit/Paper 插件版本更新成本换 jar、回归测试即可每个 mod 都要等作者适配并重新编译排障入口/timings对应 TimingsManager看事件耗时crash-report 堆栈 mod 列表做二分两个直接可用的推论管理型功能权限、聊天、经济、反作弊优先选插件升级成本远低于 mod玩法内容新维度、新机器、改核心机制只能放 mod这部分功能没有插件替代品。三、三条路线怎么选决策表 明确推荐你的实际情况推荐路线理由只要管理功能玩法用原版内容纯 Paper 插件零额外维护性能上限最高玩法核心完全依赖 mod如新维度生存NeoForge 单服放弃 Bukkit 插件硬凑插件生态只会引入协议冲突两边都要主世界用插件生态 副玩法用 mod 内容混合部署1 个 Paper 实例 1 个 mod 实例 前台代理下文步骤唯一能同时满足两边的架构第三条路线是本指南的重点。它的代价你要接受两套实例各自维护、各自升级玩家跨服时世界数据不互通。这是架构决定不是配置问题。四、动手搭建双实例 代理的完整步骤 步骤 1先做版本核对三个版本号必须一致客户端、前台代理、两个后端实例。以仓库 gradle.properties 中的mcVersion为准锁定 Paper 目标版本再让 NeoForge 实例和代理对齐同一个 Minecraft 版本。版本号差一个小数点典型症状就是登录循环、进服反复掉线。步骤 2准备 Paper 实例常规做法是直接下载官方发布好的 Paper jar 运行。如果需要用最新提交自己编译仓库给出的是标准流程需要 JDK 25git clone https://gitcode.com/GitHub_Trending/pa/Paper cd Paper ./gradlew applyPatches ./gradlew createPaperclipJar # 产物位于 paper-server/build/libs编译底层就是逐个套用 features 补丁清单 里的优化补丁打补丁脚本逻辑可参考 scripts/apatch.sh。plugins/目录里只放 Bukkit 插件不要放任何 mod 文件。步骤 3准备 mod 实例单独建一个 NeoForge 服务端目录mods/里放 mod。这个实例上不装任何 Bukkit 插件——即使放上去也不会被加载只会让排查时多出噪音。两个实例各配独立的端口和内存mod 侧内存通常要比 Paper 侧多给 20%~30%。步骤 4前台代理做路由用 BungeeCord或同类型代理监听对外端口把两个后端挂上去。最小配置长这样# BungeeCord.yml listeners: - query_port: 25565 motd: 混合部署测试服 servers: paper-main: address: 127.0.0.1:25566 mod-lands: address: 127.0.0.1:25567玩家登录默认落在paper-main跨服切换由服务端命令触发。上线前先用测试客户端把登录 → 跨服 → 回切 → 重连整条链路走一遍。步骤 5划定世界与数据边界最容易翻车的一步两个实例不要共用同一个世界目录。世界文件由各自服务端写入一旦交叉读写chunk 数据互相污染后很难恢复。需要看起来像同一个世界时用各自独立的世界 相近的地形种子来近似而不是硬共目录。五、常见坑冲突排查对照表 症状最先怀疑快速验证处置登录循环 / 进服秒掉客户端、代理、后端三者版本不一致对三处版本号看代理日志统一版本后重试跨服后实体/坐标异常两边世界版本不同实体追踪基线漂移跨服后立刻/tp回原点保持每侧世界只被本侧服务端读写随机断连、只在高峰出现改协议/封包的插件与 mod 自定义数据包互踩临时摘除封包类插件观察只保留一侧修改数据包世界加载报 datafixer 错误世界曾被其他版本服务端写入备份世界查日志中 datafixer 段用单一版本完整跑一遍迁移mod 侧 TPS 明显低于 Paper 侧mod 在主线程重活mod 端 profiler 抓一次精简 mod 列表逐个二分补充一个容易忽视的点玩家身份。两侧如果一个开 online-mode、一个不开代理会报鉴权错误跨服必挂。两侧 online-mode 必须一致代理配置也要对应。六、上线后的调优JVM 与监控清单 ⚙️JVM 参数参考G1 是当前默认选择。以 16G 内存的 Paper 实例为例mod 侧按自己的内存上限等比调整java -Xms16G -Xmx16G \ -XX:UseG1GC -XX:MaxGCPauseMillis100 \ -XX:ParallelRefProcEnabled -XX:AlwaysPreTouch \ -jar paper-*.jar要点-Xms与-Xmx设成一致避免运行期扩缩堆引起停顿mod 实例如果卡顿集中在 mod 更新世界时优先加内存而不是改 GC 参数。日常监控Paper 侧跑/timings重点看Entity tick / Chunk耗时对应仓库里 Moonrise 优化补丁 所覆盖的区块系统热点mod 侧用服务端自带 profiler两周抓一次存档即可看门狗线程Watchdog触发过就立即回查两侧日志不要等玩家反馈。两个补丁值得知道Paper 补丁里有两个对混合环境特别实用超大 chunk 保存补丁区块数据超过区域文件格式 1MB 上限时把溢出部分写到独立文件而不是静默回滚。它的说明里明确提到换 jar 后数据仍可恢复对你这种偶尔要换服务端构建的部署很关键regionfile 头部重算补丁区块文件头损坏时尝试重算恢复而不是让整片区块报废。七、拿到手就能做的行动清单今天把现有插件和 mod 列表过一遍逐条标注哪个功能必须靠它实现删掉能用插件替代的 mod本周按第四部分搭好双实例 代理测试环境完整走一遍登录/跨服/重连流程上线前备份两侧世界确认两侧 online-mode 一致JVM 参数套用后跑 2 小时压力多客户端并发进服上线后每周各跑一次/timings和 mod 侧 profiler把 TPS、GC 停顿记进表格长期规则每新增一个 mod先单独跑 48 小时再进正式服出问题用减半 mod 数二分定位。最后一句直白的建议如果你盘完列表发现 mod 只有两三个且都是内容类 mod认真考虑直接上 NeoForge 单服——双实例的维护成本往往比共存本身更贵。【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考