V2Ray 設定檔完整參考

JSON 結構總覽：先確認物件層級與處理鏈

頂層物件的用途

V2Ray 設定檔是一個 JSON 物件。常見的頂層欄位包括 log、dns、inbounds、outbounds、routing、policy 和 stats。這些欄位並不是依照檔案中的書寫順序逐一執行，而是在核心啟動時分別解析為對應模組。把 routing 寫在 inbounds 前面，不會改變實際處理順序；真正決定流量去向的是入站標籤、路由條件、出站標籤，以及模組之間的引用關係。閱讀設定時，應先找出所有 tag，再沿著引用關係檢查，而不是只按第一行到最後一行的順序閱讀。

inbounds 與 outbounds 都是陣列，因為同一個核心可以同時監聽多個本機連接埠，也可以準備多個出口。routing.rules 同樣是陣列，規則通常由上而下比對。不同的是，dns、log 和 policy 一般是物件，分別描述一組解析行為、日誌行為與工作階段策略。欄位的資料型別必須正確：陣列使用方括號，物件使用大括號，布林值寫成 true 或 false，不能寫成帶引號的字串。

如何建立最小結構

以下骨架包含一個 SOCKS 入站、一個直接連線出站和一條基本路由規則，適合用來理解層級，不代表完整的遠端伺服器設定。SOCKS 請求進入本機監聽連接埠後，路由模組會檢查目標位址；符合私有位址規則時，交由 direct 出站處理。未符合規則的流量也會使用可用的預設出站，因此正式環境通常還會明確準備主要代理出口，並透過規則區分直接連線、代理和封鎖三種結果。

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

語法錯誤與語意錯誤要分開處理

語法錯誤發生在核心尚無法理解檔案時，常見原因包括尾隨逗號、缺少引號、括號不成對，或把註解寫入標準 JSON。JSON 本身不接受 // 和 /* */ 註解；如果用戶端介面允許註解，通常是用戶端在儲存前進行了額外轉換，不能據此判斷核心直接讀取的檔案也支援相同寫法。語意錯誤則是 JSON 可以解析，但欄位組合不成立，例如路由規則引用不存在的 outboundTag、連接埠寫成字串，或協定名稱與 settings 結構不相符。

用戶端產生設定時，還會加入執行目錄、資源檔案位置和核心差異相關欄位。v2rayN 適合管理 Windows、macOS 與 Linux 桌面設定，v2rayNG 和 v2flyNG 則分別用於 Android 環境中的不同核心路線。圖形用戶端中的訂閱項目不等於最終執行設定：用戶端通常會合併節點參數、本機監聽設定、路由規則與 DNS 選項後，再交給核心。因此，故障排查時應優先查看用戶端實際產生或匯出的執行設定，不能只檢查訂閱連結中的單一節點參數。

tag 是模組之間的連接點

tag 可以理解為設定內部的穩定名稱。入站標籤供路由規則的 inboundTag 引用，出站標籤供 outboundTag 與 balancerTag 引用，DNS 伺服器也可以透過標籤與特定出站建立關係。標籤區分大小寫，改名後必須同步修改所有引用位置。建議使用含義清楚的短名稱，例如 socks-in、proxy、direct、block，不要直接把伺服器位址或經常變動的備註當作標籤。

排查整份設定時，可以畫出一條簡單鏈路：應用程式連線到哪個本機連接埠，該連接埠屬於哪個入站標籤，路由規則根據哪些網域、IP、連接埠或協定進行比對，符合後轉到哪個出站標籤，以及出站使用哪種協定與傳輸方式。只要鏈路中的每個引用都能對應到實際物件，多數結構問題都能被發現。後續章節會沿著這條鏈路拆解說明各個模組。

inbounds 入站：定義本機流量如何進入核心

監聽位址、連接埠與協定

入站負責接收來自瀏覽器、系統代理、區域網路裝置或其他程式的連線。一個入站物件通常至少包含 tag、listen、port、protocol 和 settings。listen 決定綁定到哪個網路介面。桌面用戶端僅供本機使用時，優先監聽 127.0.0.1，如此區域網路中的其他裝置就無法直接存取該連接埠。確實需要分享給區域網路時，才考慮監聽所有介面，並同時檢查系統防火牆、存取控制與 SOCKS 驗證設定。

port 是整數，必須避免與其他程式重複。v2rayN 常見的本機 SOCKS 與 HTTP 連接埠由用戶端設定產生，手動設定時不應假設某個連接埠一定閒置。核心提示位址已被使用時，應先確認是否仍有另一個用戶端執行個體正在執行，再決定關閉衝突程式或修改監聽連接埠。相關定位步驟可參閱v2rayN 連接埠被佔用導致啟動失敗的故障排查。

protocol 決定入站協定結構。本機常見選擇是 socks 與 http。SOCKS 入站適合支援 SOCKS5 的程式，並可依設定轉送 UDP；HTTP 入站適合使用 HTTP 代理設定的應用程式。透明代理、連接埠轉送等情境涉及系統網路堆疊與額外權限，不應在基本設定中隨意啟用。先讓明確設定代理位址的應用程式成功連線，再逐步擴大接管範圍，故障排查路徑會更清楚。

