V2Ray 核心啟動失敗怎麼辦？看懂 Xray 日誌，排查 JSON 設定錯誤

本文摘要

適用於 v2rayN 顯示核心啟動失敗、v2rayNG 啟動後立即停止，以及修改自訂設定後無法載入的情況。先分辨是設定載入失敗，還是執行期間的連線問題，再根據日誌中的具體原因檢查 JSON、監聽連接埠、協定與路由欄位；每次只修正一個問題，最後分別透過設定測試與實際請求確認結果。

先判斷問題發生在哪個步驟

「網頁打不開」不代表「核心沒有啟動」。用戶端介面能開啟，也不表示背景核心已成功執行。啟動時必須先讀取設定、建立入站與出站，再建立本機監聽；完成這些步驟後，應用程式的請求才會進入路由比對。

讀取設定建立欄位監聽連接埠路由請求連線至遠端

啟動後立即退出：優先搜尋 Failed to start、failed to load、failed to listen 等字樣，檢查本機設定與監聽條件。
啟動後出現請求日誌：通常表示已進入執行階段。若此時出現遠端逾時、憑證錯誤或連線遭拒，應改查節點位址、傳輸參數與網路連線狀況。
完全沒有日誌：先確認是否開啟核心日誌，而非只查看訂閱更新日誌。也要確認用戶端是否確實執行核心程式，以及日誌輸出位置是否可寫入。

v2rayN 是桌面用戶端，可用欄位取決於目前選用的核心。v2rayNG 使用 Xray，v2flyNG 使用 V2Fly；兩者設定雖有部分相同，但不代表所有擴充欄位都能互通。排查紀錄應同時列出用戶端與核心版本，不要只寫「最新版」。

保留一份完整的啟動日誌

先停止重複點擊連線，備份目前設定，再清空日誌顯示區或記下時間。只啟動一次，保留從核心版本資訊到退出訊息的所有內容。v2rayNG 可從側邊欄開啟「日誌」；v2rayN 請查看主視窗的資訊輸出區。實際入口與版面會隨版本不同，請以核心啟動資訊為準。

loglevel	主要用途	閱讀重點
`error`	收集錯誤	保留導致載入或連線失敗的原因
`warning`	查看警告與錯誤	確認警告是否與此次退出直接相關
`info`	補充執行資訊	啟動過程與請求處理的相關資訊
`debug`	暫時深入排查	更詳細的內部處理線索
`none`	關閉此類日誌	排查期間不建議使用

自訂 JSON 可暫時將 log.loglevel 設為 debug。這只會增加日誌詳細程度，無法修正錯誤；若 JSON 根本無法解析，這項設定也可能尚未生效，仍須查看程序輸出或用戶端擷取的標準錯誤。

{
  "log": {
    "loglevel": "debug"
  }
}

日誌中的時間戳記與連線編號可用來比對同一次操作；含有多個 > 的錯誤通常是逐層包裝的錯誤鏈。先找出第一條與此次啟動有關的錯誤，再讀到錯誤鏈末端的具體原因。不要只截取最外層的 Failed to start，也不要混入先前其他請求的逾時紀錄。

JSON 語法錯誤：先修正結構，再檢查欄位

JSON 解析失敗時，協定、DNS 與路由通常尚未進入有效的建立階段。常見原因包括末尾多了逗號、漏加雙引號、複製時混入中文引號，或將數字欄位寫成字串。錯誤位置有時會出現在問題之後：解析器讀到下一個字元時，才發現前面的結構不完整。

錯誤：`invalid character '}' looking for beginning of object key string`

原因：物件結尾前仍預期有欄位名稱，常見情況是在最後一個欄位後多加了逗號。

解決方法：檢查右大括號前一行，刪除多餘的結尾逗號，並確認物件中的鍵名使用英文雙引號。

錯誤：`unexpected EOF`

原因：輸入內容提前結束，可能少了閉合括號或引號，也可能是儲存時檔案遭截斷。

