設定檔參考

V2Ray JSON 設定手冊

首次安裝、匯入訂閱及驗證連線,請先依照入門指南的步驟操作。若已能連線,想查詢欄位意義、判斷流量從哪裡進入,或修改規則,再回來參閱本手冊。範例以本機迴圈位址入站及一般直連為基準;需要補充術語時,可參考概念速查。

01 檔案架構

JSON 結構總覽

沿著連線流程閱讀設定

應用程式向本機監聽埠發出請求後,入站會依自身協定讀取目標位址。路由再根據可用的目標資訊、入站標籤及其他條件選擇出站。出站負責建立實際連線,可以直接連線,也可以依節點設定與遠端互動。要判斷某個欄位會影響哪個環節,先找出它在這條連線流程中的位置。修改監聽位址不等於修改節點;修改出站位址,也不會讓原本沒有使用代理的應用程式開始透過入站連線。

頂層是一個物件,不是把入站、出站和規則並排放進同一個清單。inbounds 和 outbounds 是陣列,分別容納多個入口和出口;routing、dns 和 policy 則是物件,各自有內部結構。欄位名稱區分大小寫,陣列順序也可能影響行為。尤其要記得,出站陣列的第一項和規則陣列的第一條不是同一回事:前者是預設出站,後者只是最先接受比對的候選規則。

建立可執行的直連基準設定

以下是一份完整的原生設定檔,會在本機迴圈位址開啟 SOCKS 入站,並將流量交給直連出站。它不依賴訂閱、遠端帳號或地理規則資料庫,只用來確認「應用程式能否將請求交給核心」。使用前請確認埠號未被其他執行個體占用。如果本機原本就無法連線至測試目標,直連基準設定也不會改變這點;請先選擇目前網路中已知可連線的目標。

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

這份基準設定刻意不加入路由,因為只有一個出站,未符合任何規則的請求也有明確去向。也不加入內建 DNS 或連線策略,避免第一次測試時混淆系統解析、核心解析與等待逾時。啟動成功後,請使用明確支援 SOCKS 的應用程式,並將代理指向範例位址;不要只看系統匣圖示或介面狀態。開啟網頁前,也可以先連線到一個已知由本機提供、且目前使用者有權存取的服務,確認本機連線路徑正常。

將範例合併到正確層級

後續標示為頂層片段的程式碼雖是合法 JSON,卻不一定能獨立啟動。新增頂層欄位時,請將對應的鍵和值併入基準設定的同一個物件;修改現有欄位時,替換對應值或在陣列中加入物件。不要直接串接兩個含外層大括號的檔案,也不要在同一個物件中重複使用相同的鍵。不同解析器處理重複鍵的方式可能不同,即使成功讀取,也可能只採用後面出現的內容。

頂層欄位結構修改後優先檢查
inbounds物件陣列應用程式使用的協定、位址與埠號是否完全一致。
outbounds物件陣列預設出站的位置,以及規則引用的標籤是否仍然正確。
routing物件規則是否依預期順序比對,目標是否符合預期的第一條規則。
dns物件是應用程式、路由判斷還是出站撥號觸發了解析。
policy物件受測連線實際使用的等級是否與修改項目相符。

建議保留一份基準設定和一份編輯中的副本,使用同一個請求比較修改前後的結果。標準 JSON 使用雙引號,最後一項後面不加逗號,布林值使用小寫字面值,而非字串。格式檢查只能確認檔案能否解析,無法保證目前的核心支援相關欄位,也不能證明引用的標籤一定存在。格式檢查通過後,還要查看啟動結果,再確認單一連線的實際行為。分開進行這三項檢查,排除問題時才知道該從哪一層著手。

本手冊中的最小設定檔用於獨立執行。如果用戶端正在管理相同埠號,請先停止舊的執行個體或改用空閒埠號;不要把兩個程序的監聽衝突誤判為設定語法錯誤。

02 本機入口

inbounds 入站

監聽位址與應用程式協定要一起檢查

每個入站都要確認三件事:接收連線的位址、監聽的埠號,以及讀取資料所用的協定。listen 是繫結位址,不是用戶端要連線的目標網站;port 是本機入口,不是遠端節點埠號;protocol 則決定應用程式要選用哪種代理類型。將 HTTP 代理請求送到 SOCKS 埠,或把 SOCKS 請求送到一般 HTTP 服務,都可能出現「埠號可以連線,實際請求卻失敗」的情況。