同時提供 SOCKS 與 HTTP 入站

{
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      }
    },
    {
      "tag": "http-in",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

兩個入站必須使用不同連接埠。應用程式選擇 SOCKS5 時填寫 127.0.0.1:10808，選擇 HTTP 代理時填寫 127.0.0.1:10809。如果作業系統只允許填寫一個代理連接埠，應依用戶端的系統代理模式使用其產生的值，不要把 SOCKS 連接埠誤填到只接受 HTTP 代理的輸入框。連接埠能建立 TCP 連線，只能表示本機監聽存在，不能證明遠端出站、DNS 與路由全部正確。

流量嗅探的用途與界線

sniffing.enabled 啟用後，核心可以從部分連線的應用層資訊中還原目標網域。destOverride 中常見的 http 與 tls 表示允許使用 HTTP Host 或 TLS 交握中的伺服器名稱覆寫原始目標。這有助於網域路由：即使應用程式先解析出 IP，路由模組仍可能取得網域並比對 geosite 或完整網域規則。

嗅探不是解密網頁內容，也不是所有連線都能還原網域。沒有可辨識主機資訊的協定仍會保留原始目標；某些應用程式對目標位址變更十分敏感，啟用覆寫後可能出現與預期不同的連線行為。排查單一應用程式異常時，可以暫時關閉嗅探進行比較。如果關閉後恢復正常，應檢查網域規則、DNS 結果和 destOverride 範圍，而不是直接認定出站協定有問題。

UDP、驗證與區域網路存取

SOCKS 入站的 udp 決定是否接受 UDP 轉送請求。啟用此欄位不代表所有出站傳輸都自動支援目標 UDP，也不代表應用程式一定會透過 SOCKS 傳送 UDP。需要同時確認應用程式行為、出站協定能力與路由規則。DNS 查詢若交由核心內建 DNS 處理，其路徑又與應用程式直接向外傳送 UDP 查詢不同，應分別判斷。

監聽範圍擴大到區域網路後，不宜再把存取控制視為預設的本機環境。SOCKS 可透過 auth 和帳戶清單建立使用者名稱與密碼驗證，但不同用戶端對這些欄位的圖形介面支援程度不同。較穩妥的做法是只開放確實需要的介面和防火牆來源位址，並確認行動裝置不會把該連接埠暴露在不受信任的網路中。若只在本機使用，維持回環位址監聽最簡單，也能減少誤開放連接埠的風險。

依入站來源進行路由

多個入站不僅用於配合不同代理協定，也可以作為分流入口。例如為日常應用程式建立 main-in，為需要直接連線的程式建立 direct-in，再在路由規則中使用 inboundTag 加以區分。這種方式比頻繁修改全域模式更明確，但要求應用程式能分別指定代理連接埠。設計此類結構時，應把連接埠用途記錄在設定旁，並確保用戶端重新產生設定時不會覆蓋標籤。

入站故障排查可分四層檢查：程序是否成功繫結連接埠，應用程式是否使用正確的代理類型，入站是否接受對應的 TCP 或 UDP 請求，以及嗅探與路由是否改變目標。只有前一層成立後，才檢查下一層。瀏覽器提示代理伺服器沒有回應時，先查看監聽與連接埠；核心日誌已出現連線記錄但無法存取目標時，再轉到出站、路由和 DNS 章節。

outbounds 出站：定義代理、直連與封鎖出口

預設出站與標籤引用

出站物件描述核心如何把連線傳送到下一跳或最終目標。常見設定至少準備三個邏輯出口：主要代理出口、直接連線出口和封鎖出口。代理出口可以使用 VLESS、VMess、Trojan 等協定，具體參數來自伺服器設定；直接連線通常使用 freedom；封鎖通常使用 blackhole。三者分別設定清楚的 tag，再由路由規則透過 outboundTag 選擇。

當路由規則沒有符合時，核心會使用預設出站。不同核心及設定組織方式對預設項目的處理細節可能有所差異，因此不應依賴模糊的陣列位置完成關鍵分流。較易維護的做法是確保一般流量有明確規則，私有位址、需要直接連線的網域和封鎖目標也分別指向確定的標籤。查看用戶端產生的設定時，還要留意用戶端是否插入額外的 DNS 出站或迴圈出站。

VLESS 用戶端出站結構

以下範例展示 VLESS 出站的基本層級。伺服器位址使用範例網域，使用者識別碼僅用於展示格式，不能直接用於實際連線。settings.vnext 是伺服器陣列，每個伺服器物件包含位址、連接埠與使用者清單。使用者物件中的 id 必須與伺服器設定一致，VLESS 常見的 encryption 值為 none。傳輸方式、TLS 與伺服器名稱位於 streamSettings，不能誤放進使用者物件。

{
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "edge.example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-1111-4111-8111-111111111111",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls",
        "tlsSettings": {
          "serverName": "edge.example.com",
          "allowInsecure": false
        }
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ]
}

