企业官网建设流程全解析

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 补丁"的下载站内容，先停下来核对。

二、两套体系到底差在哪：一张表看清

选型前先建立正确预期。下面这张表按"运维视角"对比，而不是参数罗列：

两个直接可用的推论：

1. 管理型功能（权限、聊天、经济、反作弊）优先选插件，升级成本远低于 mod；
2. 玩法内容（新维度、新机器、改核心机制）只能放 mod，这部分功能没有插件替代品。

三、三条路线怎么选：决策表 + 明确推荐

第三条路线是本指南的重点。它的代价你要接受：两套实例各自维护、各自升级，玩家跨服时世界数据不互通。这是架构决定，不是配置问题。

四、动手搭建：双实例 + 代理的完整步骤 🧭

步骤 1：先做版本核对

三个版本号必须一致：客户端、前台代理、两个后端实例。以仓库 gradle.properties 中的mcVersion为准锁定 Paper 目标版本，再让 NeoForge 实例和代理对齐同一个 Minecraft 版本。版本号差一个小数点，典型症状就是"登录循环、进服反复掉线"。

步骤 2：准备 Paper 实例

常规做法是直接下载官方发布好的 Paper jar 运行。如果需要用最新提交自己编译，仓库给出的是标准流程（需要 JDK 25）：

git 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 数据互相污染后很难恢复。需要"看起来像同一个世界"时，用各自独立的世界 + 相近的地形种子来近似，而不是硬共目录。

五、常见坑：冲突排查对照表 🔍

补充一个容易忽视的点：玩家身份。两侧如果一个开 online-mode、一个不开，代理会报鉴权错误，跨服必挂。两侧 online-mode 必须一致，代理配置也要对应。

六、上线后的调优：JVM 与监控清单 ⚙️

JVM 参数参考

G1 是当前默认选择。以 16G 内存的 Paper 实例为例（mod 侧按自己的内存上限等比调整）：

java -Xms16G -Xmx16G \ -XX:+UseG1GC -XX:MaxGCPauseMillis=100 \ -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