在本機應用程式中使用時,請先從 127.0.0.1 開始。這會將監聽限制在本機,但本機上的其他程序仍可能存取該入口。不要為了解決連線失敗,就把沒有驗證的範例改成監聽所有介面。如果應用程式和核心都明確使用 IPv4 迴圈位址,請始終填入相同位址,以免應用程式優先將 localhost 解析為 IPv6 迴圈位址,而核心只監聽 IPv4。容器或虛擬機器中的迴圈位址屬於各自的網路環境,不能取代主機位址。

以兩個獨立入站區分 SOCKS 與 HTTP

以下頂層片段可取代基準設定檔原有的 inbounds。它會將 SOCKS 與 HTTP 代理分配到不同埠號,並為每個入口設定獨立標籤。瀏覽器支援哪種類型、終端工具該使用哪個參數,請依工具的代理設定確認。HTTP 入站可接收支援 HTTP 代理的應用程式所發出的請求,包括透過 CONNECT 轉送的請求;它不是用來接收一般瀏覽器頁面請求的網站服務。

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": { "auth": "noauth", "udp": false }
    },
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

標籤只在設定內部用來識別入口。應用程式填入的是類型、位址與埠號,不會將標籤傳給核心。路由可以透過 inboundTag 讀取這個識別值,因此應用程式 A 固定使用 SOCKS、應用程式 B 固定使用 HTTP 時,可以用不同入站區分連線路徑。如果兩個應用程式都使用同一個入口,標籤就無法區分它們。修改標籤時,也要搜尋所有引用;如果只修改入站物件,舊規則可能永遠不會命中。

UDP 與目標識別不是同一個開關

範例關閉 SOCKS 的 UDP 支援,因為基準設定只用來驗證一般網頁連線。若要排查支援 SOCKS UDP 的應用程式,必須同時確認應用程式確實發出 UDP 轉送、對應的 SOCKS 入站允許 UDP,且後續出站支援傳送這類流量。只開啟入站開關,無法補足另外兩個環節。反過來說,如果測試的是明確使用 TCP 的請求,修改 UDP 開關也沒有排查作用。先確認連線類型,再決定是否需要增加一組測試。

應用程式可能會直接將網域名稱交給 SOCKS,也可能先在本機解析,只將 IP 位址交給核心。後一種情況下,光靠網域路由條件可能無法得知原始輸入的網域名稱。某些入站可透過 sniffing 從支援的上層流量中辨識目標資訊,但結果取決於協定、可見資料及目前的核心實作,不能取代明確的應用程式代理設定。排查時先關閉額外的識別功能,比較將網域名稱交給代理與將 IP 位址交給代理的結果,再決定是否需要這項功能。

本機監聽失敗時,先區分位址無法繫結與埠號已被占用。前者優先檢查本機能否使用填入的位址;後者先確認占用中的程序,再決定停止舊執行個體或調整埠號。更改埠號後,瀏覽器、終端機和系統代理等所有指向此入口的設定都必須一併更新,否則新執行個體雖然正常,應用程式仍會連到舊埠號。可參考本機埠號衝突排除,不要只看到有程序在監聽就直接將它結束。

03 連線出口

outbounds 出站

第一項是預設出站,標籤是引用名稱

出站定義核心取得目標後如何處理連線。freedom 用於直接連線至目標,blackhole 則會捨棄送往該出站的流量。兩者都不需要遠端帳號,適合作為規則測試的對照。標籤可依用途命名,但名為 direct 的出站不會因為名稱而自動具有直連能力,實際行為由 protocol 等欄位決定。規則引用的是標籤,不是協定名稱,更不是訂閱中顯示的節點備註。

沒有符合規則時,連線預設交給出站陣列的第一項。因此,「新增一個物件」和「將物件移到第一項」是不同操作。如果原本的第一項是直連,後來將捨棄出站移到第一項,未經任何規則處理的一般請求也會遭到捨棄。反過來說,原本預期使用遠端節點的流量若沒有符合規則,而第一項是直連,就會改走直連。先決定預設行為再排列出站,不要只依照介面上節點的顯示順序決定。

{
  "outbounds": [
    { "tag": "direct", "protocol": "freedom", "settings": {} },
    { "tag": "blocked", "protocol": "blackhole", "settings": {} }
  ]
}

