設定欄位config.yaml

mihomo 設定欄位參考

先匯入設定、開啟流量接管並確認連線,依入門指南完整操作一次。已能連線,想知道某個鍵該放在哪一層,或更新訂閱後想找回自己的規則,就查閱這份手冊。範例從可獨立啟動的直連基礎設定開始;後續片段請依章節替換或加入,別把同名的頂層鍵拼在一起。

YAML 結構與最小設定

先分清映射、序列與純量

設定檔的最上層是一份欄位表。冒號左邊是鍵,右邊可以是值,也可以是下一層結構。連接埠號、模式名稱與布林開關都是單一值;dns 是子表;proxies、proxy-groups 和 rules 則是有順序的清單。節點清單中的每個項目仍是一份表,規則清單中的每個項目通常則是一整行字串。別因為節點和規則都以連字號開頭,就把節點屬性拆成數個獨立清單項目:這樣的 YAML 可能仍符合語法,卻不是核心需要的結構。

使用空格縮排,每層兩格最容易對齊;不要使用定位字元。請分清冒號後的空格與引號內的冒號:名稱本身若含有冒號加空格,整個值都要加上引號,否則解析器可能會把它當成另一組鍵值。井字號前有分隔空白且不在引號內時,後方內容會被視為註解。名稱中若真的要包含井字號或前導零,請替值加上引號;連接埠仍應寫成整數,開關則寫成 true 或 false,不必一律改成字串。

可獨立執行的直連基礎設定

config.yaml
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []
proxy-groups:
  - name: LOCAL
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,LOCAL

這份基礎設定不依賴訂閱、地理資料庫或遠端規則。請求會進入本機混合連接埠,規則以最後一行將流量送往 LOCAL,組內唯一的出口則是 DIRECT。此處的「直連」仍會經過本機核心,只是出口不經遠端代理。使用這份設定可先排除遠端服務、憑證與測速網址的影響。如果連這份設定都無法啟動,請先檢查執行目錄、設定檔權限及連接埠是否遭占用;換用更長的訂閱只會擴大問題範圍。

頂層鍵的書寫位置不代表執行順序。把 rules 移到檔案第一行,不會讓規則先於節點初始化。真正依賴排列的是清單內部,例如規則會由上而下比對,手動選擇組則依清單順序顯示成員。引用是依名稱查找,而不是依位置查找:範例中的 LOCAL 必須在規則和組定義中完全一致。編輯時最好搜尋這個名稱,確認所有引用位置,再一次更名。只改顯示名稱、不處理指向它的規則,會使設定中的引用失效。

空值、重複鍵與錯誤行號

proxies: [] 明確表示空清單。只寫一行 proxies: 而沒有子項,通常會解析成空值;空值、空清單和省略整個鍵並不相同,覆寫時尤其如此。不要在檔案尾端再加一個 rules:,試圖替前面的清單追加項目:有些解析器會拒絕重複鍵,有些實作則可能只保留其中一個值。擴充原清單時,請在原鍵下方新增項目,或使用用戶端提供的清單合併功能明確追加。

排錯從第一個錯誤開始。某行顯示找不到預期的冒號,原因可能是上一行漏了引號,或前一個區塊縮排不足;先檢查錯誤行前後幾行。語法解析成功後,核心還會檢查節點類型、目標名稱及欄位內容。編輯器能標示語法,不代表核心一定能載入;成功載入也不代表流量已進入代理。請保留一份可正常執行的基礎設定,之後每次只修改一個欄位區塊,才容易分辨是「結構寫錯」還是「結構正確但網路路徑不通」。

如果下載的是訂閱網址、編碼文字或用戶端專用分享連結,請先依匯入入口辨認,不要只改副檔名就交給核心。另一種常見檔案只包含 payload 或節點清單,是供其他欄位引用的資源,並非完整設定。先確認檔案開頭的結構,再決定要在用戶端新增設定、替換某個子表,還是將它設為提供器來源。介面顯示的設定名稱也不是磁碟上的檔案路徑;排錯時請確認目前編輯的是哪一份檔案。

