跳到主要内容

Resource Pack Manager 故障排查

本页面只覆盖目前在 ResourcePackManager 代码中已确认的行为。

针对 RSPM 出现的任何问题，最有用的第一步是：

/rspm status

它会打印版本、部署模式（独立 vs network-backend）、遮蔽后的网络密钥、Java 与基岩版资源包状态、当前激活的分发路径与 URL、解析得到的外部主机名 + 自动检测到的公网 IP、所有相关配置开关、一条代理部署提醒（网络代理 jar 就是同一个 ResourcePackManager.jar），以及 Floodgate / Geyser-Spigot 的检测情况。当该 jar 运行在代理上时也有同名命令，会打印代理侧的等价信息（后端列表、各后端的拉取结果、合并后的资源包状态）。

玩家收不到资源包​

请先检查这些：

  • 如果希望 ResourcePackManager 自动推送 URL，必须启用 autoHost
  • 合并后的资源包必须存在，并且至少有一条分发路径（自托管或远程）已成功
  • 玩家仅在加入服务器时，或在托管首次就绪时触发的首推广播中收到资源包

如有需要：

  1. 运行 /rspm status，查看 "Hosting" 部分。Active delivery 显示当前使用的是自托管、远程，还是都没启用。
  2. 如果显示 "active delivery: not yet ready" — 合并或上传仍在进行中。当玩家加入过早时，插件会在控制台大字提示，并会在分发就绪的瞬间自动把资源包发给玩家。
  3. 如果显示 "active delivery: none — hosting disabled or failed" — autoHost 已关闭，或自托管探测和远程上传都失败了。参阅下文 “自托管完整性检查失败” 与 “自动托管无法连接到远程服务器”。
  4. 运行 /rspm reload，在控制台观察上传 / 自托管探测的结果，再用一个测试玩家重新加入。

如果你通过自己的外部流水线自托管（autoHost: false），RSPM 不会替你推送自定义 URL。在该模式下你仍需自己负责服务端的资源包分发流程。

已安装 ItemsAdder，但最终资源包里没有它的内容​

这通常意味着 ItemsAdder 仍以某种方式阻止了 ResourcePackManager 读取或托管其输出。

请使用：

/rspm itemsadder configure

该命令目前会：

  • 启用 resource-pack.hosting.no-host.enabled
  • 禁用 protection_1、protection_2 和 protection_3
  • 将 resource-pack.zip.compress-json-files 设为 false
  • 运行 /iareload，再运行 /iazip
  • 大约 15 秒后重新加载 ResourcePackManager

如果该命令提示 ItemsAdder 已经在自托管资源包，请先手动禁用 ItemsAdder 的托管，再重新运行该命令。

合并后的资源包无效或上传失败​

ResourcePackManager 的自动托管集成会显式处理以下服务端错误类型：

  • 缺少必需文件
  • 文件过大
  • 文件格式无效
  • 会话缺失
  • 远程服务器不可用

遇到其中之一时：

  1. 运行 /rspm reload 重新构建资源包。
  2. 检查是否有某个源资源包格式错误、被加密或无法读取。
  3. 检查最终合并后的资源包根目录是否仍然包含有效的 pack.mcmeta 和 pack.png。

插件会跳过无法干净解压的资源包，并在控制台记录警告。

当远程 auto-host 报 SESSION_NOT_FOUND 错误时，RSPM 会清掉自己的会话 UUID，并在下一次心跳时重新初始化——无需人工干预。

一个插件的资源覆盖了另一个插件的资源​

这由 plugins/ResourcePackManager/config.yml 中的 priorityOrder 控制：

plugins/ResourcePackManager/config.yml

靠上的条目会胜过靠下的条目。

对于不可合并的文件，ResourcePackManager 会替换低优先级文件。对于可合并的 JSON 文件，则会合并内容。当前可合并的 JSON 类别有：

  • sounds.json
  • 语言文件
  • 位于 minecraft/models/item 的原版物品模型 JSON（非递归合并：跨资源包只合并 overrides 数组，文件其余部分遵循最高优先级取胜）
  • 图集（atlas）文件
  • 字体（font）文件
  • 位于 items/ 的 1.21.4+ 物品模型定义（格式感知合并，尊重 predicate 树结构）

pack.mcmeta 的合并方式也较特殊：取最高的 pack_format，supported_formats 范围会被扩展（支持整数、双整数数组以及 {min_inclusive, max_inclusive} 对象三种形式），overlay 条目会被合并，非标准顶层键会被保留。Overlay 条目还会针对 1.21.9+ 兼容性进行规范化：缺失时会自动补齐 min_format/max_format 字段。基础 atlas 源也会被合并进 overlay atlas 文件，防止 overlay 屏蔽基础条目。

如需查看最近一次合并发生了什么，请查阅：

plugins/ResourcePackManager/collision_log.txt

GUI 文本或基于字体的元素显示异常​

