跳到正文
本頁目錄

LegacyScriptEngine 的報錯與崩潰

在 LegacyScriptEngine(Lua 引擎)上運行 iLand(iland-core.lua)等 Lua 插件時加載失敗,報 module 'dkjson' not found / 缺少 dkjson.lua,怎麼解決?

dkjson 是 iLand 等 Lua 插件自帶的第三方依賴庫,與 LeviLamina、PreLoader 無關。解決方法:

  1. 從插件原發布頁下載完整插件包,把其中 lib 目錄下的依賴(如 dkjson.lua)放到模組根目錄下的 lib 文件夾,即 mods/lib/dkjson.lua。LSE 0.23.0 起啟動時會創建 plugins → mods 的目錄鏈接,所以放到 plugins/lib/ 效果相同。LSE 的 BaseLib.lua 會把 <模组根目录>/lib/?.lua 加入 Lua 的 package.path,因此插件可直接 require "dkjson";報錯信息中列出的其它搜索路徑也都可以放。
  2. 主腳本(如 iland-core.lua)直接放進 plugins/(即 mods/),啟動服務器後 LSE 會自動把它遷移到同名文件夾並生成 manifest.json,無需手寫 manifest;遷移後需重啟服務器才會加載。
  3. 確認 Lua 引擎已安裝並加載:控制台執行 ll list 查看是否有 legacy-script-engine-lua,ll show <模组名> 查看詳情;未安裝可用 lip install LegacyScriptEngine#lua 安裝。
  4. 檢查是否存在重複的插件文件(例如同時有兩份 iland_core.lua),以及同目錄下其它插件的報錯是否干擾;建議使用 iLand 的修復版,服務器路徑避免中文。

適用版本:LeviLamina + LegacyScriptEngine Lua 引擎當前所有版本;plugins 鏈接到 mods 的行為自 LSE 0.23.0 起

舊 LLSE 插件在 LSE 0.9 及之後版本加載時在 ll.registerPlugin 處報錯(舊版本正常),怎麼辦?

LSE 0.9 之前 registerPlugin 沒有真正實現(直接 return),參數隨便填都不報錯;從 0.9.0 起實現了參數處理並做類型檢查:第 1 個參數(名稱)和第 2 個參數(介紹)必須是字符串,第 3 個參數(版本)須為數組 [major, minor, patch, status?] 或對象 {major, minor, revision, status},第 4 個參數 otherInformation 必須是對象且其中只能是“字符串: 字符串”鍵值對。常見錯誤如把第 4 個參數寫成 null,改成 {} 即可。更簡單的做法是直接刪除/註釋掉 ll.registerPlugin 調用,插件信息寫在 manifest.json 中(該調用在 LSE 中已棄用、並非必需)。另:LSE 0.9.0 中 registerPlugin 的實現缺陷導致部分插件報錯甚至崩服,已在 0.9.1 修復,使用當前版本不會再遇到。

適用版本:LSE 0.9.1 及以上(當前 0.23.1)

手動安裝 LSE 或腳本插件後啟動提示缺少依賴項(如 legacy-script-engine-quickjs、LegacyMoney、LegacyRemoteCall),插件不加載,需要裝哪些組件?

  1. 提示缺少 legacy-script-engine-quickjs(或 -lua/-nodejs/-python):說明插件依賴該 LSE 引擎但沒裝,用 lip install LegacyScriptEngine#quickjs(對應換成需要的變體)安裝,或從 https://github.com/LiteLDev/LegacyScriptEngine/releases 下載對應 zip 手動安裝。
  2. 提示缺少 LegacyMoney / LegacyRemoteCall / iListenAttentively:這些是 LSE 引擎本身依賴的獨立模組,不包含在 LSE 包裡,手動安裝時必須自己從 LiteLDev 組織的對應倉庫 Releases 下載與 LSE 匹配的版本(如 LSE 0.23.x 對應 LegacyRemoteCall 0.23.x、LegacyMoney 0.23.x、iListenAttentively 0.18.x)。用 lip 安裝 LSE 會自動裝好這些依賴,最省事。LegacyParticleAPI 自 LSE 0.15.0 起已不再需要。若插件還依賴其他前置(如 GMLIB 等第三方庫)也要一併安裝。
  3. 目錄結構錯誤:應把壓縮包裡的那個模組文件夾(如 legacy-script-engine-quickjs/)直接放進 mods/,不要多套一層外層文件夾,否則識別不到。