將上述片段取代基準設定檔中的 outbounds 後,在尚未加入規則前,不會有請求主動進入 blocked。這個片段要搭配下一章的路由片段使用。為備用出站設定不同標籤,並保留第一項不動,就能在規則中縮小測試範圍,避免影響所有一般請求。若要還原基準設定,請先確認規則不再引用即將刪除的標籤,再移除備用物件。

分別核對協定、傳輸方式與安全設定

使用遠端節點時,出站中的協定、節點位址與埠號、驗證參數、底層傳輸方式及安全設定都必須符合伺服器設定。協定欄位說明如何建立工作階段;settings 放置該協定所需的目標及驗證資訊;常見的 streamSettings 則描述連線至遠端時使用的傳輸與安全參數。代理請求最終要連線的網站,與出站所連線的遠端節點位址是兩個不同目標,也可能各自觸發網域解析。

排除問題時,不必立刻重寫整份設定。先比對目前節點的主機名稱與埠號,再核對傳輸類型及其相關參數,最後檢查安全交涉是否符合伺服器設定。若 TCP 已經連線成功,但在交涉階段失敗,通常只修改本機監聽埠號並沒有幫助。不要關閉安全檢查來掩蓋主機名稱、憑證或時間錯誤;應保留目前的安全限制,確認設定是否符合節點提供者給出的連線參數。

用戶端清單中的訂閱網址、顯示名稱與原生出站也不是同一類物件。訂閱負責提供節點項目;用戶端會依選取的節點和核心產生執行所需的出站設定。將訂閱網址填入遠端節點位址欄位不會得到相同結果;把介面備註複製到規則的 outboundTag 也不一定有效。若要核對產生的設定,應查看目前執行個體實際載入的檔案,而非之前匯出的範例。訂閱中各節點的條件可參考節點選擇說明。

使用對照請求縮小故障範圍

選擇同一個測試目標,分別透過正常的直連出站及需要驗證的遠端出站發出新請求。如果直連正常、遠端失敗,表示這次測試中的應用程式代理、監聽及直連路徑可用,下一步再核對遠端參數與交握階段。如果兩種出站都失敗,就先回頭檢查共同的入口、目標可連線性與解析流程。切換後要重新建立連線;瀏覽器保留的舊工作階段可能繼續使用既有通道,讓先前的成功或失敗看起來像是新設定造成的結果。

04 比對順序

routing 路由規則

符合第一條規則後生效,未命中則使用預設出站

routing.rules 會由前往後比對,規則命中後,後面的規則不會再為同一個請求選擇出口。在同一條規則中寫入網域與入站條件,代表所有條件都成立才會命中;在同一個網域條件陣列中列出多個選項,通常只要符合其中一項即可。要表達「來自某個入口的指定網域」,可以寫在同一條規則中;要表達「符合任一入口條件,或符合另一個獨立目標條件」,通常應拆成兩條規則。

範圍較窄的例外規則要放在範圍較廣的規則前面。例如,先比對「來自本機 SOCKS 且目標為某個完整網域」,再比對「所有來自本機 SOCKS 的請求」。如果後者寫在前面,前者就沒有機會命中。沒有任何規則符合時,不會自動使用清單最後一條規則的出口,而是使用出站陣列的第一項。因此閱讀規則清單時,也要同時確認出站順序,尤其是從用戶端產生的設定中擷取部分規則時。

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "domain": ["full:example.com"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}

將此片段併入基準設定,並使用上一章含有 blocked 的出站陣列,即可用兩個網域進行對照測試。透過 SOCKS 並將網域名稱交給代理時,完整名稱 example.com 會符合第一條規則;其他網域則會繼續比對第二條。來自本機 HTTP 入站的請求不符合這兩條規則的入口條件,因此會使用預設出站。如果應用程式預先將目標解析為位址,第一條規則可能不會成立;此時應先確認目標的表示方式,而不是懷疑規則順序。

分別驗證網域比對與位址比對

full: 表示完整網域比對;若要比對某個網域及其子網域,請使用 domain: 格式。沒有前綴的一般字串會以子字串方式比對,字串太短容易將不相關的名稱也納入。同一個規則目標可以用網域或 IP 位址描述,但兩者比對的是不同形式的輸入。對於共用位址的網站,IP 規則通常無法區分不同網域;如果應用程式已經解析出位址,網域規則也無法自動還原原始名稱。

