Xray 核心啟動失敗怎麼辦？排查連接埠占用、JSON 格式與欄位錯誤

一、先確認是啟動失敗，還是連線失敗

「網頁無法開啟」不代表「核心沒有啟動」。Xray 啟動時會讀取設定、建立入站與出站連線，並開啟監聽連接埠；這些步驟出錯，程序可能立即結束。核心已執行後發生的遠端連線逾時、驗證失敗或 TLS 交握錯誤，則屬於另一種排查方向。先分清問題發生的階段，才能避免反覆修改原本正確的節點參數。

v2rayN 是用戶端介面，Xray 則是實際處理連線的核心。介面仍在執行，不代表核心運作正常。不同版本的選單位置可能有所調整，以下以 Windows 桌面常見介面為例；若找不到同名項目，請依括號中的功能尋找，不要直接套用其他用戶端的選單位置。

1. 保留錯誤訊息

   展開主視窗下方的資訊或記錄區，記下本次啟動時間。複製從 Failed to start 開始的完整錯誤訊息，保留後續以 > 分隔的內容；最末一層通常比開頭的摘要更具體。

2. 確認核心

   開啟「設定」→「參數設定」→「Core 類型」，確認目前節點協定所選用的核心；部分版本會顯示「Core 類型設定」標籤。接著查看啟動記錄中的執行檔路徑，確認實際呼叫的是 Xray。

3. 重現一次

   暫時關閉 TUN，只保留一個 v2rayN 執行個體，選取原本的節點後重新啟動服務一次。不要連續切換節點，讓記錄訊息不斷刷出；同時保留重新啟動前後約 10 秒的記錄，以便判斷錯誤是否來自同一次啟動。

4. 記錄變更

   記下上次成功啟動後修改過的項目，例如本機連接埠、路由規則、自訂設定或核心檔案。先備份目前設定，每次只修改一個變數，測試後記錄結果。

二、連接埠占用：先找出監聽程序，再決定是否更改連接埠

如果錯誤訊息出現 failed to listen 或 address already in use，請優先檢查本機監聽連接埠，而非遠端節點的 443 連接埠。Windows 也可能顯示英文系統訊息 Only one usage of each socket address。常見原因包括舊核心尚未結束、重複開啟用戶端，或其他程式占用了相同位址與連接埠。

以下以 TCP 連接埠 10808 為查詢範例，並非所有 v2rayN 版本都使用這個預設值。請先在「設定」→「參數設定」→「基本設定」查看實際的本機監聽連接埠，再替換指令中的數字。若使用混合入站，一個連接埠可以同時接受多種代理協定，不必硬拆成兩個連接埠。

netstat -ano -p tcp | findstr ":10808"

powershell -NoProfile -Command "Get-NetTCPConnection -State Listen -LocalPort 10808 | Select-Object LocalAddress,LocalPort,OwningProcess"

• 在 netstat 輸出中，找出「本機位址」以 :10808 結尾且狀態為 LISTENING 的那一列，最後一欄就是 PID。只有 TIME_WAIT 並不能直接證明有監聽衝突。
• 假設查到的 PID 是 4260，執行 tasklist /FI "PID eq 4260" 查看程序名稱。此處的 PID 僅供示範，實際操作時請使用查到的值。
• 如果是另一個 v2rayN 啟動的核心，請先從對應用戶端的系統匣選單正常結束，再查詢一次。不要在未確認程序歸屬前，就結束所有同名程序。
• 如果連接埠屬於必須保留的程式，可將本機監聽連接埠改為未占用的 10818，儲存後重新啟動服務。手動設定代理的應用程式也必須同步修改連接埠。

若 Windows 查不到監聽程序，卻仍顯示拒絕存取通訊端，可執行 netsh interface ipv4 show excludedportrange protocol=tcp 查看 IPv4 TCP 排除範圍。若連接埠位於該範圍內，請優先選擇範圍外可用的連接埠，不要直接刪除系統保留項目。只有記錄明確指向 TUN 或權限問題時，才進一步調整對應權限。

三、JSON 格式：使用實際執行的核心進行離線測試

設定檔能用文字編輯器開啟，不代表 Xray 一定能讀取。缺少逗號、使用中文引號或括號未閉合，都會使解析中斷。語法錯誤通常會附上行號、字元位置，或 invalid character、unexpected EOF 等訊息；實際用語會依核心版本與載入方式而異。

在用戶端停止相關服務後，前往記錄中顯示的 Xray 程式目錄，使用該目錄中的執行檔測試已儲存的設定副本。以下為 Windows PowerShell 寫法；check.json 是本次要檢查的檔名。測試不會啟動代理監聽，但仍可能讀取設定引用的憑證、規則資料等本機檔案。

.\xray.exe version
.\xray.exe run -test -config .\check.json