通用欄位:監聽連接埠與執行模式

先確認入口,再決定出口

監聽連接埠決定應用程式要從哪裡送出請求;執行模式則決定核心收到請求後要往哪裡傳送,兩者是不同的設定。常用的 mixed-port 同時接受 HTTP 代理和 SOCKS 連線,適合只替本機應用程式設定一個入口。port 僅提供 HTTP 代理入口,socks-port 則僅提供 SOCKS 入口;需要區分呼叫方式時再啟用,別以為兩個監聽欄位填上相同連接埠就能自動共用。若用戶端會替核心指派連接埠,請以啟動記錄和介面顯示的實際值為準。

欄位用途排查起點
mixed-portHTTP 與 SOCKS 共用的連入端確認連接埠未遭占用,且應用程式設定指向實際監聽位址
allow-lan是否允許其他區域網路裝置使用代理入口僅在本機使用時請保持關閉
mode選擇規則、全域或直連模式排查規則時先切回 rule
log-level調整記錄詳細程度日常使用 info,排查時短暫提高詳細程度
external-controller設定控制介面,而非應用程式代理入口確有需要時才啟用,並限制在可信任的存取範圍內

本機應用程式通常填入回送位址 127.0.0.1 和混合連接埠。不要把控制介面位址填進系統代理:兩者都可能監聽本機連接埠,但提供的服務完全不同。控制介面可以讀取執行狀態並變更設定,不應公開暴露;僅供本機使用時,請綁定回送位址,並依用戶端提供的方式管理存取憑證。確實需要讓其他裝置使用本機代理時,再分別確認 allow-lan、監聽位址、防火牆與存取控制。能從本機連線,不代表同一網路中的其他裝置也一定能連線。

三種模式與介面狀態

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

rule 依規則順序判斷出口;global 使用全域策略所選的出口,不會逐條套用自訂分流;direct 則讓核心收到的請求直接連出。切換成直連不代表退出用戶端,系統代理或虛擬網卡可能仍在接收流量。使用全域或直連模式排錯時,請記下原本的模式和選擇,測試後再恢復。想深入了解三種路徑的差異,可參閱規則、全域與直連模式筆記中的情境說明。

設定中的 mode 是檔案裡的值,不一定等於目前介面上的狀態。用戶端可能在啟動後還原上次的操作,也可能先產生中間設定再交給核心。修改檔案後仍走全域模式,請先確認載入的是剛編輯的檔案,再查看介面是否仍選著全域模式。反過來說,在介面中暫時切換也不一定會寫回原檔。若要讓變更在訂閱更新和重新啟動後持續生效,請找到用戶端支援的持久化入口,而不是只修改執行階段狀態。

連接埠成功監聽,不代表系統已接管流量

系統代理仰賴應用程式讀取系統設定,通常適用於瀏覽器等支援代理的程式。虛擬網卡模式則從系統路由接收符合條件的流量,除了用戶端開關,還須考量權限、路由衝突與名稱解析。兩個開關同時開啟,不代表一定能接管更多流量;遇到某個應用程式無法連網,最好先只開啟一種方式,記錄入口、目標和結果,再切換另一種方式比較。更多機制差異請參閱TUN 與系統代理比較。

不同裝置的授權方式各異,不必照搬桌面版的系統代理設定步驟到手機。首次安裝可前往下載頁面依平台選擇安裝檔;想先使用圖形介面,可從首推的 Clash Plus 開始,其他選項再依用戶端實際支援的功能確認。連接埠遭占用時也別急著結束不明程序,先確認是否有另一個用戶端或舊版核心正在執行。若新設定改用了不同連接埠,記得同步修改瀏覽器、終端機或系統中仍指向舊連接埠的設定。

如果只想測試單一應用程式,讓它手動連到混合連接埠,比直接修改全系統設定更容易還原。這一步可以確認核心入口、規則與出口的完整路徑;成功後再啟用系統接管,若結果不同,就將排查範圍縮小到應用程式設定或系統路由。暫時提高記錄層級時,只重試一個明確的請求;看到連入、目標與出口後,就調回日常層級,否則大量並行請求會把真正有用的記錄往後擠。