domainStrategy 控制路由在什麼情況下使用解析結果比對 IP 規則,不代表出站會以相同方式撥號。AsIs 不會為路由比對主動將網域解析成 IP;IPIfNonMatch 會在原始資訊未命中時,嘗試解析網域後再次比對;IPOnDemand 則可在比對需要 IP 的規則時解析網域。如果前面已有範圍較廣的規則命中,後面的規則就不會參與判斷;增加 DNS 伺服器也無法改變這點。

為新增規則安排正向與反向測試

新增規則時,保留一個應該命中的請求、一個名稱相近但不應命中的請求,以及一個完全無關的目標。分別記錄入口標籤、交給核心的目標形式及實際出口。使用 geoip: 或 geosite: 前,也要確認核心能讀取對應資料,且相關類別確實存在;規則文字正確,不代表本機已安裝所需資料。若要快速確認比對順序,優先使用不依賴資料檔案的精確網域或明確位址範圍。

最後要分清楚「流量有沒有進入核心」與「進入後如何分流」。系統代理是部分應用程式將請求交給本機入口的一種方式;路由規則只會套用在已進入核心的請求。調整分流不會自動攔截未使用代理的終端連線,也不能取代系統代理開關。若要比較介面上的全域與分流選項,可先閱讀系統代理與路由模式說明,再回來核對實際產生的規則。

05 名稱解析

DNS 設定

先確認是誰發起解析

頂層 dns 設定的是核心的解析功能,不代表會取代系統的所有 DNS 查詢。應用程式可以在連線前使用系統解析器,也可能使用自行設定的解析服務;如果它只將 IP 位址交給 SOCKS 入站,核心就不需要為該目標解析網域。相反地,應用程式將網域原樣交給入站後,路由可能會使用內建 DNS 比對位址規則,出站也可能在建立連線時解析名稱。先確認解析發生在哪個步驟,再決定要修改哪一層。

以下片段會將本機系統解析器列為核心 DNS 的伺服器選項,並透過 hosts 為兩個保留測試名稱設定固定對應。將它併入基準設定,只是定義核心在相關解析情境中的查詢方式,不會讓核心預設監聽本機 DNS 埠號。測試位址來自文件保留網段,目的是驗證比對流程,而非提供實際網頁服務;無法連線並不能用來判斷對應是否生效。

{
  "dns": {
    "hosts": {
      "test.example": "192.0.2.10",
      "control.example": "198.51.100.10"
    },
    "servers": ["localhost"]
  }
}

透過位址路由驗證核心解析

若要實際區分上述兩筆對應,可保留直連與捨棄兩個出站,再將路由替換為以下片段。使用能將網域交給代理的 SOCKS 應用程式發出請求。路由遇到 IP 條件時會嘗試解析目標,因此 test.example 對應的位址會進入捨棄出站;control.example 對應的位址不在該規則範圍內,會改用預設出站。請透過目前執行個體可用的路由或存取記錄確認連線路徑,不能因為兩個保留位址都無法提供網頁,就推斷結果相同。

{
  "routing": {
    "domainStrategy": "IPOnDemand",
    "rules": [
      {
        "type": "field",
        "ip": ["192.0.2.0/24"],
        "outboundTag": "blocked"
      }
    ]
  }
}

用於路由判斷的解析結果,與實際撥號時採用的目標並不是同一回事。對直連出站而言,若要明確使用內建 DNS 提供的位址,還要檢查該出站的網域策略;對遠端代理出站而言,則要區分在本機解析的遠端節點主機名稱,以及交由遠端處理的網站名稱。這兩種網域可能剛好都出現在同一串記錄中。修改 routing.domainStrategy 不保證會改變遠端看到的目標形式,也不保證瀏覽器會改用核心執行名稱查詢。

分別檢查伺服器選擇、位址家族與快取問題

dns.servers 可以包含簡單的伺服器項目,也可以使用帶有網域比對條件的伺服器物件。依網域為某個解析服務設定優先查詢範圍,不等於強制整個系統使用這台伺服器;回退規則及可用欄位仍需參考執行中核心的說明。實際部署時,先從一個可連線的伺服器開始,記錄一個應使用專用解析器的網域,以及一個應使用一般解析的網域。有分流需求時再擴充清單,避免同時調整位址、網域比對與回退行為。

