Resource Pack Manager 疑難排解

此頁面僅涵蓋目前 ResourcePackManager 程式碼中已確認的行為。

對任何 RSPM 問題而言，最有用的第一步是：

/rspm status

它會印出版本、佈署模式（獨立 vs 網路後端）、一段簡短且不含機密的網路金鑰指紋以及該金鑰的來源、Java + Bedrock 資源包狀態、目前啟用的交付路徑及其 URL、解析後的外部主機 + 自動偵測的公開 IP、所有相關的設定旗標、一則代理佈署提醒（網路代理 jar 就是同一個 ResourcePackManager.jar），以及 Floodgate / Geyser-Spigot 的偵測結果。當該 jar 在代理上執行時也有同樣的指令，可印出代理端的對應資訊（後端清單、各後端的擷取結果、合併後的資源包狀態）。

主控台的安靜是刻意設計的

RSPM 在每次重新初始化交付路徑時只會印出一行——也就是結果：

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip
[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

其餘的一切——每個被暫存的資源包、每個被合併的叢集、每次穩定性檢查、每次自我託管探測及其結果——預設都會被抑制。RSPM 自己就能恢復的狀況不會被回報為警告。 若某次自我託管探測失敗、RSPM 靜默切換到遠端託管，那是成功而非故障，主控台對此不會有任何訊息。

因此：沒有警告並不代表什麼都沒發生，而結果行的出現就代表玩家確實拿得到資源包。在回報託管或合併的錯誤之前，請先打開敘述式輸出：

/rspm verbose on

然後執行 /rspm reload。該指令會替你把 verboseLogging: true 寫入 plugins/ResourcePackManager/config.yml，且此設定會在重啟後保留，所以完成後請執行 /rspm verbose off。手動編輯該設定鍵的效果完全相同。Bedrock 轉換器有另一個獨立的開關 bedrockConverterDebug，它只能透過設定檔調整。

你確實可能看到的警告都是真正的故障：對特定玩家反覆的資源包交付失敗、用戶端回報 INVALID_URL、HTTP 連接埠無法綁定、兩條交付路徑皆失敗，或代理已輪詢數個週期卻沒有任何後端產出內容。

玩家沒有收到資源包

請先檢查以下事項：

• 若你希望正常的自動交付運作，必須啟用 autoHost（selfHostForce 則是明確的測試用覆寫）
• 合併後的資源包必須存在，且至少一條交付路徑（自我託管或遠端）必須已成功
• 玩家只會在加入時，或在託管首次就緒當下發出的首次上傳廣播時才會收到資源包
• Java 交付會刻意略過 Floodgate 玩家，因為他們的 Bedrock 資源包工作階段由 Geyser 掌管

如有需要：

1. 執行 /rspm status 並查看「Hosting」區段。Active delivery 會顯示目前正在使用自我託管、遠端或兩者皆未使用。
2. 若顯示「active delivery: not yet ready」——混合或上傳仍在進行中。當玩家過早加入時，外掛會在主控台以大字橫幅顯示警示，並在交付就緒的當下自動發送資源包。
3. 若顯示「active delivery: none — hosting disabled or failed」——表示 autoHost 已停用，或自我託管探測與遠端上傳皆失敗。請參閱下方的「自我託管健全性檢查失敗」與「自動託管無法連線到遠端伺服器」。
4. 設定 verboseLogging: true、執行 /rspm reload，觀察主控台上的上傳 / 自我託管探測結果，然後用測試玩家重新加入。（若未開啟該旗標，探測步驟不會被印出——只會印出最終的「Resource pack is live via ...」結果行。）

加入時的資源包提示會延遲約一秒。若某個 Java 用戶端回報 FAILED_DOWNLOAD 或 DISCARDED，RSPM 會針對該玩家工作階段自動重試，最多三次。它不會針對玩家主動拒絕或 INVALID_URL 重試；重試次數耗盡與無效 URL 會被記錄為真正的故障。

若你是透過自己的外部管線進行自我託管（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。

若某個已啟用的資源包無法解壓或暫存，當次混合會中止，主控台會指出是哪個資源包失敗。請修復該資源包、移除手動加入的 ZIP，或在其自動整合設定中將 isEnabled: false 之後再重新載入。

單一損壞的資源包不再永久卡住一切

無法暫存的資源包在每次重試時都會以相同方式失敗，因此放著不管會讓交付永久卡死——合併永遠無法完成，同一個錯誤無止盡地重複。在同一個檔案連續失敗三次之後，RSPM 會把該資源包從合併中剔除，好讓其餘資源包能順利發佈，並大聲地說明一次：

[ResourcePackManager] Resource pack X.zip failed to stage 3 times in a row and has been excluded
from the merge so the remaining packs can be delivered. The merged pack is now INCOMPLETE ...

請照字面理解這段訊息：玩家現在拿到的資源包缺少該外掛的內容。常見原因是損毀或寫入不完整的 zip。

這個排除狀態會自行解除。失敗紀錄是以檔案的大小與修改時間為鍵，因此修復或替換該檔案就會自動解除隔離，該資源包會重新加入下一次合併——不需要指令、也不需要重啟。/rspm reload 同樣會把所有隔離紀錄從頭重置。未達三次的失敗計數會在任何一次成功的混合之後被清除，因此在長時間運行中零星、互不相關的短暫故障不會累積成排除。

當遠端自動託管回傳 SESSION_NOT_FOUND 錯誤時，RSPM 會清除其工作階段 UUID，並在下一次 keep-alive tick 重新初始化——無需手動介入。

某個外掛的資源覆蓋了另一個外掛的資源

這由下列檔案中的 priorityOrder 控制：

plugins/ResourcePackManager/config.yml

較高的條目會勝過較低的條目。

對於不可合併的檔案，ResourcePackManager 會取代較低優先級的檔案；對於可合併的 JSON 檔案，則會合併內容。目前可合併的 JSON 類別為：

• sounds.json
• 語言檔
• minecraft/models/item 下的原版物品模型 JSON（非遞迴合併：只有 overrides 陣列會跨資源包合併，檔案其餘部分則遵循「最高優先級勝出」）
• atlas 檔
• font 檔
• items/ 下的 1.21.4+ 物品模型定義（格式感知合併，會尊重 predicate-tree 結構）

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。

/rspm status 顯示遠端託管，但我預期是自我託管

當 preferSelfHost: true（預設）且三項自我託管健全性檢查之一失敗時，此為正常行為。RSPM 不會為此發出警告——回退到遠端託管是一個成功的結果，因此失敗的檢查只會以明確標註「This is OK.」的細節等級記錄，除非 verboseLogging: true，否則不會顯示。預設情況下你只會看到 Resource pack is live via automatic hosting — ... 這一行。

請執行 /rspm verbose on（或設定 verboseLogging: true）並執行 /rspm reload，即可看到是三層中的哪一層失敗：

1. 第 1 層（heuristic） — 解析後的外部主機為 RFC1918 / loopback / link-local。請將 selfHostExternalHost 設為你的實際公開主機名稱，或確保外掛能連到 api.ipify.org / checkip.amazonaws.com。
2. 第 2 層（本機 self-probe） — 對 http://127.0.0.1:<port>/rspm.zip 發出的 HEAD 請求未回傳含非空主體的 200。可揪出連接埠綁定衝突或資源包檔案缺失。
3. 第 3 層（外部可達性探測） — magmaguy.com 試圖擷取你公告的 URL 卻連不上。最常見原因：HTTP 連接埠未在路由器 / 防火牆上轉送。探測 URL 與原因代碼（PRIVATE_HOST_REJECTED、CONNECT_TIMEOUT、ECONNREFUSED、RATE_LIMITED 等）會在 verboseLogging 下印出。

修復方式（依優先順序）：在防火牆與路由器上開放 HTTP 連接埠、將 selfHostExternalHost 設為可路由的主機名稱，或將 preferSelfHost: false 完全略過自我託管。

當 magmaguy.com 探測本身無法連線時（RSPM 連請求都送不出去），會保留自我託管而非標記失敗——理由是回退路徑同樣需要 magmaguy.com，若以無法探測為由拒絕承諾自我託管會自相矛盾。

完整的決策樹請參閱自我託管。

自動託管無法連線到遠端伺服器

ResourcePackManager 的內建遠端託管會與以下位址通訊：

https://magmaguy.com/rsp/

若連線失敗，外掛會記錄通訊警告，且在重新連線成功前無法使用遠端回退。

你的選擇有：

1. 修正伺服器對外 HTTPS 連線
2. 等待遠端服務恢復可用
3. 停用 autoHost，改由自己託管產生的 zip
4. 開放你的 HTTP 連接埠、將 selfHostExternalHost 設為你的公開主機名稱，並保持 preferSelfHost: true。明確的主機名稱會略過公開 IP 自動偵測，但 RSPM 仍會嘗試第 3 層探測。若探測服務本身無法連線，RSPM 會保留自我託管，而不會把該通訊失敗當成「你的 URL 不可達」的證據。

我想透過自己的網頁伺服器自我託管合併後的資源包

由程式碼支援的設定方式為：

1. 設定 autoHost: false。
2. 若希望 ResourcePackManager 將額外副本寫入已存在的資料夾，請設定 resourcePackRerouting。
3. 自行託管 ResourcePackManager_RSP.zip。

resourcePackRerouting 路徑會以 plugins 目錄為基準解析，目標資料夾必須已存在。

若你想改為使用 RSPM 內建的自我託管 HTTP 伺服器（這是不同的東西——與外掛位於同一 JVM 中），請參閱自我託管。

我需要檢視為此伺服器儲存了哪些遠端資料

使用：

/rspm data_compliance_request

若有作用中的遠端託管工作階段，ResourcePackManager 會將回應下載至：

plugins/ResourcePackManager/data_compliance/data.zip

RSPM 也會在同一個 data_compliance 資料夾中寫入 ReadMe.md。

若沒有遠端工作階段（例如你正在使用自我託管），該指令會回報沒有遠端資料可索取。

沒有產生 Bedrock 資源包

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-*/。

如需逐物品 / 逐 bone 的日誌輸出，請設定 bedrockConverterDebug: true 並重新載入。

Bedrock：因為存在舊版資源包而略過即時提供者

若主控台回報 Legacy RSPM Bedrock pack detected，表示 Geyser 在啟動時已從其資源包目錄掃描過一個舊的 ResourcePackManager_Bedrock.zip。在行程執行期間刪除該檔案，會讓 Geyser 對一個已不存在的路徑持有記憶體中的 codec，因此 RSPM 會刻意在該次啟動中略過它的即時資源包提供者。

請完整停止伺服器，只刪除 RSPM 印出的那個確切舊檔路徑，然後再啟動伺服器。請勿用 /reload 進行這項遷移。目前的資源包仍位於 plugins/ResourcePackManager/output/ 並以每個工作階段的方式提供；它不應該放在 Geyser 的 packs/ 目錄裡。

Bedrock 玩家看到的手持物品位置不正確

這是調整問題，並非轉換 bug。開啟 plugins/ResourcePackManager/bedrock_display_offsets.yml，調整相關軸，執行 /rspm reload，然後讓 Bedrock 測試用戶端重新連線，好讓它下次加入時收到重建後的資源包。第一人稱與第三人稱是獨立的——調整一邊不會影響另一邊。完整的調整選項列表與各項說明，請參閱 Bedrock 轉換。

Bedrock 玩家缺少自訂盔甲材質

自訂盔甲在 Bedrock 上的呈現是結合原版盔甲幾何與 Java 材質作為可見圖層。要使其正常運作，來源外掛的資源包必須在 assets/<namespace>/equipment/<material>.json 下定義一個與物品定義並列的裝備檔。若轉換日誌顯示該物品但遊戲中沒有盔甲材質，請確認該檔案存在於合併後的資源包中。

代理：某個後端表示它沒有網路金鑰

在該後端上，/rspm status 顯示 Network key source: not set — the proxy sends one when a player next connects here，而主控台不斷重複「This backend is behind a proxy but has no network key yet」。

缺少 plugins/floodgate/key.pem 並不是原因——該檔案現在是選用的。金鑰由代理持有：它會載入自己的 network-key 檔案，或在 Floodgate 的 key.pem 存在時一次性地從中衍生種子，或產生一把全新金鑰，然後在有玩家連線到某個後端時把金鑰推送過去。

請依序檢查：

1. 代理啟動之後，有玩家連線過那個後端嗎？授予是搭著玩家連線一起送出的。
2. ResourcePackManager.jar 真的在代理上嗎？後端會替你在 plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar 預備一份自身 jar 的副本並印出該路徑——把它複製到代理的 plugins/ 並重新啟動代理。
3. 在使用現代轉發的 Velocity 上，後端的轉發密鑰與代理的一致嗎？設定為現代轉發的後端會刻意拒絕未簽章或簽章錯誤的授予，其日誌會指出是哪一種。在兩側修正密鑰後，下一次玩家連線就會自行重試。
4. 比對兩端 /rspm status 中的 Network key fingerprint 行。指紋相同即代表連結正常；金鑰本身永遠不會被印出。

完整順序請參閱代理網路。

代理：「Could not save the network key」

代理解析出了金鑰，卻無法將它寫入自己的 network-key 檔案。當次啟動仍可運作。但下次重啟會產生一把不同的金鑰，而所有已佈建過的後端都會保留舊金鑰並拒絕新的——整個網路會靜默地失去連結。

請在重新啟動之前修正代理外掛資料夾的檔案系統權限。

代理：經過數次輪詢仍顯示「no merged pack」

在代理上經過 ~20 秒的空輪詢週期（預設間隔 5 秒，共 4 次）之後，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 → 後端正在運作但未產生 Bedrock 資源包。請在每個後端執行 /rspm status；Bedrock Pack 診斷區塊會告訴你原因。

該橫幅在每次「卡住」期間只會觸發一次，當至少一個後端開始重新回傳內容時，會記錄一行「NetworkSync: recovered」。更多資訊請參閱代理網路。

代理：首次代理啟動時 Bedrock 玩家看不到模型

Geyser 只在代理啟動時才會註冊其自訂物品表。如果代理在任何後端產出 Bedrock 資源包之前啟動，Geyser 會在空對應表的狀態下運行，並維持整個工作階段不變。

修復方式是在代理記錄了 Merged Bedrock pack published at ... 之後重新啟動代理。RSPM 會在代理啟動時預先佈署前次執行的對應檔，因此這個問題僅會在全新安裝時出現——之後的啟動都會在 Geyser 掃描前就準備好對應內容。

後端：「Backend HTTP server failed to bind on port X」

在網路模式下，後端會透過一個小型 HTTP 伺服器公開其 Bedrock 輸出。若連接埠被佔用或無法使用，主控台會出現多行的 [ERROR] 區塊。修復方式：

• 在 config.yml 中將 selfHostPort 設為另一個正整數。
• 或變更 networkHttpOffset-v2，讓自動衍生的連接埠避開衝突（例如 RCON 在 mcPort + 1？將其設為 2 或 3）。你不需要更新代理以保持一致：一旦後端成功綁定，它就會自動向代理通報其實際的 HTTP 連接埠，因此代理本身的 network-http-offset-v2 只在通報之前作為猜測才有意義。

當後端 HTTP 伺服器停擺時，此後端的 Bedrock 資源包無法透過直接擷取送到代理。但 magmaguy.com 中繼回退仍能運作（後端會將檔案推送到中繼端點，代理則從那裡擷取）。

清理過時的 v1 設定

從 RSPM v1 升級的操作員，其 config.yml 中可能還留有失效的 networkHttpOffset（沒有 -v2）鍵。RSPM v2 刻意不讀取舊鍵——下次啟動時會自動將 v2 預設值（1）寫入設定。失效的 v1 鍵會作為無害的殘留留在設定中，直到你手動清理為止。