DNS:上游解析、網域策略與增強模式

分開檢視解析請求與連線請求

網域解析回答「這個名稱對應哪個位址」,連線規則回答「這次存取要走哪個出口」。兩者在存取過程中會互相影響,但不是同一份表。dns.enable 會啟用核心的 DNS 模組;光靠這個開關並不會接管系統上的所有解析。瀏覽器內建的加密 DNS、系統快取和用戶端設定的 DNS 劫持,都可能改變請求路徑。排錯前請先確認由誰發起解析、解析結果是什麼,以及核心看到的是網域名稱還是已解析的位址。

dns:
  enable: true
  enhanced-mode: redir-host
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.google/dns-query
  nameserver-policy:
    '+.example.org':
      - 1.1.1.1

範例使用加密上游處理一般網域,並將 example.org 及其子網域交給獨立的解析器。default-nameserver 用來引導解析 DNS 上游本身的網域,通常應填入以 IP 表示的解析器;它不是一般網域解析失敗時通用的備援清單。若目前執行環境無法連線到範例中的公共解析服務,請改用目前網路允許且可直接連線的上游再測試。要確認策略是否命中,請選兩個請求比較:一個符合策略範圍,另一個不符合。

用戶端內建 DNS 與系統的「慣用 DNS」並非相同設定。若需要讓某個應用程式直接查詢核心的 DNS 監聽端,請另外設定 dns.listen,再讓應用程式確實將查詢送至該位址;只設定監聽端,不會自動把系統查詢導向該處。也別為求方便就將監聽位址設為所有介面,尤其是在共用網路中。排錯時,可先向指定解析器單獨查詢一次,再從原應用程式重現存取,避免把兩個入口的結果當成同一次測試。

如何選擇 redir-host 或 fake-ip

redir-host 會回傳實際位址,適合作為相容性排查的起點。fake-ip 則會為處理中的網域指派合成位址;核心收到後續對該位址的連線時,可透過映射找回網域,再依規則處理。合成位址不是目標伺服器的公開 IP,別將它複製到靜態主機表,也不要據此判斷遠端服務是否更換位址。如果應用程式繞過相應的接管路徑,或將合成位址交給另一台沒有映射資料的裝置使用,就可能出現解析成功、連線卻到不了目標的情況。

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.local'
  nameserver:
    - 1.1.1.1

這段設定會整體替換上一段的 dns 子表。過濾項目可讓指定網域不使用合成位址,常見原因是裝置探索或特定服務需要實際位址。過濾不代表網域會依直連規則處理,也不會因此取得多點傳送解析能力。如果區域網路服務仍無法開啟,請確認服務名稱是否有可用的本機解析方式,以及回傳位址是否路由至正確網段;切回實際位址模式比較時,也要考慮應用程式可能保留了先前的位址,必要時請重新啟動應用程式並再次查詢。

分開解析一般網域與節點網域

如果出口節點的 server 填的是網域名稱,節點開始連線前也必須先解析該名稱。可針對節點名稱設定 proxy-server-nameserver;使用依賴規則的 DNS 路徑時,尤其要確保節點解析有不依賴該節點連線的入口。否則就會形成循環:請求必須先經過節點,但節點又得等這次請求完成才能取得位址。若所有節點都逾時、直連位址正常但網域節點全數失敗,請先檢查這段相依關係,不要急著刪除並重建組內所有成員。

同一名稱回傳多個位址不一定代表故障;位址可能因地區、快取和記錄類型而異。更可靠的驗證方式是固定測試條件:使用同一個用戶端、同一種流量接管方式與同一個網域,記錄查詢入口、回傳的記錄類型及應用程式最後連線的位址。如果只有 IPv6 結果失敗,請確認系統和出口路徑是否都支援該位址類型;關閉某個解析選項最多只能改變回傳內容,無法取代對網路是否具備相應路由能力的判斷。

代理節點:通訊協定、遠端位址與提供器

節點是出口,不是本機監聽端