解決方法：從最後一次編輯的位置開始，往外檢查括號與引號是否成對；若檔案明顯不完整，先還原備份，再逐段重新修改。

錯誤：`cannot unmarshal string into Go struct field`

原因：欄位資料型別與核心預期不符；後續日誌通常會指出欄位路徑與預期型別。

解決方法：依完整路徑檢查資料型別，例如本機入站連接埠應寫成 "port": 10808，不要寫成帶引號的數字字串。

此處列出的是常見錯誤片段，完整前綴、大小寫與欄位路徑會因核心版本而異。修正時不要只做全域取代：連接埠欄位需要數字，不代表所有含數字的內容都要移除引號；UUID、位址與標籤仍是字串。

使用支援 JSON 檢查的本機編輯器，開啟實際載入的檔案。
先修正編輯器指出的第一個語法錯誤，重新檢查後再處理下一個。
標準 JSON 不允許尾隨逗號或註解。即使某些載入器接受擴充語法，排查時仍建議優先使用標準 JSON。
若透過用戶端表單產生設定，請回到對應的設定項目修改；直接編輯暫存產生的檔案，可能會在下次啟動時被覆寫。

連接埠遭占用：找出占用程序，不要盲目提升權限

入站建立失敗，常見原因是兩個用戶端同時監聽相同的位址與連接埠，或上次啟動留下的程序尚未結束。下列連接埠僅為本文示範值，不代表所有用戶端的預設值。請先從日誌或目前設定確認實際連接埠，再替換命令中的數字。

10808

SOCKS 入站示範連接埠

10809

獨立 HTTP 入站示範連接埠

隔離排查時保留的用戶端執行個體

錯誤：`address already in use`

原因：目標監聽位址與連接埠已遭占用，或與現有監聽範圍衝突。

解決方法：確認是哪個程序正在監聽，正常關閉重複執行的執行個體；若必須同時執行，請為入站設定不同的連接埠，並同步調整應用程式的代理設定。

錯誤：`Only one usage of each socket address`

原因：Windows 通訊端繫結衝突，完整錯誤通常也會列出本機位址與連接埠。

解決方法：依日誌中的連接埠查找監聽 PID，不要把以系統管理員身分執行當成通用的連接埠衝突解法。

Windows：檢查監聽 PID

Get-NetTCPConnection -LocalPort 10808 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

在 PowerShell 執行命令後，使用工作管理員「詳細資料」中的 PID 比對程序。確認程序歸屬後再關閉；不要依連接埠批次結束不明的系統程序。若查不到任何監聽結果，請檢查完整日誌，確認回報的是否為權限或位址無法使用，而非連接埠遭占用。

Linux 與 macOS：查看監聽程序

# Linux
ss -ltnp 'sport = :10808'

# macOS
lsof -nP -iTCP:10808 -sTCP:LISTEN

一般使用者可能無法查看其他使用者程序的完整資訊。必要時只對查詢命令提升權限，不要長期以高權限執行整個用戶端。若本機連接埠從 10808 改為 10810，瀏覽器、系統代理或其他手動設定的應用程式也須同步更新。

協定與欄位錯誤：確認實際使用的核心

JSON 格式正確，只代表檔案可以解析，不代表核心能理解其中的協定。protocol 值必須拼寫正確，例如 vmess、vless、socks、freedom。入站與出站的 settings 結構不同，不能直接將伺服器接收使用者的欄位貼到用戶端出站設定中。

先確認版本：記錄啟動日誌中的 Xray 或 V2Fly 名稱與版本。用戶端介面版本和核心版本是兩項獨立資訊。
再確認設定方向：出站設定遠端伺服器，入站設定本機監聽。同名協定在兩端使用的欄位也不一定相同。
最後確認擴充功能：傳輸層、安全層與協定擴充各有支援範圍；將設定交給另一個核心前，須逐項確認，不要只改程式名稱。