字体文件是 ResourcePackManager 会合并的 JSON 类别之一，但这并不保证两套不同的字体系统在 Minecraft 中能够良好共存。

如果某个基于字体的菜单或 HUD 显示异常：

  1. 修改 priorityOrder，让你希望胜出的资源包靠前。
  2. 运行 /rspm reload。
  3. 检查 collision_log.txt，确认冲突发生在你预期的位置。

资源包变更没有立即生效​

ResourcePackManager 对受支持的资源包来源具有看门狗机制。

它会等到某个发生变化的资源包持续 3 秒不再变化为止，然后在所有被监视资源包都稳定之后立即开始重新合并。

如果你正在主动重新生成另一插件的资源包，请在文件写入停止后再给它几秒时间。如果仍不确定，可在上游插件完成后运行 /rspm reload。

自托管完整性检查失败；回退到远程托管​

这条消息在 preferSelfHost: true（默认）且三项自托管完整性检查之一失败时属于正常行为：

  1. 第 1 层（启发式） — 解析得到的外部主机名是 RFC1918 / 回环地址 / 链路本地。请将 selfHostExternalHost 设为你真正的公网主机名，或确保插件能访问 api.ipify.org / checkip.amazonaws.com。
  2. 第 2 层（本地回环自探测） — 对 http://127.0.0.1:<port>/rspm.zip 发起的 HEAD 请求没有返回 200 + 非空主体。能捕获端口占用冲突或资源包文件缺失的情况。
  3. 第 3 层（外部可达性探测） — magmaguy.com 尝试拉取你公告的 URL 但访问不到。最常见原因：HTTP 端口没有在路由器/防火墙上放通。探测的 URL 与原因都会被记录。

修复方式（按推荐顺序）：在防火墙 + 路由器上放通 HTTP 端口；将 selfHostExternalHost 设为可路由的主机名；或将 preferSelfHost: false 完全跳过自托管。

当 magmaguy.com 探测本身都不可达（RSPM 连询问的对象都连不上）时，会保留自托管而不是判定失败——理由是回退路径同样需要 magmaguy.com，所以以“无法探测”为由拒绝自托管在逻辑上是自相矛盾的。

完整决策树请参阅 Self-hosting。

自动托管无法连接到远程服务器​

ResourcePackManager 内置的远程托管会与下面这个地址通信：

https://magmaguy.com/rsp/

如果该连接失败，插件会记录通信警告，并且在重新连接成功之前无法使用远程回退。

你的选项有：

  1. 修复服务器的出站 HTTPS 连接
  2. 等待远程服务恢复可达
  3. 禁用 autoHost，自行托管生成的 zip
  4. 打开 HTTP 端口并保持 preferSelfHost: true，让 RSPM 在完全不依赖 magmaguy.com 的情况下使用自托管（在这种场景下，也请把 selfHostExternalHost 设为你的公网主机名，这样就用不上第 3 层外部探测——遇到探测 IOException 时 RSPM 会保留自托管）

我想通过自己的 Web 服务器自托管合并后的资源包​

代码层面支持的做法是：

  1. 设置 autoHost: false。
  2. 如果希望 ResourcePackManager 额外把合并后的 zip 写入某个已存在的文件夹，则设置 resourcePackRerouting。
  3. 自己托管 ResourcePackManager_RSP.zip。

resourcePackRerouting 相对于 plugins 目录解析，且目标文件夹必须已存在。

如果你想使用 RSPM 内置的自托管 HTTP 服务器（这是另一件事——它与插件运行在同一个 JVM 中），请参阅 Self-hosting。

我需要查看本服务器在远程存储了哪些数据​

请使用：

/rspm data_compliance_request

如果存在活动的远程托管会话，ResourcePackManager 会把响应下载到：

plugins/ResourcePackManager/data_compliance

如果没有远程会话（例如你正在使用自托管），该命令会报告当前没有可请求的远程数据。

没有生成基岩版资源包​

bedrockConversionEnabled 默认值为 true，因此应当会自动运行。请先运行 /rspm status——Bedrock Pack 部分会告诉你资源包为何不在磁盘上：

  • "No Bedrock target detected" — 本地没有 Geyser-Spigot、没有 Floodgate，也不在网络模式下。转换被有意跳过。安装 Floodgate（用于代理部署）或 Geyser-Spigot（用于独立部署）后运行 /rspm reload。
  • "Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing" — 通常是第一次合并周期还没完成（启动后大约等 30 秒），或扫描器在合并后的资源包中没找到任何物品定义，或转换抛了异常。在控制台中搜索 [BedrockConverter] 警告或 Generic scanner: discovered 0 items definition files。

如果 Geyser 自动检测失败：

  1. 在 config.yml 中将 bedrockGeyserFolder 设为 Geyser 的数据目录路径（例如 Geyser-Spigot）。
  2. 该路径可以是绝对路径，也可以是相对于 plugins 目录的路径。