適用版本:LSE 0.21.2 及以上(含 iListenAttentively 依賴);當前最新 LSE 0.23.1

LSE 升級到 0.17.11 及以後版本(如 0.17.13)或重載插件後,很多甚至全部 LSE 插件的命令變成“未知命令”、表單打不開,但插件其他功能正常,降回 0.17.10 就恢復,是什麼原因?怎麼解決?

原因:LSE 0.17.11 把原來基於事件實現的“假命令”(CommandCompatibleAPI)換成了真正註冊到命令系統的命令(LegacyCommandAPI),目的是兼容 LeviStone。從此插件不能再覆蓋已經存在的命令。如果某個 LSE 插件註冊的命令和其他插件或已有命令同名(例如和 LegacyMoney 的 /money 同名),或者命令枚舉(cmd.setEnum)的名字和其他插件重複,就會發生註冊衝突,導致大量插件的命令失效。重複註冊時,控制台還會提示 Runtime command xxx already exists。

排查:逐個移除插件,找出衝突的那個。

解決:修改衝突插件源碼裡註冊的命令名或枚舉名(查找 mc.regPlayerCmd / mc.newCommand / cmd.setEnum 的位置,例如把 /money 改成 /moneys)。如果是與 LegacyMoney 衝突,也可以在 LegacyMoney 的配置裡把 enable_commands 設為 false,關閉它自帶的命令。

適用版本:LSE 0.17.11 及以上(含當前 0.23.x)

裝了某些 LSE 插件後,插件命令提示 no permission 或無法使用,甚至所有指令都失效,控制台執行 stop 也提示“未知的指令”、關不了服,是什麼原因?

LSE 為兼容 LeviStone,從 0.17.11 起把原來的“假指令”改成了真正註冊的指令。如果某個插件註冊的指令不符合原版命令規則,就可能把整個命令系統搞壞,連原版指令(包括 stop)都會失效。常見的不合規寫法:試圖覆蓋原版指令(例如註冊同名的 stop);指令名含大寫字母或非英文字符;指令名或參數不合法。

解決:逐個移除插件,找出註冊了不合規指令的插件,把它的指令改成小寫、合法、不與原版或其他插件衝突的名字,或者讓插件作者修復。

適用版本:LSE 0.17.11 及以上(含當前 0.23.x)

LeviLamina 服務器一有苦力怕爆炸就崩服(生成 trace 日誌),可能是什麼原因?

通常是裝了 JS 寫的防爆類 LSE 插件(如 anticreeper)導致:不少防爆插件在爆炸事件回調(onExplode/onEntityExplode)裡先攔截爆炸再用 mc.explode 重新生成一個爆炸,在新版 LSE 下容易直接崩服。解決:卸載或替換防爆插件,或讓作者不要在爆炸回調裡再創建爆炸;苦力怕防爆也可以直接通過修改行為包實現,無需 LSE 插件。

適用版本:LeviLamina + LSE(第三方防爆插件)。未能從源碼或文檔中直接證實,僅供參考。

2022 年左右的老 LLSE JS 插件(如 lljs-ban)在新版 LSE 上報錯無法運行,是什麼原因,能修嗎?

新版腳本引擎(QuickJS 後端)優先以 ES Module 方式加載 JS 插件入口文件,模塊代碼強制處於嚴格模式(只有入口頂層執行拋異常時才會回退成普通腳本 eval)。很多舊插件沒有考慮嚴格模式,存在變量未聲明就直接賦值使用的情況,在事件/命令回調等運行時代碼中就會報 xxx is not defined 等錯誤。如果會 JS,把這些未聲明的變量補上 let/const/var 聲明即可繼續使用;否則建議換一個仍在維護的同類插件。

適用版本:LegacyScriptEngine(QuickJS 後端)當前版本

BDS 服務器崩潰,trace 日誌顯示疑似死循環/棧溢出,與背包插件有關,是什麼原因?

通常是某個 LSE 插件在 onInventoryChange 事件回調裡又去修改背包物品,修改物品會再次觸發 onInventoryChange,形成遞歸/死循環導致棧溢出崩潰。排查並修改在 onInventoryChange 回調中改動背包物品的插件(例如加重入保護標誌,或用 setTimeout 延後修改並避免重複觸發)。

適用版本:LegacyScriptEngine 當前版本

LL1 時代的老 JS 插件(如在線時長統計 /onlinetime rank)在 LSE 上運行時報錯 i is not defined,排行榜打不開,怎麼修?

