Troubleshooting zh TW

English | 繁體中文

本頁涵蓋實際使用 NextVoiceCord 時會遇到的各種失敗狀況：你會看到什麼、為什麼會發生，以及該怎麼處理。

播放失敗，或沒有聲音

症狀： 機器人加入了語音頻道，並顯示某首曲目正在播放，或是在載入時回報錯誤，但沒有任何聲音， 或是某個連結／搜尋結果完全無法播放。

原因： 這個專案之所以是 Beta 版，原因就出在 YouTube 擷取（extraction）這一塊。目前已發布的 youtube-source 版本無法播放相當大一部分的影片，因此本專案固定使用一個尚未正式發布、但可以播放 這些影片的快照版本。正是這個固定版本讓播放現在能夠正常運作，但這也意味著這個擷取層走在任何官方 發布版本之前——它會在每次 CI 執行時，依實際播放結果做驗證，而且一旦上游有正式版本通過相同的測試， 這個固定版本就會被移除，但這與依賴一個穩定發布版本的保證程度並不相同。

該怎麼做： 如果某支特定影片無法播放，先試試不同的來源或搜尋字詞，不要立刻認定是你的環境設定 出了問題——這是目前 Beta 版本本身結構性的已知限制，通常不是設定問題。可以查看你所使用版本的 發行說明，確認你遇到的問題是否已被記錄。如果播放是「全面」失敗、而不是特定曲目失敗，請改參考 下方的啟動或連線問題，而不要當成 Beta 版本的既知限制處理。

機器人無法啟動

不同原因會產生不同的訊息；請檢查主控台（或桌面提示訊息）看看你遇到的是哪一種。

"Invalid configuration. Check your token."——config.txt 中的 discord.token 遺漏、 格式錯誤，或被 Discord 拒絕。請從你 Discord 應用程式的 Bot 分頁重新產生一個 Token，完整貼上， 然後重新啟動。

"Invalid response from Discord. Check your internet connection."——這台機器無法連線到 Discord 的伺服器。請檢查對外連線，以及前面是否有任何防火牆或代理伺服器。

"Your bot is missing required Discord intents!"——機器人已連線，但 Discord 因為某個特權 Intent 未開啟而拒絕這次連線。這則訊息直接指出了修正方式：到你應用程式在 開發者後台的 Bot 設定頁面，開啟 Message Content Intent，然後重新啟動。這是每個機器人應用程式只需要做一次的設定步驟——見 Getting-Started-zh-TW。

"Another instance of NextVoiceCord is already running."——機器人在啟動時會對其工作目錄 取得一個獨占鎖定，避免兩份指向同一份設定檔的副本同時執行（否則每個指令都會被回應兩次）。如果你 看到這則訊息，代表有一個較早啟動的行程還存活著——請先確認它的狀態，再啟動另一個，或是等它完全 結束。這個鎖定會在行程結束時自動釋放，包含當機的情況，所以不需要手動清理。

jar 檔完全無法執行，並出現 class-file-version 錯誤。——這是 JVM 本身拒絕執行一個為比目前 執行環境更新版本 Java 所編譯的 jar 檔。NextVoiceCord 需要 Java 25 或更新版本；請檢查 java -version，若版本較舊則需要更新執行環境。（機器人自身的啟動檢查只會確認你使用的是 64 位元 JVM——它不會在 JVM 之前先攔截過舊版本的問題，所以這會顯示為啟動失敗，而不是機器人給出 的友善提示訊息。）

使用 --web 時，連接埠已被占用。——網頁面板連接埠綁定失敗會被記錄下來，但不會讓機器人的 其餘部分停止運作；音樂播放與桌面視窗（若有啟用）仍會正常啟動，只是不會有面板。請查看記錄檔中的 綁定錯誤，釋放該連接埠，或用 --web <port> 選擇另一個連接埠，然後重新啟動。

網頁面板無法連線

症狀： 已加上 --web <port>，機器人也已啟動，但瀏覽器無法載入面板。

依可能性排序的原因與處理方式：