address 是核心實際連線的伺服器位址，serverName 是 TLS 交握使用的名稱，兩者可以相同，也可能因部署結構而不同。不能為了「看起來一致」就擅自把它們改成相同值。連接埠、傳輸類型、安全層、伺服器名稱及其他擴充參數必須與伺服器端整體對應；其中任何一項不相符，都可能表現為連線建立後立即關閉、TLS 交握失敗或長時間等待。

freedom 與 blackhole 的實際作用

freedom 讓核心從本機網路直接存取目標。它不是繞過核心：流量仍會先經過入站和路由，只是在出站階段不再傳送給遠端代理伺服器。私有位址、本機開發服務、區域網路裝置，以及明確要求本地出口的網站，通常交給此出站。若系統本身無法解析或存取目標，交給 freedom 也不會自動修復本機網路問題。

blackhole 用於丟棄被規則命中的連線，可用來封鎖明確不需要的網域、IP 或協定。它與「沒有符合任何出站」不同：前者是有意選擇封鎖出口，後者通常屬於設定引用錯誤。故障排查時可透過日誌中的路由結果加以區分。封鎖規則宜保持具體，過於寬泛的網域後綴或 IP 範圍，會同時影響合法子網域和共用位址上的其他服務。

多伺服器與負載策略

將多個伺服器直接放進同一個出站物件，並不等於自動取得符合預期的切換策略。需要多個出口時，通常會為每個出口建立獨立標籤，再透過路由的負載平衡器或用戶端提供的選擇機制管理。如此可以個別測試每個伺服器，也能清楚看出哪條規則選中了哪個出口。圖形用戶端可能依目前選取的節點動態產生 proxy 出站，因此手動新增的並行出站，可能在下次套用設定時被重建。

訂閱是節點參數的來源，不應與執行設定混為同一層。訂閱更新後節點消失或欄位解析失敗時，應先檢查訂閱格式與用戶端相容性，可參考訂閱失效與解析失敗故障排查。如果節點可以匯入，但只有某個出口無法連線，則應比較位址、連接埠、使用者識別碼、傳輸層與安全層，而不是反覆更新整份訂閱。

出站故障排查的分層方法

首先確認路由確實選擇了目標出站標籤；其次確認伺服器位址能夠解析，且本機網路可以連到對應連接埠；接著檢查協定驗證欄位；最後核對 streamSettings。如果一開始就同時替換節點、關閉 DNS、修改路由模式並調整 TLS，得到的結果無法說明哪項修改有效。保留一個已知可運作的直接連線出站也很重要，這能協助判斷問題是在核心整體啟動、路由選擇，還是單一代理出口。

streamSettings：傳輸方式與安全層必須成組匹配

協定層、傳輸層與安全層的差異

出站的 protocol 描述 VLESS、VMess 或 Trojan 等代理協定，streamSettings.network 描述承載連線的傳輸方式，streamSettings.security 描述 TLS、REALITY 或不啟用額外安全層等選擇。三個層次各自解決不同問題，但實際連線時必須與伺服器端逐項一致。只知道「使用 VLESS」不足以建立連線，還需要知道 TCP、WebSocket、gRPC 等傳輸方式，以及相應的伺服器名稱、路徑、服務名稱或安全參數。

用戶端匯入分享連結或訂閱後，會把這些參數轉換為核心可識別的欄位。不同核心家族對部分欄位名稱、可選值和擴充能力並不完全一致。v2rayNG 常用 Xray 核心，v2flyNG 使用 v2fly 核心路線；v2rayN 可以管理桌面端核心與節點設定。跨用戶端移轉時，應依目標用戶端實際使用的核心能力檢查，不要只複製一段內部 JSON，就假設所有欄位都能被相同方式解析。

TCP 與 TLS 範例

一般 TCP 傳輸通常將 network 設為 tcp。啟用 TLS 時，security 寫為 tls，並提供 tlsSettings。serverName 會參與憑證名稱檢查與交握，應使用伺服器端提供的值。allowInsecure 設為 false 表示執行正常的憑證驗證；改為 true 只會略過部分驗證，不能修復錯誤連接埠、錯誤協定或伺服器未啟動等問題，也不應作為長期使用的常規排錯方案。

{
  "streamSettings": {
    "network": "tcp",
    "security": "tls",
    "tlsSettings": {
      "serverName": "edge.example.com",
      "allowInsecure": false,
      "alpn": ["h2", "http/1.1"]
    }
  }
}

alpn 用於協商應用層協定。是否需要填寫以及值的順序，應與伺服器端部署保持一致。並非欄位越多越完整；伺服器端未要求時，讓用戶端自動協商通常更合適。連線失敗時也不應隨意輪換所有 ALPN 值，因為交握結果還會受到連接埠、伺服器名稱、中間代理和伺服器端憑證設定影響。

WebSocket 的路徑與請求標頭

WebSocket 傳輸會使用 wsSettings，其中常見欄位是 path。路徑必須與伺服器端完全相符，包括開頭的斜線和可能存在的查詢字串。某些部署還要求特定的 Host 請求標頭，具體欄位結構取決於核心的支援方式。移轉設定時，最常見的問題是只複製伺服器位址和連接埠，卻遺漏路徑或主機名稱，結果表現為 TLS 可以連線，但接著收到一般網頁回應或連線被關閉。