新版腳本引擎以 ES Module 方式加載 JS(嚴格模式),未聲明就使用的變量會報錯。根據報錯行號打開插件文件,把 for (i = 0; ...) 改成 for (let i = 0; ...),並檢查整個文件中其它循環變量/變量是否都用 let/const/var 聲明。

適用版本:LegacyScriptEngine(QuickJS 後端)當前版本

LSE JS 插件中 const db = new KVDatabase('plugins/mydb/db'); 之後的代碼都不執行,try/catch 得到 ReferenceError: can't create class KVDatabase,是 bug 嗎?

can't create class KVDatabase 表示 KVDatabase 構造時底層 LevelDB 數據庫打開失敗(構造函數返回空)。常見原因:服務器放在需要管理員權限才能寫入的目錄(如 Program Files)導致無法創建/寫入數據庫目錄(見 LegacyScriptEngine#228);或者同一路徑的數據庫已被其他插件/實例佔用。請把服務器放到普通用戶可寫的目錄、檢查路徑與佔用情況。腳本頂層拋出未捕獲的異常會使後續代碼不再執行,可用 try/catch 捕獲查看錯誤;LSE 0.10.2 起插件加載出錯時會在控制台顯示錯誤(#240)。

適用版本:LSE 當前所有版本(0.10.2 起加載錯誤會顯示)

LSE NodeJS 中 async 函數里 throw 的錯誤在控制台不顯示,和普通 Node.js 行為不一致,怎麼處理?

LSE NodeJS 嵌入環境對未處理的 Promise 拒絕(unhandled rejection)的輸出與獨立 Node.js 不一定一致。建議在調用 async 函數處自行 try/catch(await)或 .catch(),並用 logger.error 輸出錯誤。

適用版本:LSE NodeJS 引擎。未能從源碼或文檔中直接證實,僅供參考。

LSE NodeJS 引擎下更新到最新版 npm 後,npm 相關功能無法使用,怎麼辦?

LSE 的 npm/npx 控制台命令是在內嵌的 Node 環境中直接執行引擎目錄下 node_modules/npm/bin/npm-cli.js(npx-cli.js)的,若把 npm 升級到與內嵌 Node 版本不兼容的版本就會失效,使用隨 LSE 附帶的(或兼容的舊版)npm 即可。替代方案是用外部的 node.exe 執行 npm。

適用版本:LSE NodeJS 引擎。未能從源碼或文檔中直接證實,僅供參考。

LSE nodejs 插件中寫了無限遞歸/佔用大量內存後出現崩潰報錯,這是 Script API 還是 LSE 的問題?

這是 Node.js(V8)的報錯,表示 V8 棧溢出/內存耗盡,來自 LSE 的 nodejs 引擎,而非 BDS 的 Script API。另外在 quickjs 引擎中無限遞歸可能直接讓 BDS 崩潰。需要排查插件中的無限遞歸或內存佔用過大的邏輯。

適用版本:LSE nodejs / quickjs 引擎。未能從源碼或文檔中直接證實,僅供參考。

LSE quickjs 插件報錯 C++ Exception: script::Exception ... not a function ... In callback for sendForm 是什麼原因?

表示表單回調裡調用的某個東西不是函數(函數不存在或對象為空),是插件代碼問題,需檢查插件代碼。常見於菜單類插件註冊的命令被 runcmd/控制台執行時:例如回調中 en.toPlayer() 得到的不是玩家對象(非玩家實體時返回空),後續再調用玩家方法就會報錯,可改成 mc.getPlayer(en.name) 獲取玩家對象並先判空。

LSE 啟動時報錯 ERROR [legacy-script-engine-quickjs] failed to load: Failed to migrate legacy plugin at plugins/XXX.js: plugins/XXX already exists 怎麼解決?

LSE 啟動時會把 plugins/(0.23.0 起是指向 mods/ 的鏈接)根目錄下的單文件舊插件(如 XXX.js)遷移到 mods/XXX/XXX.js,並生成 manifest.json。如果目標位置 mods/XXX/XXX.js 已經存在(插件之前已遷移過,你又放了一份同名單文件),遷移就會報這個錯。處理方法:刪除根目錄下重複的那個 XXX.js;如果要用新文件替換,就先刪掉或清空舊的 mods/XXX 目錄,再重啟服務器。遷移完成後還要再重啟一次,插件才會加載。

