Paper 服务器 mod 插件共存怎么做：4 步跑通混合部署的实操指南
【免费下载链接】PaperThe most widely used, high performance Minecraft server that aims to fix gameplay and mechanics inconsistencies项目地址: https://gitcode.com/GitHub_Trending/pa/Paper
朋友开的生存服最近有诉求：反作弊和权限插件一个都不能少，可玩家又点名要那几个新玩法 mod。在纯 Paper 服务器上，插件和 mod 走的不是同一套加载体系，mod 与插件共存就是你要先解决的混合部署问题。下面先用 3 个问题帮你选路线，再给 4 步部署流程，最后讲调优和排障。
5 分钟判断：你到底需不需要混跑
本节结论：能用插件解决的，就别引入 mod。
按顺序问自己三个问题：
- 你要的功能在“插件地盘”里吗？权限、反作弊、基础指令、经济系统，这些用插件覆盖成本最低，加载开销也最小。
- 这个玩法有没有插件版实现？新维度、新方块、自定义生物行为，通常只有 mod 做得到。到这一步，才需要换到 PaperForge 构建（PaperMC 团队维护的、把 Paper 与 Forge/NeoForge 生态结合起来的版本）。
- 你的服务器扛得住性能成本吗？mod 每 tick 都会增加额外工作，在线人数多的服务器 TPS（服务器每秒处理的刻数）会掉；人少、低负载的玩法服可以考虑。
第 2 问答案是“是”，就按本文混跑；答案是“否”，停在纯插件侧即可，后面的调优和排障章节照样能用。
原理速览：插件和 mod 分别怎么进游戏的
本节结论：三句话看懂两套体系为什么难混在一起。
插件基于 Bukkit 事件模型：它监听服务器抛出的事件（玩家登录、方块被破坏），不改动游戏自身代码。mod 走字节码改造：Forge/NeoForge 直接修改游戏类，能实现插件做不到的核心玩法，代价是额外的生命周期开销。Paper 本身靠“补丁”体系运转——本仓库里游戏源码就是靠paper-server/patches/下的补丁文件持续改造的，paper-server/patches/features/里一共有 34 个功能补丁，其中就包括世界存储文件头修复和实体激活距离 2.0；PaperForge 就是用同样的补丁机制把 mod 侧接进来的，构建细节以官方文档为准。
部署走流程：从 clone 到启动的 4 步
本节结论：按顺序走完 4 步，你手里会有一个能开服的混合环境。每步一行命令，附一句目的。
第 1 步｜环境准备：JDK 25 起步，先克隆源码
git clone https://gitcode.com/GitHub_Trending/pa/Paper目的：拿到完整源码和补丁集。注意环境需要 JDK 25（java -version查一下版本），构建脚本在非 git 目录会直接拒绝执行。
第 2 步｜应用补丁并构建：一条命令完成
./gradlew applyPatches createPaperclipJar目的：先把paper-server/patches/下的全部补丁打到游戏源码上，再打包出可运行的服务器 jar，成品在paper-server/build/libs目录。
第 3 步｜白名单怎么配：目录内容就是白名单
mkdir -p plugins mods目的：只放精选后的 mod（起步建议个位数）和必需插件，白名单就是目录里有什么，移除某个 jar 即等于移出白名单。想先压负载，可以在server.properties里写simulation-distance=12。
第 4 步｜启动验证：/tps 是唯一标准
java -Xms4G -Xmx4G -jar paper-server/build/libs/paper*.jar nogui目的：启动后在游戏里执行/tps，几名测试玩家在线期间能稳在 20.0，混合环境就算就绪。
⚠️ 上面这条链路产出的 jar 是 Paper 基座，原生只跑插件。要真正跑 mod，需要换 PaperForge 项目构建出的 jar——它的构建流程和这里一致（克隆 → 打补丁 → 打包），具体操作以 PaperForge 官方文档为准。
调优：4 个动作把 TPS 稳住
动作一：把 mod 清单砍到最核心
→ 预期效果：每 tick 的回调变少，TPS 曲线更平。把 mod 逐个关掉做对比测试，只保留影响核心玩法的那几个。
动作二：先降模拟距离
→ 预期效果：参与运算的区块和实体变少，效果立竿见影。server.properties里simulation-distance=12起步，再按情况微调。
动作三：堆内存和 GC 只加两行
→ 预期效果：长暂停变少，TPS 尖刺减少。启动命令里带上即可：
java -Xms8G -Xmx8G -XX:+UseG1GC -jar paperclip.jar nogui动作四：用 /timings 定位重负载
→ 预期效果：卡顿真凶被抓住，而不是靠猜。跑一次/timings，在报告里找 CPU 占用最高的插件，再决定降频还是改异步。Timings 的实现就内置在本仓库，参考paper-api/src/main/java/co/aikar/timings/。
排障：5 个“症状现场”怎么处理
现场一：生物模型错乱
原因一句话：mod 与插件对同一实体都写过数据，版本没对齐导致错帧。处置：先让客户端 mod 版本和服务端严格一致，再逐个关掉插件二分定位。
现场二：进世界即断连
原因一句话：插件和 mod 都注册了自定义数据包，客户端协议版本对不上服务端。处置：先确认客户端与服务端版本一致，再临时卸掉跨版本兼容类插件排除嫌疑。
其余三个高频现场，直接查表：
| 症状现场 | 最可能原因 | 第一步处置 |
|---|---|---|
| 区块生成异常、加载错乱 | mod 世界生成与插件世界隔离逻辑打架 | 把 mod 主世界和插件重世界拆成独立世界文件 |
| TPS 只在特定时间掉 | 某个插件在同步做重活 | 跑一次 /timings，找 CPU 第一名的插件 |
| 日志满屏红字、定位不到元凶 | mod 与插件钩子互相覆盖同一事件 | 只留一个插件，单独开 mod 复测，再对调 |
上线前自检：5 项确认再开门
- 玩家在线状态下 /tps 能连续 10 分钟保持 20.0
- 上线前已备份世界目录和服务器目录（mod 是数据损坏的高发源）
- mod 清单和版本号有记录，方便日后逐个二分排查
- 启动命令的堆内存与机器实际内存匹配，已启用 G1GC
- 你能在 1 分钟内从日志里认出红色堆栈是哪一类报错
后续如果在线人数涨上来，先看卡顿属于“区块生成型”还是“实体型”，再决定是调加载参数还是引入代理集群分流，具体配置键以官方文档为准。下期预告：《TPS 排查实录：用 /timings 把服务器从 12 拉回 20》。
【免费下载链接】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），仅供参考