{
  "streamSettings": {
    "network": "ws",
    "security": "tls",
    "tlsSettings": {
      "serverName": "edge.example.com",
      "allowInsecure": false
    },
    "wsSettings": {
      "path": "/vless-connect",
      "headers": {
        "Host": "edge.example.com"
      }
    }
  }
}

位址、TLS 伺服器名稱與 HTTP Host 可能指向同一個網域，也可能分別負責連線目標、憑證驗證和反向代理分流。只有在明確了解伺服器端結構時才能調整。路徑中的大小寫通常具有意義，結尾斜線也可能導致不同的路由結果。若用戶端介面把這些欄位拆成「位址」「偽裝網域」「路徑」等輸入項，應以匯出後的實際 JSON 為準，確認欄位對應。

gRPC 與服務名稱

gRPC 傳輸通常使用 grpcSettings，關鍵欄位是 serviceName。它不是一般網頁路徑，不應機械式地加上斜線。不同部署還可能涉及多路複用相關選項，但基本故障排查仍應從服務名稱、TLS 伺服器名稱和連接埠開始。若伺服器端使用 gRPC，而用戶端選擇 WebSocket，即使雙方都啟用 TLS，也不會因為憑證正確就自動相容。

{
  "streamSettings": {
    "network": "grpc",
    "security": "tls",
    "tlsSettings": {
      "serverName": "edge.example.com",
      "allowInsecure": false
    },
    "grpcSettings": {
      "serviceName": "vless-grpc"
    }
  }
}

REALITY 設定的核對順序

REALITY 屬於安全層能力，常與 VLESS 搭配，但它不是 VLESS 的同義詞。用戶端參數通常涉及伺服器名稱、公鑰、短識別碼和指紋等內容，具體欄位以目標核心支援為準。核對時先確認目前核心是否支援此安全層，再檢查位址與連接埠，接著逐項比較伺服器名稱、公鑰、短識別碼和傳輸方式。把 TLS 設定區塊與 REALITY 設定區塊同時混入同一個出站，通常表示匯入或手動合併過程出了問題。

傳輸層故障排查應避免「逐一猜值」。正確做法是從同一份可靠的伺服器端參數重新比對，確認協定、網路類型、安全類型三個入口欄位，再進入對應的設定物件。日誌中若出現憑證名稱、交握、服務路徑或協定回應相關錯誤，才沿著相應分支繼續檢查。若日誌只顯示逾時，還要先排除 DNS 解析、目標連接埠無法連通和路由選錯出口。

多路複用與效能參數

部分設定支援在出站上啟用多路複用，讓多個邏輯連線共用底層連線。這可能減少重複交握，也可能因伺服器端支援、長連線特徵或應用程式流量類型而產生相反效果。沒有明確問題時，應先使用用戶端預設值。遇到單一連線正常但並行存取異常、長時間執行後卡住等情況，可以在其他欄位不變的前提下關閉多路複用進行比較。效能參數應建立在連線正確的基礎上，不能用來掩蓋協定或傳輸層不相符。

routing 路由規則：依序比對並選擇出口

路由只決定出口，不會建立連線能力

routing 模組會根據目標網域、目標 IP、連接埠、來源入站、網路類型或協定等條件，把連線交給指定出站。它不會改變出站本身的協定參數，也不會讓無法使用的伺服器恢復連線。某個網域存取失敗而其他網域正常時，路由和 DNS 是檢查重點；所有流量都無法透過同一個代理出口時，應先確認出站的連線能力。

rules 陣列通常由上到下檢查，最先符合的規則會先決定結果。因此，具體規則應放在寬泛規則之前。例如某個完整網域需要走代理，而其所屬的整個網域後綴設定為直連時，完整網域規則應位於後綴規則之前。規則數量較多時，可依「封鎖、私有位址、特殊代理、特殊直連、地域分類、兜底」分組維護，並為每組保留清楚說明。

domain、ip 與 port 的寫法