適用版本:LSE 0.x 至當前(0.23.x);0.23.0 起 plugins/ 是指向 mods/ 的鏈接

LSE 加載舊插件時報錯,提示事件 onEnderDragonDestroy 不存在(舊版為 Event "onEnderDragonDestroy" No Found!,新版為 Event onEnderDragonDestroy not found!),怎麼辦?

LSE 已經刪除了 onEnderDragonDestroy 事件,是插件作者沒有跟進更新。這個報錯只表示該監聽沒有生效,不影響其他功能,可以忽略。嫌報錯煩的話,可以把插件代碼裡監聽該事件的 mc.listen("onEnderDragonDestroy", ...) 那段註釋掉。

適用版本:LSE 0.6.x 至當前(0.23.x)

LSE 控制台出現 WARN [legacy-script-engine-quickjs] Could not find menu in registered commands. 是什麼原因?

這條警告來自 LSE 的命令執行回調:執行命令時,LSE 會進入最後一次對該命令調用 setCallback 的插件所在的引擎,再在該插件自己的 registeredCommands 裡查找這個命令的參數註冊信息(通過 mandatory/optional/setEnum/overload 等調用記錄)。找不到就輸出 Could not find menu in registered commands.,命令也不會執行。常見的排查方向是命令衝突,例如兩個插件都註冊了 menu(註冊時控制台通常會有 Runtime command menu already exists... 警告),或者某個插件只對該命令調用了 setCallback,卻沒有註冊參數/重載。檢查並移除重複註冊該命令的插件,或者確認插件在 setCallback 之前調用了 overload 等註冊函數。

適用版本:當前所有 LSE 版本(至 0.23.x)。未能從源碼或文檔中直接證實,僅供參考。

LSE 插件用 pl.setSidebar 設置的側邊欄中,出現了玩家 ID/名字而不是配置的內容,怎麼解決?

一個可能的原因是計分板 ID 衝突:LSE 的 setSidebar 發 SetScorePacket 時,直接把每一行的計分值用作 mScoreboardId,可能和客戶端裡已有的真實計分板條目(例如玩家的計分 ID)撞上,於是顯示成了玩家名。可以嘗試刪除存檔裡的所有計分板,或者調整各行的計分值來驗證;如果確認是這個問題,可以向 LSE 提 issue。

適用版本:當前 LSE 版本(至 0.23.x)。未能從源碼或文檔中直接證實,僅供參考。

LSE 插件熱重載(如 ll reload)後,數據庫查詢和插入正常,但更新和刪除失效,怎麼辦?

不建議用熱重載重新加載 LSE 插件,熱重載後插件持有的數據庫連接(DBSession)等資源狀態可能異常。直接重啟服務器即可。

未能從源碼或文檔中直接證實,僅供參考。

LSE 服務器在玩家重生等涉及 NBT 的操作時崩服(崩潰與 CompoundTag/NBT 有關),原因是什麼?

LSE 的 NbtCompound 內部要麼用 unique_ptr 持有 CompoundTag(擁有所有權),要麼只持有裸指針(借用)。如果某個 tag 經 RemoteCall 導出給其他插件,對方銷燬了它或轉移了所有權,LSE 再訪問時就會崩潰,所以外部插件不應銷燬任何 LSE 導出的對象。實際案例中,是舊插件 StillHungry.lls(玩家死亡後保持飢餓值,直接改 NBT)在重生時觸發了崩服,卸載該插件即可解決。自己重寫時注意:飢餓值(hunger)和飽和度(saturation)是兩個不同的屬性。

適用版本:LeviLamina + LSE 當前版本

LSE 的 QuickJS 插件使用 import 語法時報錯(如 Failed to load plugin xxx: expecting '(' 之類的語法錯誤),而插件路徑和代碼看起來都沒問題,可能是什麼原因?

已知 BDS(服務端)路徑中含有中文會導致 QuickJS 引擎(legacy-script-engine-quickjs)的 import 出問題。把 BDS 和插件放在純英文路徑下即可;無論什麼原因,都建議服務端和插件路徑不要帶中文。

適用版本:LegacyScriptEngine QuickJS 引擎,當前所有版本(相關 issue 仍未關閉)

LSE 的 Node.js 插件中使用 node-fetch 報 fetch 未定義/導入失敗,但同樣代碼直接用 node 運行沒問題,怎麼辦?