「未知協定」不一定會以單一錯誤行呈現，也可能包含在入站或出站載入失敗的訊息中。沿著錯誤鏈找出具體的 protocol 值，再與實際設定比對。即使陌生欄位沒有引發錯誤，也不能據此認定它已生效：部分未知 JSON 欄位可能會被忽略，必須參考目前核心的文件並實際驗證。

路由錯誤：檢查條件與出站標籤

路由規則會將已進入核心的連線交給特定出站。routing.rules 依序比對；範圍較廣的規則若放在前面，可能會遮蔽後續更具體的規則。這類設定即使能啟動，也可能造成「全部直連」或「特定網域走錯出口」；應與導致啟動失敗的結構問題分開排查。

錯誤：`this rule has no effective fields`

原因：規則沒有有效的比對條件，例如只留下 type 和 outboundTag。

解決方法：補上明確的 domain、ip、port 或 network 等條件，或刪除不需要的空規則。

以下是用於隔離測試的精簡完整設定：僅在本機 127.0.0.1:10808 提供 SOCKS 入站，將 example.com 及其子網域交由封鎖出站處理，其餘流量則使用第一個直連出站。此設定不包含遠端代理節點，不應取代正式的節點設定。

{
  "log": {
    "loglevel": "info"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "blocked"
      }
    ]
  }
}

逐字比對 outboundTag 與 outbounds[].tag，包括大小寫。標籤不存在時，依版本與處理路徑不同，呈現結果可能也不同，不能只憑成功啟動就認定設定正確。
網域與 IP 比對條件使用陣列；單一規則中的不同條件通常必須同時符合。不要把「增加條件」誤當成「新增任一條件都可符合」。
若錯誤直接指向 geosite.dat 或 geoip.dat，請檢查目前核心的資源目錄、檔案是否可讀，以及規則引用的分類是否存在。
若要隔離資源問題，可暫時以明確的網域規則取代上述資源分類；確認通過後，再逐條恢復原有規則。

修正後分兩階段驗收

第一階段只確認核心能否接受設定。使用 Xray 命令列時，可在設定檔所在目錄執行下列測試命令；執行檔必須與用戶端實際使用的版本相同。Windows 可將命令開頭的 xray 改為 .\xray.exe。

xray run -test -config ./config.json

設定測試成功，不代表連接埠一定能成功繫結，也不代表能連上遠端伺服器。第二階段必須實際啟動用戶端，確認沒有新的監聽錯誤，再讓應用程式透過正確的本機代理連接埠發出請求。示範設定刻意封鎖了 example.com，因此不能以該網域作為「應可成功存取」的驗收目標。

JSON 檢查通過了，為什麼還是啟動失敗？

JSON 檢查只涵蓋語法。請繼續查看核心輸出，分辨是協定建立失敗、資源檔讀取失敗，還是連接埠繫結失敗。先執行設定測試，再實際啟動，並分別記錄兩個步驟的結果。

每次修改檔案，重新連線後又恢復原狀？

你可能修改了由用戶端自動產生的執行設定。請先備份，再回到節點編輯、路由設定或自訂設定入口修改來源資料，然後重新啟動，確認新產生的檔案及日誌中的讀取路徑。

核心已經啟動，但日誌一直出現逾時，該怎麼辦？

先確認應用程式確實連入本機入站，再檢查遠端位址、連接埠、TLS 服務名稱與傳輸路徑。執行期間的遠端逾時不是 JSON 語法錯誤，不必反覆刪除整份設定。

重新安裝用戶端能解決連接埠遭占用的問題嗎？

重新安裝不會自動釋放其他程式正在監聽的連接埠。先查詢 10808 等實際衝突連接埠對應的 PID，關閉重複執行的執行個體或更換連接埠，再同步更新應用程式的代理設定。

可重現的排錯紀錄應包含操作時間、用戶端與核心版本、讀取的設定路徑、第一條錯誤日誌、此次修改的欄位，以及重新測試的結果。每次只變更一個項目，才能避免修好連接埠問題時又同時引入路由錯誤。若要進一步了解欄位層級，可參考設定參考逐段檢查。