proxies 用來定義一批可供引用的出口。每個節點的 name 是設定中的引用名稱,type 決定後續欄位要依哪種通訊協定解讀,server 和 port 則描述實際要撥接的遠端端點。節點連接埠與本機的 mixed-port 沒有對應關係。若把用戶端的本機連接埠抄進節點項目,輕則無法連線,指回自身時還可能形成循環。填入設定前,請先向提供者確認通訊協定、位址和連接埠,不要只根據節點名稱中的地區或備註推測欄位內容。

proxies:
  - name: LAB-SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false

proxy-groups:
  - name: LAB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - MATCH,LAB

這組欄位可替換直連基礎設定中的三個同名頂層欄位。它要求本機另有一個受控的 SOCKS5 服務監聽在 1080;若沒有,就只能用組內的 DIRECT 進行比較。測試時先確認這個服務不是目前核心的另一個入口,也不會再將流量送回目前核心。此節點關閉 UDP,是為了讓初步測試只聚焦在 TCP。若應用程式確實需要 UDP,通訊協定能力、節點設定、伺服器支援及入口接管方式都必須同時符合要求。

節點名稱可以使用中文,但排錯時最好選擇穩定、簡短且容易搜尋的名稱。節點與節點重名,或節點與組同名,都會讓引用變得含糊,部分設定甚至會被核心直接拒絕。同一台伺服器若因通訊協定或連接埠不同而設定兩次,請分別命名,不要只靠清單順序辨認。訂閱定期變更顯示名稱時,也不要讓大量規則直接依賴單一名稱;先以穩定的本機組接收規則,再維護組內成員。

不同通訊協定的參數不可混用

不同通訊協定對驗證欄位的要求不同。例如 SOCKS5 可依伺服器設定填入使用者名稱和密碼;Shadowsocks 節點則應依伺服器提供的資料填入加密方式和密碼。不要為了補齊欄位,就把一種通訊協定的驗證區塊原封不動搬到另一種協定。使用 TLS 的節點也要確認伺服器要求的名稱、傳輸方式和相關選項;伺服器位址與 TLS 用來識別對端的名稱不一定相同。遇到交握失敗時,先核對通訊協定與伺服器資料,不要把放寬憑證驗證當成長期解法。

出口無法建立時,可從三類訊號判斷問題:節點網域解析失敗,通常會在交握前出現錯誤;目標連接埠無法連線,通常會遭拒或等待逾時;通訊協定或驗證方式不符,則常在連線建立後失敗。確認連接埠有回應,只能證明連到某個監聽服務,不代表服務接受目前使用的通訊協定。使用額外傳輸層的節點也應檢查相應路徑或服務識別資訊;只有伺服器明確採用相同設定時,這些選項才有作用。

使用提供器管理可替換的節點清單

proxy-providers:
  lab:
    type: file
    path: ./providers/lab.yaml

proxy-groups:
  - name: LAB
    type: select
    use:
      - lab
    proxies:
      - DIRECT

rules:
  - MATCH,LAB

本機檔案提供器可將組定義與節點來源分開。先在核心工作目錄下準備 providers/lab.yaml,檔案只需要包含上一個範例中的 proxies 區塊;主設定保留通用欄位,再使用上方這段定義組和規則。這裡的相對路徑是以核心工作目錄為基準,不一定是從 GUI 剛開啟的 YAML 檔案所在位置尋找。遇到路徑錯誤時,請先確認用戶端實際指定給核心的目錄,並確認執行核心的使用者有權讀取該檔案。

遠端提供器取得的內容也必須符合核心預期,並非任何分享連結都能當成節點清單網址。更新失敗時,先確認是下載過程出錯,還是取得的內容無法解析;後者可能是伺服器回傳了一般網頁。分享排錯資料時,請保留錯誤類型與欄位結構,並移除訂閱網址、驗證資訊及連線記錄中無關的個人位址。需要補充概念時,可參閱術語手冊中的訂閱、節點與策略組條目。

策略組:選擇、測速與故障切換

規則指向穩定的組名稱