如果部分名稱能解析,但連線一直無法建立,請分別確認回傳記錄的位址家族,以及本機能否連線至該位址。取得 IPv6 記錄不代表所在網路有可用的 IPv6 路徑;反過來,也不應只因一次 IPv6 連線失敗就永久停用該位址家族。先進行一組可控的對照測試,確認哪一類位址與失敗同時出現,再調整查詢策略或網路環境。DNS 查詢失敗與解析成功後連線逾時是兩種不同問題,可從記錄中的時間點加以區分。

變更對應或解析器後,舊結果可能仍留在瀏覽器、系統或核心快取中。重新啟動其中一層,不代表其他層的記錄也會清除;既有連線也不一定會重新解析。測試時請建立新連線,必要時改用從未查詢過、由自己控制的測試名稱。如果一般程式與 SOCKS 程式得到不同結果,先保留這項差異作為證據,不要立刻把兩種程式都改成相同的解析設定。

06 連線行為

policy 連線策略

先確認連線屬於哪個等級

policy 用於設定核心連線策略,例如交握等待時間、閒置時間及部分統計開關。它不會選擇出口,也不能取代路由規則。policy.levels 是一個物件,鍵是使用者等級對應的字串,例如 "0";設定中讓協定連結某個等級時,欄位值通常是數字。自訂等級不會只因名稱出現在 levels 中就套用到所有連線,必須確認所用協定如何為連線指定等級。

基準入站沒有明確提高使用者等級,因此此處以零級作為對照。以下提供以秒為單位的範例數值,用來觀察調整等待時間的影響,不建議所有網路直接照抄。將片段併入基準設定後,先確認目前連線仍使用該入站,再驗證策略。如果用戶端產生了另一套入站,或另一個協定為使用者指定不同等級,修改零級設定就無法解釋該連線的行為。

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 180,
        "uplinkOnly": 10,
        "downlinkOnly": 10
      }
    }
  }
}

分別理解交握、閒置與單向收尾

handshake 是代理協定在相應交握階段的等待限制,不是整個網頁瀏覽的總時間,也不是所有底層連線逾時的通用開關。connIdle 則適用於已建立、且一段時間沒有傳輸資料的連線。如果連線每次都在建立後、閒置時間相近時中斷,才值得優先檢查這個欄位;如果連線從未成功建立,應先檢查監聽、遠端位址、節點交涉或網路錯誤。

uplinkOnly 與 downlinkOnly 管理連線進入單向收尾時,剩餘方向的等待時間,不是上傳或下載限速。例如應用程式結束傳送後,仍需等待服務傳回最後一段資料時,會進入只剩下行的階段。將這個階段的等待時間設得太短,可能讓較晚送達的回應來不及返回。排查檔案上傳完成後遲遲沒有結果的情況時,要分清楚是處理端真的很慢、連線遭中間設備關閉,還是核心在收尾階段提早終止連線。

欄位關注階段不適合用來解釋的現象
handshake相關協定建立工作階段交握成功後,資料傳輸長時間過慢。
connIdle連線建立後沒有資料傳輸的時段應用程式從未連上本機埠號。
uplinkOnly、downlinkOnly剩餘的單向傳輸階段網域已符合更早的路由規則。

逾時設定與統計資料都要確認適用範圍

測試逾時時,選擇一條已知能穩定建立的連線,記錄開始時間、最後一次有效傳輸時間及關閉時間。每輪只修改一個欄位,並重新建立連線。應用程式的請求時間上限、系統與中間設備的閒置限制,以及伺服器本身的等待策略,都可能早於核心設定生效。如果調整核心數值後,中斷時間仍固定在應用程式的等待期限,就應檢查應用程式或遠端伺服器,不要繼續延長彼此無關的策略欄位。

統計資料也有不同層級。等級下的使用者上傳與下載統計,與系統層級依入站或出站彙整的統計,採用的計算方式並不相同。只有啟用對應功能,且目前的協定與連線提供所需的統計維度時,才會有資料可供讀取。開啟策略開關不代表用戶端介面會立即顯示數字,也不等於設定了流量配額。除錯程序首次啟動時,不必先串接統計介面才能判斷規則是否命中;測試一個入口與一個目標的連線結果更直接。

不要為了消除錯誤就一律將逾時設得很長。等待時間過長可能延後失敗提示,也會讓已無法完成的連線持續占用資源。先確認限制發生在哪一層,再只修改負責該階段的設定。