網域條件可以使用精確網域、後綴、關鍵字、正規表示式以及 geosite 分類。不同比對形式的前綴和含義不同，不能把一般字串理解為精確比對。IP 條件可以填寫單一位址、CIDR 網段或 geoip 分類。連接埠既可以是單一數字，也可以是範圍字串。一條規則中同時填寫多種條件類型時，通常需要所有類型共同符合；同一類型陣列中的多個值則用於比對其中任一個。

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "domain": ["full:updates.example.com"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "domain": ["domain:example.net", "geosite:cn"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["geoip:private", "geoip:cn"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

full: 適合只比對一個完整主機名稱，domain: 通常涵蓋該網域及其子網域。geosite: 依賴核心能找到對應的地理分類資源檔案；geoip: 同樣依賴 IP 資料資源。資源檔案缺失、路徑錯誤或用戶端更新後未正確載入時，相關規則會在啟動階段報錯，或無法依預期運作。首頁視覺中的「更新 geosite 資料」是一項實際的維護操作，但執行頻率應由用戶端更新機制和規則需求決定。

domainStrategy 如何影響網域與 IP 規則

domainStrategy 決定路由階段是否為了比對 IP 規則而解析網域。AsIs 傾向保留請求中的網域，不主動為 IP 規則進行解析；IPIfNonMatch 通常在網域規則沒有符合時才解析 IP，並嘗試比對 IP 規則；IPOnDemand 會更早觸發與 IP 規則相關的解析。具體行為仍須結合核心實作與 DNS 設定理解。

選擇策略時，應先釐清規則主體。如果主要依靠 geosite 和明確的網域清單，避免不必要的解析可以降低路徑複雜度；如果大量依賴 geoip，就需要讓網域取得可用於路由判斷的 IP。解析結果來自哪裡同樣重要：系統 DNS、核心內建 DNS 和遠端解析可能產生不同結果，進而改變 IP 分類的命中。因此，調整 domainStrategy 後，應同時觀察 DNS 日誌和路由結果。

依入站、網路與協定分流

inboundTag 可限制規則只處理來自特定入口的流量。例如單獨建立直連入口後，可以把該入口的所有流量導向 direct。network 可區分 TCP 與 UDP，適用於某個出站不處理特定網路類型的情況。部分核心還支援辨識特定應用層協定，但前提是流量嗅探能取得足夠資訊。依賴協定辨識的規則應作為輔助，不應取代明確的網域或連接埠條件。

{
  "type": "field",
  "inboundTag": ["direct-in"],
  "network": "tcp,udp",
  "outboundTag": "direct"
}

規則衝突與優先順序檢查

最常見的路由衝突是規則本身都合法，但寬泛規則提早符合，導致後面的具體規則永遠沒有機會執行。檢查時從目標連線開始，記錄它的網域、解析 IP、連接埠、網路類型和入站標籤，再從第一條規則逐條判斷。不要只搜尋預期規則是否存在，也要檢查它前面是否已有可能符合的規則。可參閱自訂路由規則與比對優先順序詳解，了解 domain、ip 與 geosite 的組織方法。

另一個常見問題是規則引用了錯誤標籤。用戶端切換節點後可能重新產生主要出站標籤，手動規則若引用舊標籤，就會失效或導致啟動錯誤。穩定的做法是使用用戶端保留的邏輯標籤，而不是節點備註。若用戶端提供「略過區域網路位址」選項，應確認它產生的是私有位址直連規則，並位於合適的優先順序，而不是再手動新增一組彼此重疊的規則。

兜底規則與可維護性

一條只指定網路類型並導向主要出口的規則，常被用作兜底。它應放在陣列末尾，因為會符合大多數連線。規則前段保留封鎖、私有位址和特殊分流，最後再處理其餘流量，行為最容易預測。若完全依賴預設出站而不寫兜底，設定仍可能運作，但讀者需要額外推斷陣列位置與核心行為，不利於長期維護。

大型規則集不宜把每個網域都零散放在主要設定中。可以使用用戶端支援的規則集管理方式，但最終仍要確認產生後的 JSON 是否引用正確資源。更新規則資料後若連線行為突然改變，應比較分類內容、資源載入日誌和規則順序，而不是先修改伺服器節點。路由是一套確定的比對系統，故障排查重點是找出實際符合的是哪條規則。

DNS 設定：控制解析來源、網域比對與結果範圍

核心 DNS 與系統 DNS 的關係

dns 模組為核心內部需要解析的網域提供伺服器和比對規則，但不保證作業系統中的所有 DNS 請求都會自動進入核心。應用程式是否直接呼叫系統解析、是否把網域交給 SOCKS、是否傳送獨立 DNS 封包，會決定實際路徑。看到設定中存在 dns.servers，不能直接推斷瀏覽器每次解析都使用這些伺服器。故障排查時要區分「核心為出站伺服器位址進行解析」「路由為目標網域進行解析」和「應用程式自行完成解析」三種情況。

核心 DNS 的價值在於讓解析選擇與路由規則協同運作。例如將特定網域交給指定解析伺服器，再把結果用於 IP 路由；或為某組網域設定預期的 IP 範圍，避免接受不符合條件的回應。完整方案需要同時考慮 DNS 查詢本身經由哪個出站、解析結果用於哪個步驟，以及應用程式最終連線時是否仍保留網域。

servers 陣列與條件式伺服器

servers 中既可以寫簡單的伺服器位址，也可以寫帶有比對條件的物件。物件形式可透過 domains 指定適用網域，並透過 expectIPs 限制可接受結果的範圍。以下範例把特定分類交給一個本地網路可存取的解析位址，其他網域則交給另一個解析伺服器。範例位址僅用於說明結構，實際部署應選擇目前網路與出站路徑確實能存取的解析服務。

{
  "dns": {
    "hosts": {
      "router.internal.example": "192.168.1.1"
    },
    "servers": [
      {
        "address": "223.5.5.5",
        "domains": ["geosite:cn"],
        "expectIPs": ["geoip:cn"]
      },
      {
        "address": "1.1.1.1",
        "domains": ["geosite:geolocation-!cn"]
      },
      "localhost"
    ],
    "queryStrategy": "UseIP"
  }
}

domains 的比對方式與網域規則體系相關，所依賴的分類資源也必須能夠載入。expectIPs 不是把解析結果改寫到某個網段，而是用來篩選或判斷回應是否符合預期。條件過於狹窄時，合法但不在分類範圍內的位址可能被拒絕，表現為該網域解析失敗。故障排查時應暫時使用簡單的伺服器設定進行比較，再逐步恢復網域條件與結果限制。

hosts 的靜態對映

hosts 用於為特定名稱提供靜態對映，適合固定的本機服務、測試環境或明確需要覆寫的記錄。不適合用來取代大規模動態 DNS。目標位址變更時，靜態值不會自動更新；設定中遺留的舊對映還可能讓某個網域長期指向錯誤位址。檢查「只有一個網域始終連到舊伺服器」這類問題時，應搜尋 hosts、系統 hosts 檔案和用戶端自訂 DNS 對映這三處。

靜態對映的名稱仍可能進入路由模組。應確認路由判斷使用原始網域還是解析後的 IP，以及該 IP 會命中哪個出口。如果本地域名對映到私有位址，通常還需要私有位址直連規則。否則連線可能被錯誤送往代理出站，造成區域網路服務無法存取。

queryStrategy 與位址族選擇

queryStrategy 用於限制查詢的位址類型。常見目標是同時使用可用位址、只請求 IPv4 或只請求 IPv6，具體可選值取決於核心實作。選擇時要以目前網路是否真正具備相應位址族的連通性為依據。網路能回傳 IPv6 位址但沒有穩定的 IPv6 出口時，應用程式可能優先嘗試無法連通的位址，表現為連線延遲或逾時；反過來，強制只使用 IPv4 會排除只提供 IPv6 的目標。

位址族問題不應只靠反覆切換策略來判斷。可以分別查看 DNS 回傳結果、系統路由表和核心連線日誌，確認最終嘗試的是哪一類位址。若代理伺服器本身以網域填寫，用於解析它的位址族同樣會影響核心能否建立出站連線。目標網站解析正常但伺服器網域解析失敗時，故障發生在不同環節。

DNS 查詢如何選擇出站

DNS 伺服器也是一個目標，查詢流量同樣需要經由網路出口。部分設定可以為 DNS 伺服器設定標籤，或透過專用出站處理；用戶端也可能產生專用的 DNS 路由。設計時要避免迴圈：解析代理伺服器位址所需的 DNS 若依賴尚未建立的代理出站，啟動階段可能無法完成第一步連線。常見做法是讓伺服器位址解析具備可用的本地路徑，再讓目標網域查詢依規則選擇直連或代理出口。

當解析伺服器寫成網域而不是 IP 時，它本身也需要先被解析，這又增加了一層依賴。基本設定應優先建立可解釋的路徑，確認運作後再引入加密 DNS、條件式伺服器和複雜的出站繫結。有關中國大陸與海外網域分開解析、servers、domains 與 expectIPs 的組合，可繼續閱讀V2Ray DNS 設定詳解。

快取與故障排查順序

DNS 結果可能存在於應用程式、作業系統、用戶端或核心的快取中。修改設定後立即重複存取，仍可能使用舊結果。正確步驟是儲存設定、重新啟動對應核心，視需要關閉並重新開啟測試應用程式，再觀察新的日誌。不必每次都清除整個系統網路狀態；應先確認是哪一層快取了結果。若重新啟動核心後日誌仍沒有新的查詢記錄，表示應用程式可能沒有把網域解析交給核心。

DNS 故障排查可以遵循固定順序：先驗證伺服器位址可達，再用無條件規則確認能取得結果，接著加入 domains，最後加入 expectIPs 和出站繫結。每一步只增加一個變數。解析成功後仍無法連線，則轉向路由與出站檢查；不要把所有連線錯誤都歸因於 DNS。

policy、stats 與 log：工作階段策略、統計開關與診斷記錄

policy 控制連線工作階段行為

policy 用於設定使用者層級和系統層級的執行策略。常見內容包括交握等待時間、連線閒置時間、上下行單向關閉後的延遲，以及是否啟用使用者流量統計。它不負責網域路由，也不會改變傳輸協定。預設策略通常足以應付桌面用戶端使用，只有在明確遇到長連線回收、伺服器端使用者等級或統計需求時才需要調整。

使用者層級由協定使用者物件中的 level 與 policy.levels 對應。若使用者未指定等級，通常會使用預設等級。等級是策略索引，不是線路品質或權限評分。手動設定時，如果使用者寫了 level: 1，卻只定義等級 0，預期策略就不會依設計套用。用戶端節點通常不需要自行增加等級，除非伺服器端與用戶端的設定方案明確使用此機制。

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 4,
        "connIdle": 300,
        "uplinkOnly": 2,
        "downlinkOnly": 5,
        "statsUserUplink": false,
        "statsUserDownlink": false
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  },
  "stats": {}
}

handshake 限制建立連線階段可等待的時間，設定過短會讓網路波動下的正常連線提早終止；設定很長則會讓無回應連線占用資源更久。connIdle 用於處理閒置連線，某些需要長時間保持但暫時沒有資料的應用程式可能受其影響。uplinkOnly 與 downlinkOnly 處理半關閉狀態下的保留時間。沒有充分理由時，不宜為了追求「更快釋放」而把這些值壓得過低。

stats 物件與統計開關的關係

僅寫入一個空的 stats 物件，不一定會產生所有統計資料。需要在 policy.system 或使用者等級策略中啟用相應方向的統計開關，再由用戶端或 API 讀取。入站與出站統計用於觀察對應標籤的總流量，使用者統計則與協定使用者及等級策略相關。統計功能會增加一定的狀態維護工作，若用戶端介面不讀取這些資料，可以保持關閉。

圖形用戶端顯示的流量資訊可能來自核心統計介面，也可能來自用戶端自身對連線的彙總。看到介面上有流量數字，不代表設定中所有 stats 欄位都已啟用；反過來，啟用統計但沒有讀取介面，介面也未必會顯示結果。故障排查應先確認資料產生的位置，再檢查讀取方式，避免把顯示層問題當成轉送故障。

log 的存取記錄、錯誤記錄與層級

log 常見欄位包括存取日誌位置、錯誤日誌位置和 loglevel。日誌層級可依故障排查需求調整。日常執行使用警告層級可以減少輸出；遇到設定引用、DNS 選擇或連線交握問題時，可暫時提高詳細程度。問題重現並完成記錄後，應恢復適合長期執行的層級，以免日誌持續增長並混入大量無關資訊。

{
  "log": {
    "access": "access.log",
    "error": "error.log",
    "loglevel": "warning",
    "dnsLog": false
  }
}

相對日誌路徑通常是相對於核心工作目錄，而不是設定檔所在目錄。由 v2rayN 等用戶端啟動核心時，工作目錄可能由用戶端決定，因此手動查看檔案時要先確認實際執行目錄。若路徑所在目錄沒有寫入權限，核心可能無法建立日誌檔案，甚至直接啟動失敗。為避免路徑差異，優先使用用戶端提供的日誌查看入口；需要自訂路徑時，再使用目前系統中明確可寫入的目錄。

存取日誌用於記錄連線目標和處理結果，錯誤日誌用於記錄解析、交握、資源載入與模組異常。日誌可能包含目標網域、位址和本機連線資訊，分享故障排查內容前應刪除與問題無關的個人設定資料。完整設定中的使用者識別碼、伺服器參數和訂閱內容也不應直接貼到公開環境；通常只需提供錯誤行、相關模組和經過簡化的欄位結構。

DNS 日誌與路由診斷

部分核心支援透過 dnsLog 或更詳細的日誌觀察 DNS 查詢。此選項是否存在及具體行為，應以目前核心文件和用戶端產生的設定為準。啟用後重點查看查詢網域、選定的伺服器、回傳位址和失敗原因。路由診斷則關注入站標籤、目標資訊、命中規則與最終出站。結合兩類記錄，才能解釋「網域解析到某個位址後，為何又被某條 IP 規則分配到特定出口」。

日誌中的第一條錯誤通常比後續連鎖錯誤更有價值。例如資源檔案無法載入後，大量 geosite 規則都會失敗；連接埠繫結失敗後，應用程式端會產生一連串代理不可用提示。應依時間順序找到核心啟動階段最早的異常，再判斷後續內容是否只是結果。若核心啟動成功，只在存取特定目標時出錯，再依單次連線記錄追蹤。

API 與管理介面的界線

部分設定透過 API 入站向用戶端提供統計、日誌或執行控制能力。它通常由圖形用戶端自動產生，並繫結本機位址。手動修改這類入站標籤、服務清單或路由規則，可能導致用戶端無法讀取核心狀態。API 連接埠不應當作一般 SOCKS 或 HTTP 代理連接埠使用，也不應隨意開放到區域網路。若用戶端能正常啟動核心但狀態列無法更新，應比較 API 入站、通往 API 出站的路由規則，以及用戶端預期的連接埠。

policy、stats、log 和 API 都屬於執行管理層。它們有助於觀察連線，卻不能取代對入站、路由、DNS 和出站鏈路的檢查。最小設定應先確保流量能正確通過，再逐項啟用統計與管理功能。如此即使管理介面發生問題，也能明確區分「核心無法轉送」與「用戶端無法顯示狀態」。

組合設定與故障排查：從語法測試到單一連線追蹤

先建立可驗證的完整鏈路

組合設定時，不要直接從一份包含大量規則、多個出口和複雜 DNS 的檔案開始。先建立一個本機 SOCKS 入站、一個參數完整且已知可用的代理出站、一個直接連線出站，以及少量明確路由。確認核心可以啟動、應用程式可以連線，且兩個出口都能分別運作後，再加入網域分類、條件式 DNS、封鎖規則和統計模組。每增加一層就進行一次測試，問題出現時便能鎖定最近的修改。

在圖形用戶端環境中，設定來源通常有三層：訂閱或手動節點提供遠端參數，用戶端設定提供本機連接埠與系統代理行為，路由和 DNS 範本提供分流邏輯。最終執行檔案是三層合併的結果。節點詳細資訊正確但執行失敗時，應匯出或查看實際設定，確認用戶端沒有覆蓋伺服器名稱、傳輸方式或出站標籤。升級或切換核心後，也要檢查舊欄位是否仍被目前核心接受。

執行語法與設定測試

核心通常提供只測試設定而不長時間執行的指令。指令名稱和參數形式會隨核心程式而異，常見形式如下。執行時應使用用戶端實際呼叫的核心檔案和實際設定路徑。若圖形用戶端已提供「檢查設定」或日誌入口，優先使用用戶端功能，因為它會帶入正確的工作目錄與資源路徑。

v2ray test -c config.json

xray run -test -config config.json

測試通過表示 JSON 可以解析，且基本模組能夠建立，不代表遠端伺服器可達，也不代表每條路由都符合預期。測試失敗時，從輸出中的欄位路徑和最早錯誤開始處理。若提示無法載入地理資料，先檢查資源檔案與工作目錄；若提示找不到標籤，檢查路由引用；若提示位址已被使用，檢查入站連接埠；若提示未知欄位，則確認目前核心家族是否支援該設定。

用於本機結構驗證的組合範例

以下範例不包含遠端代理認證資料，而是用直接連線和封鎖出口展示完整的模組關係。可用於驗證本機入站、DNS、路由與日誌層級。實際加入代理出口時，應將伺服器端提供的協定與傳輸欄位作為完整物件插入，並將兜底規則的 outboundTag 改為對應的代理標籤。

{
  "log": {
    "loglevel": "warning"
  },
  "dns": {
    "servers": ["localhost"]
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "domain": ["full:block.example"],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "direct"
      }
    ]
  }
}