策略組將「哪些請求走這裡」與「目前選用哪個出口」分開處理。規則引用組名稱,組再引用節點、其他組或內建出口。如此一來,更換節點只需調整成員,不必重寫所有網站規則。最容易檢查的結構是一層用途組加一層候選出口;需要再增加一層自動選擇時,也要維持單向關係。例如手動組可以引用自動組,但自動組不要反過來引用手動組,否則無法得出最終出口。

select 是手動選擇組,適合初次驗證、固定出口及保留備用選項。清單中的排列順序方便操作,但別把「排第一個」當成每次啟動時的強制選擇:用戶端可能會還原先前的狀態。排錯時,請在組介面中選取明確的成員,再從連線記錄確認實際使用的出口。將 DIRECT 放進組內也不代表會自動切換直連,它只是多了一個可手動選取的出口。

proxy-groups:
  - name: WEB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,WEB
  - MATCH,DIRECT

這段設定依賴上一章定義的 LAB-SOCKS 節點。它只會將指定網域送進手動組,其他請求則直接連出。手動切換成員後,請建立新連線進行驗證,不要期待既有工作階段會自動切換;瀏覽器可能重用連線,應用程式也可能維持長連線。如果介面顯示已選取其他節點,但行為沒有改變,請先中斷測試應用程式原有的連線,再確認新連線命中的規則與實際出口。如此才能分辨是選擇未儲存,還是連線尚未重新建立。

自動組的探測結果只代表該次探測

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,AUTO
  - MATCH,DIRECT

url-test 會利用探測網址比較候選出口,適合接受自動選擇的流量。此處的 interval 單位為秒,tolerance 單位為毫秒,用來減少延遲小幅變動造成的切換。介面顯示的是對指定網址進行一次或多次探測的結果,不代表實際服務網站的延遲,更不代表頻寬。範例將直連加入組內是為了方便實驗;若業務流量必須走代理,就不要把直連列為自動候選出口,否則可能因探測速度較快而被選中。

fallback 更接近依優先順序選擇目前可用的成員,而不是挑選延遲最低的成員。若要保留首選出口,請將常用成員排在前面,再列出備用成員,並設定這些成員都能穩定連線的探測網址。兩種自動組都會受到探測位址、連線逾時及排程間隔影響。如果探測位址無法開啟,但實際服務可正常存取,整個組的可用性判斷也會偏離需求。更換探測網址時,必須同時考量目標網路是否穩定,以及回應是否足以證明連線已建立。

成員來源與復原策略

proxies 用名稱引用已定義的節點或其他可選出口,use 則引入提供器中的成員。訂閱更新後節點名稱可能變動時,在組內使用 use 通常比硬編碼一長串名稱省事。兩種來源也可以並用,將固定的本機備用項與更新中的遠端候選放在同一組。組看起來有名稱卻沒有可選節點時,請檢查提供器是否已載入、清單中是否確實有節點,以及用戶端是否另外套用了篩選條件;不要只重新整理測速結果。

如果固定出口不穩定,請先決定可接受哪些備援方式,再選擇組類型。若需要保留登入工作階段或來源位址,手動組通常比頻繁比較延遲更合適;只有在首選出口失效後才要切換時,再使用故障切換。對於無法明確判斷的流量,不要讓組在未提示的情況下,把「使用備用代理」變成「直接連出」。保留手動比較組來測試新節點,等連線、解析與應用程式請求都確認正常後,再納入自動排程。發生異常時,也能迅速切回上一個明確選擇。

提供器的健康檢查與組本身的測速設定也應分開核對。節點在提供器中顯示可用,不代表它一定能從某個組的探測位址連線;反過來說,短暫錯誤也不表示應該將該節點從所有組移除。請選定相同的目標與傳輸路徑重新檢查,再判斷該修正的是候選清單、探測設定還是實際出口。記錄判斷依據,比記錄單次延遲數值更有用。

規則語法:比對順序、目標與資源集

第一條命中規則決定流量去向