如果為了診斷暫時放寬等待時間,確認原因後應還原原設定,或只保留有證據支持的調整項目。記錄目標、核心、入口標籤、連線等級及發生時間,下一次出現相同錯誤時才有可比較的條件。缺少這些背景資訊時,一張顯示「逾時」的截圖通常無法判斷究竟是代理交握尚未完成,還是已建立的連線正在等待資料。

07 編輯範圍

用戶端設定與原生 JSON

區分介面輸入、產生的設定與實際執行檔案

日常使用時,建議優先透過用戶端介面設定代理;桌面端首選 v2rayN,Android 可依核心需求選擇 v2rayNG 或 v2flyNG。用戶端下載頁依作業系統與架構提供下載入口;本手冊只說明核心讀取的設定。用戶端可以儲存節點、訂閱、分流方案與程式狀態,但這些資料不一定以原生核心設定的形式存放。看到副檔名為 JSON 的檔案,不代表它可以直接交給核心執行。

訂閱更新會影響節點項目,圖形介面設定會影響下一次產生的執行設定,而核心實際使用的是目前執行個體載入的檔案。直接修改用戶端暫存產生的檔案,切換節點、重新啟動核心或重新套用設定後,修改可能會被覆寫。若要長期保留某項修改,請優先使用用戶端提供的相應設定;確實需要原生檔案時,請在支援自訂設定的模式下另存獨立副本,並明確記錄哪些變更由用戶端管理,哪些由維護者自行追蹤。

平台用戶端優先確認的執行條件
Windowsv2rayN分別核對應用程式使用的系統代理與核心監聽端點。
macOSv2rayN分清楚系統代理設定、應用程式本身的網路選項,以及實際啟動的核心。
Androidv2rayNG、v2flyNG確認系統 VPN 的流量接管狀態、納入的應用程式與核心路由結果。
Linuxv2rayN分清楚桌面網路設定與終端程序繼承的代理參數。

切換核心時應比對有效欄位,而非複製整份設定

Xray 與 V2Fly 有共通的設定概念,但特定協定、傳輸方式、安全選項及專有欄位未必通用。移植時可先保留獨立的本機入站與直連出站,確認最小設定檔能啟動後,再逐段加入原檔中的規則、解析設定與遠端出站。留意錯誤指出的是未知欄位、無效欄位值,還是缺少資源檔案。同一份設定可在某個用戶端正常運作,不代表換用其他用戶端或核心後也能原樣執行。

以下頂層片段只保留一個本機迴圈位址的 HTTP 入口與一個直連出站,可用來跨核心檢查這兩個基本物件。它和第一章的 SOCKS 基準設定採用不同的入口方式:應用程式必須明確使用 HTTP 代理及本例的埠號。如果要比較兩個核心,請讓兩者依序執行同一份檔案,並確保舊程序已結束。不要同時啟動兩份設定搶用同一個埠號,否則得到的是監聽衝突,而非相容性測試結果。

{
  "inbounds": [
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    { "tag": "direct", "protocol": "freedom", "settings": {} }
  ]
}

如果原生檔案能啟動,明確設定代理後的測試也有效,但用戶端啟動的執行個體表現不同,接下來應比較執行檔案中的出站順序、入口埠號、路由標籤及 DNS 策略,而不是只核對節點名稱。如果差異只在開啟系統代理或虛擬網卡模式後出現,就要進一步檢查流量接管方式。入口接管涉及用戶端與系統之間的設定;原生 JSON 中寫好出站,並不能讓應用程式自動開啟原本未使用的代理通道。

分享設定片段時,只保留重現問題所需的資料

需要請別人協助排查時,先複製一份臨時設定,刪除訂閱網址、遠端憑證、真實節點位址、個人目錄及可識別的存取記錄。保留必要的鍵、值類型、陣列順序及標籤之間的引用關係;只替換其中一端的標籤,會讓新片段產生原本不存在的錯誤。若問題必須透過遠端重現,請說明失敗階段和對應錯誤訊息,不要上傳完整執行檔案。首次啟動與匯入節點的介面操作可參考v2rayN 初始設定。

每次儲存持久變更前,先寫明要改變哪個請求的行為,以及如何撤銷。例如,分流設定可透過還原原有規則順序撤銷,系統代理則應在應用程式或系統設定中還原。兩者最好分別記錄;關閉用戶端後,系統仍保留指向本機舊埠號的代理設定,就可能造成與核心設定無關的連線失敗。遇到這種情況,應先還原原本的流量接管方式,再比較檔案差異。

08 驗證與復原

