指南
如何修正 Minecraft 插件錯誤
更新於 2026年10月18日
插件無法載入時，伺服器幾乎都會說明原因：原因就在啟動時的主控台裡，插件名稱的上下幾行。學會看懂日誌的這一段，大多數錯誤一分鐘就能修好。以下是常見的錯誤和它們的意思。
寫明你的伺服器版本，以及插件該做什麼。
用 Codexe 產生這個逐步說明
1.打開啟動日誌
查看主控台，或伺服器資料夾裡的
logs/latest.log。如果用的是主機商的控制面板，就用它的主控台或檔案管理員。2.搜尋插件的名稱
找到第一個提到它的錯誤。以
[ERROR]或[WARN]開頭、下面接著堆疊追蹤的那幾行才是重點。3.看第一行和「Caused by」那幾行
第一行說明什麼失敗了；最後一個
Caused by:行通常會說明原因。帶有插件自己套件名稱的那幾行，會指出它程式碼裡出錯的位置。4.對照下面的清單
大多數啟動錯誤都是版本、Java 或相依插件的問題，訊息會告訴你是哪一種。
5.一次只修一個地方，然後重新啟動
改一個地方，重新啟動（不要用
/reload），再看一次日誌。一個插件的錯誤可能會連帶造成其他插件出錯。
常見錯誤
| 你看到的訊息 | 代表什麼 | 解決方法 |
|---|---|---|
Unsupported API version 1.21 | 插件的 api-version 比你的伺服器還新。 | 取得適用你伺服器的版本，或升級伺服器。 |
Could not load 'plugins/X.jar'，並伴隨 Invalid plugin.yml 或 Jar does not contain plugin.yml | 插件的描述檔不見了或有 YAML 錯誤，或這個檔案根本不是插件。 | 確認你下載的是插件本身，而不是它的原始碼、模組或 zip。如果是你自己建置的，請修正 plugin.yml。 |
UnsupportedClassVersionError、「class file version 65.0」 | 插件需要的 Java 比伺服器正在用的還新（61 = Java 17，65 = Java 21，69 = Java 25）。 | 用那個版本的 Java 執行伺服器，或針對你的 Java 重新建置插件。 |
NoClassDefFoundError 或 ClassNotFoundException | 插件需要的某個類別不存在：少了某個相依插件、某個函式庫沒有打包進 .jar，或這個 API 在這個版本上不存在。 | 安裝錯誤訊息裡提到的插件（Vault、ProtocolLib），或改用適合你版本的建置。 |
Unknown/missing dependency plugins | depend 裡列出的某個插件沒有安裝。 | 把它裝進 plugins/。 |
Error occurred while enabling X (Is it up to date?) | 插件已載入，但在 onEnable 裡當掉了。 | 看 Caused by 那一行：通常是設定錯誤或缺少相依插件。 |
Ambiguous plugin name | plugins/ 裡有同一個插件的兩個 .jar 檔案。 | 刪掉舊的那個。 |
和載入無關的錯誤
- 插件是綠色的，但指令顯示「Unknown command」：
plugin.yml裡少了這個指令，或另一個插件用了同樣的名稱。 - 「I'm sorry, but you do not have permission」：玩家缺少權限節點。在插件頁面查到該節點，再用你的權限插件給予它。
- 修改 config.yml 之後出錯：YAML 要用空格，不能用 Tab，而且開頭是
:或&的文字要加上引號。 - 重新啟動後正常，用 /reload 後就壞掉：這個插件不支援
/reload。請改成重新啟動。
你的伺服器需要哪個 Java
Minecraft 1.20.5 以上需要 Java 21，26.x 需要 Java 25；1.18 到 1.20.4 需要 Java 17。用伺服器使用的同一個 Java 執行 java -version（在主機商的控制面板上，通常是一個叫 Docker 映像檔或 Java 版本的設定）。為舊版 Java 建置的插件可以在新版 Java 上執行，反過來就不行。
修正用 Codexe 製作的插件
在 Codexe 上做的插件會針對你選擇的版本編譯，並在變成就緒之前確認 plugin.yml 有效。在測試伺服器上，日誌分頁會即時顯示日誌並標出錯誤，匯出日誌可以把它存成檔案。在專案聊天中描述你看到的狀況（「插件在 /plugins 裡是紅色的，日誌寫著……」），Codexe 就會修改程式碼並重新建置。如果 Codexe 交付的檔案在完全沒改動的情況下編譯失敗，用 AI 修正會免費把它們修好。
常見問題
伺服器日誌在哪裡？
伺服器資料夾裡的 logs/latest.log，記錄的是這次執行。之前的執行紀錄會以 .log.gz 檔案放在同一個資料夾。
一個插件會弄壞另一個插件嗎？
會：少了或壞掉的相依插件，會讓所有需要它的插件都停擺。請先修好日誌中的第一個錯誤，再處理其他的。
分享我的日誌安全嗎？
大致上安全，但先檢查一下：日誌可能含有 IP 位址，某些插件的錯誤訊息裡甚至會出現資料庫密碼。
替你的伺服器重新建置壞掉的插件
這則提示詞開啟後即可直接傳送：
“一個名為 SimpleWarps 的 Paper 1.21.4 插件，用來取代我那個已經無法載入的舊插件：帶名稱的 /setwarp、/warp 和 /delwarp，/warps 在介面中列出所有傳送點，設定和刪除需要 warps.admin 權限，傳送點在重新啟動後仍會保留，訊息放在 config.yml。”
用 Codexe 產生這個