在規則模式下,核心會由上而下檢查 rules,遇到第一條命中規則後就採用其目標,不會繼續尋找更精確的規則。大多數規則由類型、比對內容和目標組成,三者以英文逗號分隔;MATCH 不需要比對內容,只需指定出口。較具體的例外應放在範圍較廣的分類之前,最後才放兜底規則。不要依字母順序排列規則,也別把個人規則加在兜底規則之後:這些規則雖然寫在檔案裡,實際上卻沒有機會執行。

rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

這段可直接替換直連基礎設定中的規則清單,並保留其中的 LOCAL 組。第一行只比對完全相符的網域,第二行則涵蓋主網域及其子網域。即使兩個目標最後都直連,連線記錄仍可分辨是精確比對落在 DIRECT,還是後綴比對落在 LOCAL。若將兩行對調,精確網域就會先被後綴規則攔截。使用結構簡單的目標進行比較,可在排除遠端網路影響的情況下驗證規則順序。

網域規則填寫的不是完整網頁網址。不要加上通訊協定、路徑、連接埠或查詢參數;要比對的是核心看到的主機名稱,而不是瀏覽器網址列中的整串內容。重新導向後可能會存取新的目標,網頁也可能非同步呼叫其他網域;看起來像同一個頁面,記錄中卻會出現多條連線。每次只測試一個已知主機名稱,並在記錄中確認目標與命中規則。從其他地方複製規則時,也要留意全形逗號或不可見空格。

位址比對可能會觸發解析

IP-CIDR 用來比對 IPv4 位址範圍,IPv6 則使用 IP-CIDR6;GEOIP 依據位址與地理資料比對,並仰賴目前執行環境中的相應資料。這些都不是網域後綴規則。對網域目標而言,位址類規則可能需要先進行解析才能判斷;部分位址規則支援在結尾加上 no-resolve,用來避免為這條規則額外發起解析,但不代表已取得的目標位址不會被使用。若無法取得可供比對的位址,就不能假設位址規則一定會命中;後續規則仍須安排合理的去向。

如果同一項流量有時命中網域規則、有時命中位址規則,請先檢查發起連線的應用程式是否總以相同方式提供目標。有些應用程式會傳送網域名稱,另一些則直接連線至快取位址。同一網域可能解析出多個結果,依據地理資料判斷時,也會因實際位址或資料內容而改變。不要用地理分類取代業務網域清單:請先為重要服務設定明確例外,再以位址範圍或地理分類處理其餘請求,並透過記錄確認命中時實際取得的目標資訊。

外部規則需在提供器中宣告類型

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,LOCAL
  - MATCH,DIRECT

接著在核心工作目錄中的 rules/local-domains.yaml 寫入 payload 清單:

payload:
  - '+.example.net'

domain 資源集填寫網域運算式;ipcidr 用於位址範圍;classical 可包含帶有比對類型的傳統規則。行為宣告必須與檔案內容一致,且不要在提供器檔案中為每個項目另行指定出口;去向由主設定中的 RULE-SET 指定。RULE-SET 在清單中的位置同樣會影響優先順序;若私人例外規則要優先於資源集,應放在引用行之前,而不是更動資源檔案中的排列。

規則資源更新後若出現大範圍策略變化,請先比較資源類型、更新前後的比對範圍,以及主規則中的優先順序。可暫時使用工作目錄中的本機資源進行比較,以分辨是下載失敗、格式錯誤,還是真的命中了更廣的範圍。需要新增自訂分流規則時,請在前方插入範圍最小且有效的條件,接著各測試一個應命中和不應命中的請求。兩種結果都符合預期,才算驗證了規則邊界,而不只是證明「這次連得上」。

覆寫與合併:從訂閱檔案到有效設定

找到要修改的正確層級

圖形化用戶端通常會分別儲存遠端訂閱、個人覆寫、介面選擇及最後交給核心的檔案。手動修改訂閱快取,眼下可能有效,但下次更新就會被覆蓋;修改暫存輸出也可能在重新載入時遺失。若要讓個人規則不受更新影響,請先確認用戶端是否提供覆寫、擴充設定或指令碼入口,並查明套用順序。核心讀取的是處理後的結果,不會只因來源檔案出現「覆寫」字樣,就自動合併兩份檔案。