• 綁定位址。 面板預設綁定 127.0.0.1——只有同一台機器能連線。若要讓網路上的其他裝置也能 連上，請在 config.txt 中設定 web.bindAddress = "0.0.0.0"。這麼做也代表面板現在可以被同一個 網路上的任何裝置連線，而且是透過明碼 HTTP 傳輸，任何能看到該流量的人都能看到 Token——請勿把這 個連接埠對外轉發到網際網路。
• Token。 面板使用單一個持有人權杖（bearer token）進行驗證，每次機器人重新啟動時都會重新 產生並印在主控台上。用先前執行時的舊 Token，或是重新啟動前收藏的網址，都不會有效——請以主控台 上目前顯示的那一組為準。
• 寫入請求缺少正確的標頭。 只是載入頁面的話，把 Token 放在網址中（?token=…）就能運作，但 任何會改變狀態的操作——儲存設定、變更設定、透過 API 控制播放——都只接受把 Token 放在 Authorization: Bearer <token> 標頭中，絕不接受放在查詢字串裡。這是刻意設計的：標頭無法像網址 那樣被其他網站上的頁面偽造。如果某個寫入操作回傳 401 Unauthorized，但頁面本身載入正常， 幾乎都是這個原因。
• 設定檔編輯被明確拒絕。 若 web.allowConfigEdit 這項設定關閉（預設就是關閉），設定檔的 寫入請求會回傳 403，並附上訊息 "Config editing is off. Set web.allowConfigEdit = true in config.txt."。 只有在你真的希望面板能改寫 config.txt 時才把它打開——不論如何，discord.token、 web.bindAddress，以及 web.allowConfigEdit 本身，都無法透過面板變更。
• 連續失敗被鎖定。 同一個位址連續使用錯誤的 Token，會被限速並回傳 429 Too many failed attempts。請等待限速解除，或重新啟動機器人讓舊 Token 失效並取得新的一組。

桌面視窗無法開啟

如果沒有可用的顯示器——例如無介面伺服器，或是透過 SSH 連線、沒有做 X 轉發的機器——桌面視窗就無法 開啟，行程會依環境不同而卡住或失敗。請改用 --nogui 執行，這會完全略過圖形介面，並將輸出記錄到 主控台。如果你仍然想要一個介面，只是改成瀏覽器介面而非桌面介面，可以搭配 --web <port> 一起使用。

指令沒有出現在 Discord 中

症狀： 在機器人已經加入的伺服器中，Discord 的斜線指令自動完成清單裡沒有出現 /play 等指令。

原因： 斜線指令是全域註冊的（不是逐伺服器註冊），而 Discord 把新註冊或變更過的全域指令推送到 各個 Discord 應用程式的速度並非即時——傳播到所有應用程式可能需要一段時間。機器人只有在指令集實際發生變化時才 會重新註冊（它會對整個指令集做雜湊比對，沒有變化就跳過對 Discord API 的呼叫），所以這個延遲通常 只會在第一次安裝機器人，或更新到變更了指令集的版本時才會出現。

該怎麼做： 耐心等待，並嘗試重新啟動你的 Discord 應用程式。如果等了合理的時間後指令仍未出現， 請查看主控台記錄中是否有斜線指令註冊錯誤，並確認邀請機器人時確實包含了 applications.commands 這個範圍（scope）——如果當初邀請時只給了 bot 範圍，那麼斜線指令根本無法為它註冊，必須重新邀請 並同時包含這兩個範圍。

文字語言錯誤，或部分是英文

症狀： 在一個設定為非英文的伺服器中，大部分回覆都以伺服器設定的語言顯示，但某一兩則訊息卻是 英文。

原因： 這在一般意義上並不算是臭蟲（bug）。在隨附的十二種語言中（DE、EN、ES、FR、JA、KO、PL、 RU、UA、VN、ZH-CN、ZH-TW），只有英文經過人工審閱——其餘十一種都是機器產生，且各自標記 _meta.reviewed: false。翻譯的回退機制是以每個字串鍵值為單位，而不是以整個檔案為單位：如果某個 特定字串尚未翻譯（或翻譯遺失、損壞），就只有這一個字串會回退成英文，周圍其他內容仍會維持在設定的 語言。而語言本身的判斷順序是先看個人設定，再看伺服器設定，最後才是全域預設——所以如果不同人各自 設定了個人語言覆寫，同一個指令在同一個頻道中，對不同人顯示不同語言，是完全合理的情況。

該怎麼做： 對這十一種未經審閱的語言來說，這是預期中的行為，不是設定錯誤——config.txt 裡 沒有任何東西需要修正。如果你剛好會其中一種語言，翻譯校對是這個專案目前最有價值的貢獻方式；翻譯檔 放在哪裡、CI 強制檢查哪些規則，請見 README 的 Translations 章節。

另請參閱

初次設定請見 Getting-Started-zh-TW。如果是版面渲染出空白內容，而不是整個機器人都出問題， 請見 Controller-Panel-zh-TW。如果指令能執行但被拒絕，那是權限問題，不是臭蟲，請見 Commands-zh-TW 與 Permissions-and-Server-Settings-zh-TW。