依症狀選擇故障排查入口

症狀分類的作用是減少無關修改。核心無法啟動時，伺服器是否可達並不重要；應用程式無法連到本機連接埠時，先檢查入站，不必更換遠端節點；只有部分網域失敗時，重點是該網域與正常網域在 DNS、路由和嗅探上的差異。每次測試都應包含一個對照對象，例如同一出口下的正常網域、同一網域走 direct 的結果，或同一節點關閉複雜路由後的結果。

修改設定後的固定檢查清單

儲存後先進行 JSON 與設定測試，確認沒有語法和模組初始化錯誤。接著檢查所有標籤引用：每個 outboundTag 都存在，每個 inboundTag 都能找到入口，負載或 API 相關標籤也沒有改名。再確認本機連接埠沒有衝突，且用戶端使用的代理類型與入站協定一致。核心啟動後，分別測試直接連線規則、代理規則和私有位址規則，最後再測試 UDP 或特殊應用程式。

DNS 修改需要額外記錄查詢伺服器與回傳位址；路由修改需要記錄實際命中的規則；傳輸層修改需要對照伺服器端參數；策略修改需要觀察長連線，而不是只開啟一次網頁。按模組記錄結果，比「修改後好像更快」可靠得多。如果問題只能在某個應用程式中重現，還應比較該應用程式是否自行解析網域、是否支援 SOCKS UDP、是否忽略系統代理，以及是否維持舊連線。