依欄位值的類型決定合併方式。連接埠和模式是純量,通常只能保留一個最終值;DNS 是映射,可以只修改其中一個子鍵,也可能被工具整份替換;規則和策略組則是序列,工具可能整段替換,也可能支援插入前方、追加至末尾或依名稱處理。YAML 本身並未規定用戶端如何合併兩份設定中的序列。使用任何工具前,先用兩行規則測試並檢查最終檔案中的順序,不要直接套用其他用戶端的覆寫欄位。

最好同時記錄覆寫項目及其用途。例如只需將某個網域導向本機組,就別一併複製連接埠、記錄設定和整份節點清單;這些無關欄位日後可能覆蓋上游變更。相反地,若要替換整份 DNS 設定,請先列出必須保留的解析上游與策略,避免連節點網域使用的專用解析入口也一起刪除。覆寫越精簡越容易檢查,但不能為了精簡而省略完整功能區塊所需的其他欄位。

透過輸入與輸出驗證合併規則

# 遠端設定原有規則
rules:
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT
# 加入一條前置例外後的有效規則
rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT

這兩段分別是輸入與預期輸出,不是可同時啟用的兩段設定。重點是例外規則位於後綴規則之前,原有兜底規則仍保留在末尾。若用戶端只支援替換規則清單,請使用完整的輸出清單;若支援前置項目,則只需在相應入口加入第一條例外。請交叉比對輸出規則與記錄,並確認輸出中的 LOCAL 仍有對應定義。修改策略組名稱時,也要確認覆寫程式沒有追加兩個同名組,而是取代原有組。

JSON 格式的內嵌清單與多行清單通常可以表達相同的值,但展開後更容易比對新增項目的位置。別為了美觀而讓工具自動排序規則;映射鍵排序通常只影響閱讀,清單排序卻會改變設定含義。刪除欄位時也要先分清「沿用原值」和「主動清空」:省略某個鍵通常表示不覆寫,空清單則可能表示覆寫成零個項目,實際情況仍須依工具規則而定。只留空的冒號,則可能讓核心收到非預期的空值。

錨點重用與更新後的回歸測試

YAML 的錨點和別名適合在同一份檔案中重用既有結構,並不是跨設定的匯入機制。映射合併寫法是否支援,取決於用戶端的前處理器和解析器;尤其不要用它來假設序列會逐項合併。若要將檔案交給其他用戶端使用,請優先保留已展開且可獨立讀取的版本。若記錄顯示找不到別名,請先檢查前處理是否移動或刪除了錨點,而不是先修改規則本身。

更新訂閱前,先保留一份上次可用的本機快照,並另外儲存個人覆寫。更新後先確認節點名稱和目標組仍可引用,再檢查清單是否變成空的,最後比對規則兜底、DNS 與執行模式。若回歸測試失敗,可先停用覆寫並單獨執行原訂閱,再啟用覆寫進行比較。如果兩次都失敗,問題未必出在合併;若只有啟用覆寫才失敗,就分區塊逐一還原,找出第一個改變行為的區塊。

保存有效設定以供比較時,別順手把含有驗證資訊的整份檔案貼到公開討論區。比較本機檔案時,著重檢查變更路徑、順序與引用關係;分享時只保留必要片段,並以一致的假名稱同時替換定義與引用。如此既能重現結構,也能讓協助排錯的人看出究竟是順序錯置、名稱重複,還是檔案產生後根本沒有重新載入。

驗證與排錯:從載入結果到連線記錄

先驗證設定,再確認監聽

命令列核心可先測試設定,不必直接替換目前正在執行的版本。將目前目錄切換至自己的測試目錄,並將有效設定存成 config.yaml;若使用本機提供器或規則資源,請依設定在相同測試目錄中準備子目錄。下列命令假設 mihomo 已在可執行檔搜尋路徑中,且可直接呼叫 curl。第一條命令請先單獨執行;成功後,在一個終端機啟動第二條命令,再於另一個終端機送出請求。

