疑難排解

手機無法連線

確認 .env 使用 HOST=0.0.0.0。
手機網址必須使用主機 LAN IP，不能使用 localhost 或 0.0.0.0。
確認手機與主機位於同一網段，且不是訪客 Wi-Fi。
開放作業系統防火牆的面板 TCP 連接埠。
檢查 AP Isolation、Client Isolation 或 VLAN 規則。

Windows：

Get-NetTCPConnection -LocalPort 8787

Linux：

ss -lntp | grep ':8787'

應看到 0.0.0.0:8787 或 [::]:8787，而不是只監聽 127.0.0.1。

Windows 安裝卡在 better-sqlite3 或 node-gyp

請先查看啟動器保存的完整紀錄：

runtime/install/npm-install.log

BlockPilotMC v1.0.4 使用含 Windows x64 預編譯檔的 better-sqlite3 13.0.2。一般 Windows 10/11 x64、Node.js 22–26 不應進入本機編譯。若日誌仍出現 node-gyp rebuild、Could not find any Python installation 或 find VS：

確認使用 x64 版 Node.js，而不是 32 位元或非標準架構版本。
刪除可能殘留的舊相依套件後重新執行語言啟動檔：

Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue
Remove-Item .blockpilot-npm-lock.sha256 -Force -ErrorAction SilentlyContinue
.\Start-BlockPilot-TW.bat

如果套件仍必須從原始碼編譯，安裝 Python 3 與 Visual Studio 2022 Build Tools 的「使用 C++ 的桌面開發」工作負載。啟動器會偵測缺少項目並顯示可用的 winget 指令。

正式環境稽核結果位於：

runtime/install/npm-audit.log

不要直接執行 npm audit fix --force。請先確認受影響套件、實際使用路徑與升級相容性，再由專案版本統一更新。

Linux 原生模組錯誤

從 Windows 複製專案到 Linux 後：

rm -rf node_modules
npm ci

前端沒有更新

BLOCKPILOT_REBUILD_WEB=1 npm start

Windows CMD：

set BLOCKPILOT_REBUILD_WEB=1
node app.js

Java 無法啟動

java -version

Windows 可執行：

powershell -ExecutionPolicy Bypass -File scripts/diagnose-java.ps1

忘記管理員密碼

npm run reset-admin -- admin 新密碼

API 健康檢查

http://127.0.0.1:8787/api/health

Windows API 控制台訊息更新過快

Windows 啟動器會把 WEB 與 API 訊息分成兩個控制台。API 預設不顯示狀態碼為 200 的一般 Dashboard 輪詢，只保留啟動訊息、失敗請求與超過一秒的慢速請求。

如果仍看到舊版每秒大量出現 incoming request 與 request completed，請重新執行其中一個語言啟動檔，讓 npm run build 更新 API：

Start-BlockPilot-TW.bat
Start-BlockPilot-ZH.bat
Start-BlockPilot-EN.bat

API 視窗可用 Ctrl+C 停止；WEB 視窗只負責啟動狀態與開啟瀏覽器，關閉它不會停止 API。

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History