分層驗證與復原

先確認設定檔讀取成功,再確認請求進入核心

開始排除問題前,記下目前的用戶端、實際核心、監聽位址、埠號、預設出口及測試目標。先儲存可正常運作的設定副本,再編輯候選檔案。如果核心拒絕啟動,先查看最早出現且明確指出欄位的錯誤:格式不合法、型別不符、協定不支援、缺少規則資料及埠號被占用,是不同問題。後續錯誤可能只是第一個問題造成的結果;先修正最前面的原因,再重新查看啟動記錄,不要一次修改多個模組。

啟動後,先使用明確設定代理的程式發出一個簡短請求。以下命令適用於使用基準檔案、已安裝 curl,且可直接連線至範例網站的環境;請將執行結果與相同環境下「不經此代理」的請求比較。兩個 SOCKS 參數的主要差別在於由哪一端處理目標網域,對照路由與 DNS 時特別有用。如果使用其他監聽埠號,請確保兩條命令使用相同設定,不要在改變目標的同時順手更改代理位址。

curl --socks5 127.0.0.1:10808 --max-time 12 https://example.org/
curl --socks5-hostname 127.0.0.1:10808 --max-time 12 https://example.org/

如果命令顯示無法連線至本機埠號,優先檢查核心是否正在執行,以及是否繫結到相同位址;如果已連上本機埠號,但代理協定交涉失敗,再確認應用程式使用的代理類型。如果明確設定代理後測試有效,但瀏覽器或終端機平常的操作無效,就回頭檢查應用程式的流量接管設定:瀏覽器擴充功能、系統代理與終端環境變數可能各自影響不同範圍。可參考系統代理排查,分別驗證瀏覽器與終端機。

使用短時間記錄追蹤單一請求

即使確認連線已到達核心,仍無法判斷去向時,可暫時提高記錄詳細程度。以下片段會取代整個頂層 log 物件,適合在基準設定副本中短時間觀察,不會指定持久化記錄路徑。用戶端如何接收及顯示核心輸出,取決於執行方式;提高記錄層級也不保證介面會列出每條規則的完整判斷過程。可依請求時間、目標、從入站到出站的記錄及錯誤階段,拼出完整的連線路徑。

{
  "log": {
    "loglevel": "info"
  }
}

只重現一次並清楚記下目標。如果目標以 IP 位址出現,就先不要修改網域比對運算式;如果記錄顯示流量進入預設出站,請核對是否有規則命中、標籤是否存在,以及第一項是否為預期出口。如果出口正確但連線失敗,接著檢查 DNS 或撥號。網域解析錯誤、連線遭拒及連線逾時不能互相替代:它們分別指向位址取得、目標監聽狀態或等待階段,後續應檢查的模組也不同。

測試新舊設定時,請保持目標、應用程式、入口協定、網路及所選節點不變,只替換待測檔案。每輪都重新建立連線,避免瀏覽器連線池與用戶端中的舊工作階段影響結果。如果問題只在長連線閒置一段時間後出現,對照測試也應等待相同時間;如果只在某一類名稱出現,請保留一個已知有效的名稱作為對照。若問題無法穩定重現,先記錄發生條件,比漫無目的地重新安裝用戶端更能保留排查線索。

分別復原設定檔與流量接管方式

如果候選檔案無法通過啟動或基本連線測試,請停止候選執行個體,還原先前的設定副本及應用程式所指向的本機埠號,再測試一個已知可用的目標。如果測試期間曾暫時啟用系統代理或虛擬網卡模式,也應一併還原原狀;這與替換 JSON 是兩項不同操作。確認應用程式已回到原本的連線路徑後,將記錄層級恢復平常設定,並移除測試時加入的額外監聽、固定主機對應及專用規則。

最後保留三類結果:應用程式是否進入指定入站、路由是否選中預期出站,以及出站是否成功連線至目標。每一類只記錄可觀察到的事實。分享記錄前,刪除目標詳細資料中不需要公開的內容。

如果復原後仍然失敗,不要繼續在候選檔案上疊加修改。重新進行基準測試,確認本機埠號、流量接管狀態及網路環境是否確實恢復原狀,再檢查是否有新程序占用埠號或使用舊檔案。若此時只想恢復日常使用,可回到入門指南,依序完成匯入、選擇模式與連線驗證;等基本連線路徑恢復後,再從本手冊相應章節查詢單一欄位。