mihomo -t -d . -f ./config.yaml
mihomo -d . -f ./config.yaml
curl --noproxy "" --proxy http://127.0.0.1:7890 https://example.org/

不要讓圖形化用戶端和這份測試核心同時搶用相同連接埠。啟動前先退出占用該連接埠的程序,或替測試設定選用其他空閒連接埠,並修改命令中的數字。在某些環境中,curl 是終端機別名,可改用該平台上的實際可執行程式。明確指定代理的目的,是讓這次請求經由指定入口送出,減少系統代理設定和代理環境變數對測試的影響。若測試通過,只能證明這個入口能接受一次請求,不代表所有應用程式都會讀取相同設定。

設定測試失敗時,先確認是否找到檔案、有無語法解析錯誤,以及相依資源能否讀取。測試通過但啟動失敗,則著重檢查執行環境,例如連接埠衝突、權限不足,或實際工作目錄與測試時不同。能啟動卻無法連線,才開始排查連線路徑。此階段記錄一筆完整錯誤就足夠;重複出現的同類錯誤通常只是應用程式不斷重試,不代表設定中同時有十幾處錯誤。

利用連線資訊縮小故障範圍

現象優先檢查下一步
代理連接埠連線遭拒核心是否在預期的位址和連接埠監聽比對啟動記錄與應用程式設定
應用程式有送出請求,核心卻沒有記錄應用程式是否確實經過代理入口分別測試明確指定代理與系統接管
有記錄,但命中的目標不正確模式、規則順序與實際目標確認組目前的選擇及生效設定
命中代理後仍逾時節點解析、連線與遠端交握切換單一成員後重試,並記錄出錯階段

沒有連線記錄時,不要先修改 DNS 策略或替節點新增參數。先用明確指定入口的請求進行比較;如果這樣能命中,問題更可能是應用程式沒有讀取系統代理設定,或接管入口沒有收到該程序的流量。瀏覽器和終端機要分開排查:前者可能使用代理擴充功能,後者可能讀取環境變數或工具本身的設定。詳細步驟請參閱系統代理未生效:瀏覽器與終端機排查。

已有記錄但流量去向不符時,請記下模式、目標名稱、命中規則和最終出口這四項。例如規則指向自動組,不代表出口一定是預期的代理;實際選中的可能是列為候選的直連。若只有舊工作階段狀態異常,請關閉該工作階段後重新連線;若新工作階段仍可穩定重現,再檢查執行階段選項是否覆蓋檔案中的設定。請以當次連線記錄為準,不要只根據上一輪測試的面板截圖下結論。

將驗證流程整理成可重複執行的回歸測試

每次修改後至少保留三種比較:應直連的目標、應命中自訂規則的目標,以及應落到兜底規則的目標。先確認最小設定可以執行,再依序加回節點、策略組、DNS 和外部資源;每一步出錯都能追溯到剛加入的部分。遇到偶發故障時,記錄當時的網路環境與入口類型;從有線網路切換到無線網路,或從桌面裝置換成手機時,系統接管方式和上游解析都可能改變,不能直接把兩次結果當成相同條件的比較。

如果首次匯入設定時就失敗,可先回到入門指南,依序確認匯入、模式與連線。若已定位到特定欄位,請記錄預期行為、實際行為及最小設定片段,再單獨重現問題。恢復正式環境前,請還原暫時提高的記錄詳細程度、測試連接埠及臨時接管設定。如此下次遇到「改完就無法上網」,就能從最後一份有效設定和可重現的請求開始,不必重新猜測。

最後別忘了分別比較重新載入與重新啟動後的結果。前者可確認核心是否接收檔案變更;後者則用來確認用戶端是否還原舊選擇、重新產生設定,或在啟動時重新取得訂閱。若兩次結果不同,請記錄變化實際發生的階段,並回到覆寫與合併檢查來源。長期維護時,最有用的不是留下更多除錯輸出,而是知道哪份檔案可還原、哪個請求能重現,以及哪條規則應該命中。