转换器会自动在 plugins/Geyser-Spigot/、任何 plugins/Geyser-*/ 变体，或者 Fabric/NeoForge 部署下的 config/Geyser-*/ 中查找 Geyser。

如需逐物品 / 逐骨骼的日志输出，将 bedrockConverterDebug: true 并重新加载。

基岩版玩家看到手持物品位置错误​

这是调优问题，而非转换 bug。打开 plugins/ResourcePackManager/bedrock_display_offsets.yml，调整相应的轴。第一人称与第三人称相互独立——调整一个不会影响另一个。基岩版客户端会在无需重启的情况下热重载可附着物 JSON，因此可以快速迭代。完整的旋钮列表及其作用请参阅 Bedrock conversion。

基岩版玩家身上看不到自定义盔甲贴图​

自定义盔甲在基岩版上的渲染方式是：将原版盔甲几何体与 Java 贴图组合为可见层。要让它工作，源插件的资源包必须在物品定义旁边提供 assets/<namespace>/equipment/<material>.json 装备文件。如果转换日志中显示了该物品，但游戏中没看到盔甲贴图，请确认该文件存在于合并后的资源包中。

代理：启动时报 "Floodgate key.pem missing"​

代理插件在代理主机上找不到 plugins/floodgate/key.pem，进入空转状态。RSPM 是从该文件派生网络身份的，没有它代理就无法与任何后端建立连接。修复方法：

  1. 在代理上安装 Floodgate。反正基岩版玩家要接入代理也需要它，所以不论是否使用 RSPM 都得安装。
  2. 确保代理上的 plugins/floodgate/key.pem 与每个后端上的同名文件逐字节一致。把一份规范的 key.pem 复制到所有组件（其他后端 + 代理），然后重启所有节点。Floodgate 本身就要求基岩版认证用同一个文件，所以如果基岩版玩家目前能跨节点正常工作，这一步其实已经完成了。

代理：经过几轮轮询后仍 "no merged pack"​

在代理上经历约 20 秒的空轮询循环后（4 轮 × 默认 5 秒间隔），RSPM 会一次性记录一个诊断横幅，列出它轮询过的每个后端、尝试访问的 HTTP URL，以及结果（200 / 304 / 404 / CONNECT_FAILED / 等）。横幅会解释最常见的修复方法：

  • 每个后端都返回 CONNECT_FAILED → 代理无法访问后端的 HTTP 端口。检查 velocity.toml / config.yml 中的地址是不是代理真正能访问到的（而不是诸如 Docker 内部名之类、从代理网络解析不到的地址），并确认代理与后端之间后端公告的 HTTP 端口是放通的。横幅会打印它尝试访问的确切 URL；在某个后端公告其端口之前，代理会回退到 mcPort + network-http-offset-v2，所以早期的 CONNECT_FAILED 也可能意味着那个回退端口暂时还不可达。
  • 每个后端都返回 NOT_FOUND_404 → 后端已就绪，但没有生成基岩版资源包。在每个后端运行 /rspm status；Bedrock Pack 诊断块会告诉你原因。

每个卡住期内横幅只触发一次，当至少有一个后端重新开始返回内容时，会记录一行 "NetworkSync: recovered"。详见 Proxy networks。

代理：第一次启动代理时基岩版玩家看不到任何模型​

Geyser 只在代理启动时注册其自定义物品表。如果代理在任何后端生成基岩版资源包之前就启动了，Geyser 就会带着空的映射表运行，并在整个会话期间保持空表。

修复方法：在后端日志中出现 Wrote merged Geyser mappings: N entries 之后，重启一次代理。RSPM 会在代理启动时预先部署上一次运行的映射，所以这种情况只会在全新安装时碰到一次——后续启动时 Geyser 扫描前总会有可用的映射就位。

后端：报 "Backend HTTP server failed to bind on port X"​

在网络模式下，后端会通过一个小型 HTTP 服务器暴露其基岩版输出。如果端口被占用或不可用，控制台会出现多行 [ERROR] 块。修复方法：

  • 在 config.yml 中把 selfHostPort 设为另一个正整数值。
  • 或者修改 networkHttpOffset-v2，把自动派生出的端口避开冲突（例如 RCON 占用了 mcPort + 1？改成 2 或 3）。你不需要同步更新代理：一旦后端成功绑定，它会自动把自己实际的 HTTP 端口公告给代理，因此代理自己的 network-http-offset-v2 仅作为公告之前的猜测才有意义。

在后端 HTTP 服务器无法启动期间，该后端的基岩版资源包无法通过直连方式送达代理。magmaguy.com 中继回退仍然可用（后端把文件推送到中继，代理从中继获取它们）。

清理过时的 v1 配置​

从 RSPM v1 升级的运维人员，config.yml 中可能仍有一个已废弃的 networkHttpOffset（不带 -v2）键。RSPM v2 故意不读取旧键——下次启动时会自动把 v2 默认值（1）写入配置。废弃的 v1 键会以无害遗留物的形式留在你的配置中，等你手动清理它。