用戶端設定與手動設定如何共存

v2rayN 是桌面平台的首選管理用戶端，適合透過介面維護訂閱、節點、路由和 DNS；v2rayNG 與 v2flyNG 用於 Android，分別對應不同核心路線。需要安裝或重新選擇用戶端時，可前往安裝套件頁面。用戶端負責產生執行設定時，應盡量透過其自訂設定、路由設定或 DNS 設定入口進行修改，直接編輯暫時產生的檔案通常會在重新啟動或切換節點後遺失。

確實需要手動維護 JSON 時，應將穩定設定與用戶端暫存檔案分開存放，並明確由誰負責啟動核心。不要讓兩個用戶端同時監聽相同連接埠，也不要讓系統代理仍指向已停止的執行個體。訂閱更新只會更新節點來源，不會自動證明自訂路由與 DNS 仍然適用；更新後應重新查看合併結果，尤其是出站標籤和傳輸層欄位。

建立可重複的故障排查記錄

有效的故障排查記錄應包含發生時間、用戶端與核心類型、相關入站標籤、目標網域或位址、命中的出站、第一條錯誤訊息，以及本次唯一修改的欄位。不必複製整份包含敏感連線參數的設定。把問題縮減成最小結構後，通常更容易判斷是語法、核心相容性、網路可達性還是規則邏輯。

完成基本設定後，可回到使用文件核對用戶端操作主線；處理訂閱異常、路由優先順序、DNS 分流或連接埠衝突時，可在文章目錄依故障類型繼續查閱。系統化設定的目標不是堆疊欄位，而是讓每個入口、比對條件和出口都有清楚作用，並能透過日誌與對照測試解釋其行為。