node-fetch 3.x 只提供 ES Module,在 CommonJS 插件裡用 require 會失敗。可選方案:

  1. 把依賴改為 node-fetch ^2.6.7(CommonJS 版本)。
  2. 在插件的 package.json 中加 "type": "module",讓插件以 ESM 方式加載,再用 import 引入 node-fetch 3.x(LSE 0.10.6 起支持 Node.js ESM 插件)。
  3. LSE 現在內置的是 Node.js v22.12.0,可直接使用全局 fetch,或用內置 http/https 模塊。
  4. 使用 LSE 自帶的網絡接口 network.httpGet 等。

另外在插件目錄的 package.json 中聲明 dependencies 後,若插件目錄下沒有 node_modules,LSE 加載插件時會自動執行 npm install --omit=dev 安裝依賴。

適用版本:LegacyScriptEngine Node.js 引擎;ESM 方案需 LSE 0.10.6 及以上

LSE 的 Node.js 插件加載報錯(讀取 JSON 失敗 / 缺少 libnode.dll / npm 執行失敗等)怎麼排查?

若報錯是讀取 JSON 文件失敗,通常是某個 Node.js 插件目錄下的 package.json 等 JSON 文件格式有誤,需逐個檢查 nodejs 插件的 JSON 文件。若提示缺少 libnode.dll,說明 Node.js 運行時沒裝全:libnode.dll 等文件應位於 mods/legacy-script-engine-nodejs/ 目錄。最好用 lip 安裝 Node.js 引擎(lip install github.com/LiteLDev/LegacyScriptEngine#nodejs),lip 會同時下載引擎本體和 node-prebuilt 運行時,保證文件完整。如果仍有異常,可能是服務端文件本身損壞,可新建一個乾淨的服務端重新安裝。

適用版本:LegacyScriptEngine Node.js 引擎,LeviLamina 1.x(mods 目錄)及以後

LSE 適配 LeviLamina 26.60 後,調用 logger.setConsole 的腳本插件導致服務器崩潰,且 latest 日誌來不及寫入,怎麼處理?

這是 LSE 0.23.0 中 logger.setConsole 實現的 bug(向需要 string_view 的參數傳入 0 導致空指針崩潰),已在 LSE 0.23.1 修復,升級到 0.23.1 或更高版本即可。暫時無法升級時,可在插件目錄中搜索並註釋掉所有 setConsole 調用。崩潰時 latest 日誌為空是因為崩潰發生得太早,日誌來不及寫入。另外注意:logger.setTitle 會重新獲取/創建一個新的 logger,因此應先調用 setTitle,再調用 setConsole/setFile/setPlayer/setLogLevel,否則之前的設置會失效。

適用版本:LegacyScriptEngine 0.23.0(崩潰);setTitle 調用順序注意事項適用於當前版本

LSE JS 插件導致服務器崩潰(生成 minidump/trace 日誌),最後排查出與註冊命令有關,原因是什麼?

原因是插件註冊命令(mc.newCommand 等)時命令名使用了大寫字母。LSE 註冊命令時命令名(以及除 String、RawText、Message 等可變參數外的命令內容)只能使用英文小寫字母,改為全小寫即可。

適用版本:LegacyScriptEngine 當前所有版本

LSE(QuickJS)插件導致崩潰但日誌沒有任何有用信息,如何調試定位?

LSE 的 release 壓縮包裡已經自帶各引擎的 pdb 調試符號(如 legacy-script-engine-quickjs.pdb),安裝後與 dll 一起位於 mods/legacy-script-engine-quickjs/ 目錄;確保 pdb 與所用 dll 版本一致(不一致時從 https://github.com/LiteLDev/LegacyScriptEngine/releases 下載對應版本的壓縮包取出 pdb)。然後用 Visual Studio 調試器附加到 bedrock_server.exe 進程,復現崩潰即可看到帶符號的調用棧。示例案例中最終定位到 CompoundTag(NBT)對象被提前銷燬,與通過 LegacyRemoteCall 傳入的 NBT 對象有關。

適用版本:LegacyScriptEngine 當前版本(pdb 隨 release 壓縮包分發)

LeviLamina + LSE 開服正常,但玩家一進服服務器就崩潰,崩潰日誌在哪?之前裝過多維度插件會有影響嗎?

崩潰日誌在服務端目錄的 logs/crash 下,包括 minidump_<时间>.dmp 和 trace_<时间>.log 兩個文件,求助時應把它們一起發出來。本例分析結果是:之前裝過基於多維度(自定義維度)的插件,存檔裡留有自定義維度數據,卸載該插件後,玩家下線時所在的維度已不存在,進入服務器時就會崩潰;把多維度插件裝回去即可恢復(或先讓玩家離開自定義維度再卸載)。

適用版本:LeviLamina 當前版本;多維度部分適用於使用過 MoreDimensions 等自定義維度插件的存檔。未能從源碼或文檔中直接證實,僅供參考。

LeviLamina + LSE 環境下服務器一啟動就崩潰(刪掉其他模組也無效),可能是什麼原因?

一個常見原因是 LSE 的 Python 引擎(legacy-script-engine-python):系統裡另外裝了 Python(且在 PATH 中)時,Python 引擎可能無法加載、報一長串錯,甚至直接崩服。如果不用 Python 插件,卸載 Python 引擎即可(刪除 mods/legacy-script-engine-python 目錄,或用 lip 卸載 LegacyScriptEngine#python 變體);需要 Python 插件的話,確保系統 Python 版本與引擎內置版本一致(當前為 3.12.10)或把它從 PATH 中移除。排查時請看 logs/crash 下的 trace 日誌確認崩潰點。

適用版本:安裝了 LSE Python 引擎的 LeviLamina 服務器(當前所有版本,具體是否衝突視用戶環境而定)。未能從源碼或文檔中直接證實,僅供參考。

LeviLamina 服務器每隔一兩個小時隨機崩服,崩潰日誌每次都不一樣,其中有堆棧指向 LeviLamina 的關卡 tick 事件 hook(舊版為 ll::event::world::LevelTickEventHook::detour),刪插件、換新存檔都還會崩,怎麼排查?

實際案例中是一個老舊的 JS 自動備份插件導致:它在服務器運行時直接讀取存檔目錄並調用 7z 壓縮,引發空指針崩潰(所以堆棧看起來像是 tick 事件裡出問題,且每次報錯都不同)。換成 BackupHelper 這類走 BDS 正常備份流程(save hold/query/resume)的備份插件後恢復正常。經驗:不要在運行中直接拷貝/壓縮存檔;定時任務建議用插件而不是命令方塊。

適用版本:LeviLamina 1.x 及以上,使用運行時直接複製存檔的第三方備份插件的服務器。未能從源碼或文檔中直接證實,僅供參考。

LeviLamina 服務器崩潰,CrashLogger 的 trace 日誌顯示崩潰於 LSE 的 data.toJson(堆損壞),如何排查?

崩潰點在 LSE 的 data.toJson 調用處且伴隨堆損壞,說明某個腳本插件向 data.toJson 傳入了異常數據。在插件目錄中全局搜索 data.toJson,找出調用它的插件,禁用或修復該插件後觀察是否還會崩潰;求助時附上 logs/crash 下的 trace_*.log 和 minidump。

未能從源碼或文檔中直接證實,僅供參考。

LeviLamina 服務器運行中崩潰,崩潰文件在哪裡?如果 trace 日誌顯示是死循環/棧溢出,與 JS 插件監聽 onExperienceAdd 有關,應如何排查?

崩潰文件位於服務器目錄 ./logs/crash 下,包括 minidump_*.dmp 和 trace_*.log,求助時兩個都發。本例 trace 顯示是死循環:某個 JS 插件監聽了 onExperienceAdd 事件,又在回調裡再次給玩家增加經驗(如 player.addExperience),從而再次觸發該事件,無限遞歸導致棧溢出崩潰。排查方法:用 VSCode 等編輯器在插件目錄(plugins/,即 mods/)中全局搜索文件內容(不是文件名)“onExperienceAdd”,找到監聽該事件的插件(本例為一個 VIP 經驗翻倍腳本),卸載它或修復其邏輯(避免在回調中重複觸發同一事件,例如加防重入標記,或改為修改/攔截原事件)即可。

適用版本:當前所有版本(LeviLamina + CrashLogger + LSE)

LeviLamina 服務端(如 Windows Server、或用機器人程序啟動時)一啟動就閃退/頻繁崩潰,已裝 VC++ 運行庫,該看哪個日誌、怎麼排查?

求助時應提供 logs\crash\ 下的 trace_xxx.log(以及 minidump_xxx.dmp),而不是 LeviLamina-latest.log。這類啟動崩潰較常見的原因是 LSE 的 Python 引擎(legacy-script-engine-python)與系統已安裝的 Python 環境衝突。若沒有 Python 插件,直接刪除 mods 目錄下的 legacy-script-engine-python 文件夾(或用 lip 卸載 LegacyScriptEngine#python 變體);若需要 Python 插件,則讓系統 Python 與引擎版本一致(3.12.10)或將其移出 PATH,二者擇一處理。

適用版本:LeviLamina + CrashLogger,安裝了 LSE Python 引擎的服務器(當前所有版本)。未能從源碼或文檔中直接證實,僅供參考。

同一個版本的 LegacyScriptEngine(LSE),為什麼有些插件加載成功、有些插件加載失敗?

LSE 按語言分為多個引擎,需分別排查:

  1. Node.js 引擎要用 lip 安裝(lip install github.com/LiteLDev/LegacyScriptEngine#nodejs),lip 會同時下載 Node 預編譯運行庫;若 lip 無法使用,可手動從 https://github.com/LiteLDev/node/releases 下載對應的 node-prebuilt.zip(當前為 v22.12.0),解壓後把內容放進 mods/legacy-script-engine-nodejs/ 目錄。
  2. Python 引擎需要系統安裝對應版本的 Python(LSE >=0.16.2 為 Python 3.12.10)。
  3. 如果報缺少符號(missing symbol),說明 LeviLamina 版本與 LSE 不匹配,需要安裝 LSE 要求的 LeviLamina 版本(LSE 0.23.x 需要 LeviLamina 26.60.*)。

適用版本:LSE 0.16.2 及以上(當前 0.23.x)

裝好 LeviLamina 和 LSE 後啟動,控制台彈出一堆報錯然後窗口直接消失,怎麼辦?

有用戶排查後發現是 LSE 的 Python 引擎(legacy-script-engine-python)導致,刪掉後服務器正常啟動。Python 引擎依賴系統安裝的對應版本 Python(當前 LSE 要求 Python 3.12.10),環境不對可能導致啟動失敗;如果不需要 Python 插件,可以直接卸載該引擎(刪除 mods/legacy-script-engine-python 或用 lip 卸載)。

適用版本:安裝了 LSE Python 引擎的服務器。未能從源碼或文檔中直接證實,僅供參考。

崩潰日誌顯示 BDS 內部讀取 ItemStack 時出錯(疑似 ItemStack 被提前釋放),會是 LSE 的 JS 插件導致的嗎?

一般不是。LSE 腳本中的物品對象(Item)背後的 ItemStack 由 LSE 本體或 BDS 管理,腳本無法直接釋放它;這類 ItemStack 生命週期問題應優先排查原生(native/C++)mod。

適用版本:LeviLamina + LSE 當前版本(經驗判斷)。未能從源碼或文檔中直接證實,僅供參考。

開服時 LSE 報錯 Fail to import! Function [LLSEGlobal::LoginAPI] has not been exported!,這是什麼原因?

某個腳本插件通過遠程調用 ll.imports("LLSEGlobal", "LoginAPI") 導入另一個插件導出的函數,但導出該函數的前置插件(此處是登錄類插件)沒有安裝或沒有加載成功(也可能是加載順序導致導入時尚未導出)。

在 plugins 目錄中全局搜索字符串 LoginAPI,找到是哪個插件在導入或導出,然後安裝或修復其依賴的前置插件即可。

開服時出現與 config.reload() 相關的 JSON 解析報錯,但沒指出是哪個 LSE 插件,如何排查?

通常是某個插件的配置 json 文件為空或損壞,導致 JsonConfigFile 的 reload()(內部用 JSON 解析器讀取文件)解析失敗並拋出異常。

可以寫腳本掃描 plugins 目錄下所有 .json 文件,找出解析出錯的(重點看大小為 0 的空文件),修復或刪除對應配置(數據文件注意先備份)後重啟。

把 LeviLamina 服務端放在磁盤根目錄運行時,LSE 插件用 ./ 相對路徑寫入文件失敗,是什麼原因?

磁盤根目錄(尤其是系統盤 C:\)普通用戶沒有相應的寫入權限,導致寫入失敗。把服務端放到一個普通文件夾裡運行即可。

適用版本:Windows,當前版本。未能從源碼或文檔中直接證實,僅供參考。

服務器一有玩家進入就刷屏“該指令引用了0x%P的內存,該內存不能為%s”,一段時間後崩服,怎麼解決?

本質是內存訪問越界(訪問違規),原因可能很多:加載了與當前版本不匹配的 mod、mod 之間不兼容、缺少前置、mod 本身的 bug、Mojang 的 bug 等。有案例是 LegacyScriptEngine 版本過舊,更新到與當前 BDS/LeviLamina 匹配的 LSE 版本後解決。

排查方法:

  1. 確認 BDS 版本與 LeviLamina/LSE/各 mod 版本對應。
  2. 用二分法逐個移除 plugins 目錄下的 mod/腳本插件,定位問題來源(腳本插件可看其 manifest.json 中的 type 是否為 lse-* 來區分)。

適用版本:當前版本(通用排查思路)。未能從源碼或文檔中直接證實,僅供參考。

服務器後臺加載舊插件時報錯(涉及 LegacyAddonsManager、CustomMap、BehaviorLog.lxl.js),怎麼處理?

  • LegacyAddonsManager 已停更並歸檔,不再維護,不要再使用(可自行 fork 適配,或手動/用其他工具管理 addon)。
  • CustomMap 版本不對,需換成與當前版本匹配的版本。
  • BehaviorLog 插件已不兼容,刪除 plugins/BehaviorLog.lxl.js。

適用版本:LeviLamina 當前版本

服務器啟動時一直卡在加載 Lua 引擎(LSE lua)不動,重試幾次有時能過,怎麼解決?

一般是某個 mod 缺少依賴導致卡住,檢查各 mod 的依賴是否齊全。

如果沒有使用 Lua 插件,可以直接刪除 LSE 的 Lua 引擎(plugins/legacy-script-engine-lua)。

適用版本:LeviLamina 與 LSE 當前版本。未能從源碼或文檔中直接證實,僅供參考。

服務器啟動時多個 LSE 腳本插件報錯 [json.exception.parse_error.101] parse error at line 1, column 1: syntax error while parsing value - unexpected end of input,同時出現 LevelDB IO error: fwrite failed / database or disk is full,而自己沒有改過配置,怎麼辦?

這是插件的 JSON 配置/數據文件內容損壞(如變成空文件、丟失頂層 {} 或 []),通常由服務器意外關機、斷電、磁盤寫滿或服務商遷移導致數據未寫完。

先清理磁盤空間,然後刪除出問題的 JSON 配置文件,讓插件重新釋放默認配置後再啟動;如需手動編輯,確保保存為 UTF-8 編碼、JSON 語法正確。

注意有些 JSON 是數據文件,刪除會丟數據,最好從備份恢復;存檔(LevelDB)損壞也只能從備份恢復。該問題最早見於 LiteLoaderBDS,LSE 仍適用。

服務器安裝了 LSE Python 引擎後,部分玩家客戶端進服就提示“破損的數據包”(server sent broken packet)/崩潰,原因是什麼?

這是已知問題(LegacyScriptEngine issue #103,截至目前仍未關閉):服務器啟用了“客戶端區塊生成”(BDS server.properties 中的 client-side-chunk-generation-enabled)時,與 LSE Python 引擎(legacy-script-engine-python)衝突,玩家進服會提示 server sent broken packet(破損的數據包);關閉該選項或不安裝 Python 引擎時可正常進服。

規避辦法:在 server.properties 中設置 client-side-chunk-generation-enabled=false,或暫時不使用 Python 引擎。

適用版本:使用 LSE Python 引擎的服務器(issue 最初報告於 LSE 0.6.2 / BDS 1.20.72,最新版本未見修復記錄)

裝了 GMLIB 和 iLand 等腳本插件後服務器崩潰,trace 日誌顯示在加載 JSON 配置文件時崩潰,怎麼排查?

崩潰是某個插件在加載 JSON 數據/配置文件時出錯,通常是該插件的 JSON 數據文件損壞(格式無效)。檢查各插件的 json 配置/數據文件,修復或刪除損壞的文件即可。

若無法自行定位,可在 GitHub 開 issue 並附上崩潰日誌和 dmp 文件供開發者調試。

適用版本:當前版本(涉及第三方插件)。未能從源碼或文檔中直接證實,僅供參考。

服務器裝了 LSE 引擎和領地插件 iLand 後,玩家一挖方塊、一打動物控制台就報錯,怎麼解決?

報錯來自與 iLand 配套的 iLandHelper 插件(與當時的 LSE 不兼容),刪除 iLandHelper 即可。

一般原則是根據報錯堆棧中的插件名找到出錯插件並移除或更換。

適用版本:使用 iLand / iLandHelper 第三方插件的服務器。未能從源碼或文檔中直接證實,僅供參考。