行號通常指向「解析器發現問題」的位置，不一定是錯誤最初發生的地方。若第 24 行出現錯誤，請連同第 23 行一起檢查。不要將含有憑證的完整設定貼到線上格式化工具；使用本機編輯器的括號配對功能，搭配核心測試指令，通常就足以排查。

四、欄位錯誤：依層級檢查，別只看拼寫

JSON 語法正確後，還必須符合 Xray 的設定結構。inbounds、outbounds 是陣列；協定專屬參數應放在對應的 settings 中；傳輸與安全參數通常歸在 streamSettings。欄位放錯層級時，即使檔案仍是合法 JSON，也可能導致建立設定失敗，或設定無法生效。

不要將某種核心的設定片段直接貼進另一種設定格式。v2rayN 的節點編輯表單也不等於完整的 Xray JSON：用戶端會根據節點、路由與全域選項產生執行設定。尤其要分清 VLESS 與 VMess 的協定參數，不能因為兩者都使用使用者識別資訊，就互換整個 settings 區塊。

• 核對鍵名：streamSettings 中間的 S 要大寫；routing.rules 中用來引用出站標籤的欄位是 outboundTag。名稱大小寫請依所用核心的設定要求填寫。
• 核對標籤：規則中的 outboundTag 應與某個出站的 tag 相符。標籤寫錯可能影響規則匹配後的出站選擇，不能只憑測試通過就認定分流有效。
• 核對取值：protocol、傳輸類型與安全類型都應使用目前核心可識別的值。若將說明文字當成參數值，就會觸發未知協定或未知類型錯誤。
• 核對資源：若讀取 geoip.dat、geosite.dat 或憑證檔案失敗，請檢查資源目錄、檔名與權限。相對路徑會受實際工作目錄影響，從不同目錄執行可能得到不同結果。

另請留意：某些解析流程可能會忽略未知欄位，不一定都會回報錯誤。因此，「沒有錯誤」只代表通過目前的檢查，無法證明每個手動撰寫的欄位都已生效。調整路由後，應使用明確的目標網域確認出站選擇；不要以某個網頁能開啟取代完整驗證。

五、最小設定：區分環境問題與節點問題

完整設定內容很長時，可先將以下設定存成 check.json。它只會在本機 127.0.0.1:10818 提供 SOCKS 入站，並直接連線至目標；不包含遠端代理節點，也不能用來驗證訂閱是否可用。這份設定用於確認目前的 Xray 能否讀取設定、建立出站並開啟本機連接埠。

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-check",
      "listen": "127.0.0.1",
      "port": 10818,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

1. 先執行 .\xray.exe run -test -config .\check.json。若測試失敗，請保留輸出內容，優先檢查檔案內容與目前使用的核心，不要加入實際節點參數。
2. 測試通過後，執行 .\xray.exe run -config .\check.json。只有程序持續執行，且查得到 127.0.0.1:10818 正在監聽，才算通過繫結驗證。視窗暫時沒有新輸出，不代表程式沒有回應。
3. 按下 Ctrl+C 停止測試程序，再逐部分還原原始設定：先加入節點出站，再加入傳輸與安全設定，最後加入路由和規則資料。每還原一部分就測試一次。
4. 如果最小設定能啟動，加入某個部分後才失敗，排查範圍就縮小到新增的欄位或相依項目。不要在同一輪測試中同時更換節點、連接埠與核心。

六、版本相容性：確認實際執行的檔案

用戶端版本與核心版本是兩回事。只更新 v2rayN 主程式，不能據此認定 Xray 也已更新；手動覆蓋核心檔案，也不代表用戶端實際呼叫的就是該檔案。請以啟動記錄中的路徑和 xray.exe version 輸出為準，並記下處理器架構。

新增欄位、新傳輸類型或已調整的舊欄位，都可能受到核心版本影響。遇到這類情況，請先保留可正常啟動的版本與設定副本，再透過用戶端提供的更新功能或下載中心取得相容元件。不要為了勉強啟動而不斷刪除欄位，導致設定改變原本需要的連線行為。

• 設定不相容：程式可以執行，但出現設定錯誤時，請優先確認該版本支援的欄位與參數，並參考核心測試輸出定位問題，不要只靠發布日期猜測。
• 程式無法執行：若系統直接顯示無法執行或執行檔格式錯誤，請檢查 Windows 與處理器架構、下載內容是否完整，以及檔案是否遭安全軟體隔離。這時尚未進入 JSON 解析階段。
• 更新後回復舊版：先結束用戶端與殘留的核心程序，再還原完整備份。若新版用戶端仍會產生新格式設定，只換回舊核心可能還是無法啟動。
• Android 版本對照：v2rayNG 使用 Xray 核心，v2flyNG 使用 v2fly 核心。兩者的支援範圍不能互相替代，Windows 的程序查詢指令也不能直接套用在 Android 上。

七、啟動失敗常見問題