Clash 設定檔參考
本頁供查閱欄位、核對引用,以及了解核心實際載入的設定。初次安裝或匯入訂閱,請先看快速入門教學;確認連線正常後,再回到本手冊調整設定。以下內容以 mihomo 為準,涉及外部服務的範例會註明執行條件。
YAML 結構與設定入口
頂層欄位、映射與列表
核心接收的是一份以映射為根節點的 YAML 文件。連接埠和模式以頂層鍵表示;DNS 是一個映射,解析器位址則是該映射下的列表。節點、策略組和規則也各自有頂層鍵。判斷欄位應放在哪裡,先找出它的父層,再確認父層接收的是鍵值對還是列表。只把欄位縮排到看起來接近其他設定的位置,不會讓它自動歸入正確的模組。
同一層的欄位請使用相同縮排,建議每層縮排兩個空格。列表項目以連字號開頭,後面空一格。列表中的每個節點都是一筆記錄;節點名稱、類型和位址屬於同一筆記錄,不能拆成三個列表項目。規則則不同:每條規則通常是一行字串。逗號分隔的是規則字串內的欄位,不能因此拆成多個 YAML 列表項目。
數值連接埠請寫成數字,開關請使用 true 或 false,不要一律加上引號。名稱或較長的參數可以加引號;值中若有可能被解讀為註解或鍵值分隔符號的字元,尤其要保留引號。例如,未加引號的名稱若在空格後緊接井字號,井字號後的文字可能會消失,策略組引用該名稱時便找不到目標。空列表 [] 和空映射 {} 也是不同的值。
最小基準設定與名稱引用
以下基準設定只開放本機混合代理連接埠,所有經此入口的流量都使用內建直連出口。它不依賴訂閱或額外資源,適合先確認本機能否透過代理入口連上原本就可存取的網站。這份設定不是加密代理方案,也不會改變未接入核心的應用程式流量。若本機已有其他用戶端占用該連接埠,請先改用閒置連接埠,並同步更新測試端的設定。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
從這份基準設定增加策略時,可以沿著資料關係逐步檢查:規則引用策略組,策略組引用節點、其他策略組或內建出口,節點則描述實際的連線方式。規則也可以直接指向內建出口。引用是依名稱綁定,不是依列表中的位置。修改節點名稱時,請檢查所有策略組;修改組名時,還要檢查規則及其他引用該組的策略組。名稱相似但多一個空格,也不算相同物件。
訂閱、設定檔和代理提供器的內容不一定能互換。用戶端的訂閱匯入功能可能會取回並處理完整設定,也可能依照自身規則產生最終設定。代理提供器載入的是供策略組挑選的節點集合;只有節點列表,不代表具備頂層監聽設定和規則。複製內容前先確認根鍵。若根鍵是 payload,還要確認它屬於哪一類資源,不能直接當成主設定啟動。
區分來源設定與實際生效設定
使用圖形介面用戶端時,至少要區分訂閱原始內容、本機覆寫,以及交給核心的最終設定。介面開關可能參與產生最終檔案,也可能透過執行階段介面修改核心狀態。若訂閱更新後手動修改的內容消失,通常應將自訂項目移至用戶端支援的覆寫位置,而不是一再編輯快取檔案。請依使用的用戶端確認操作入口;初次挑選用戶端可從安裝套件頁面的首選項目 Clash Plus 開始。
中文註解可以說明修改目的,但核心不會靠註解解決引用衝突。同一映射中不要重複使用相同鍵名。部分解析器會直接報錯,另一些則可能只保留其中一個值。重複寫兩段規則不會自動追加;應整理成單一列表,並依預期的比對順序排列。儲存後先檢查實際結構,再確認介面選取了正確的設定。
只靠編輯器的色彩標示判斷是否合法並不可靠。語法上色可以指出部分縮排和引號問題,卻不知道組名是否已定義,也不一定知道目前核心支援哪些欄位。遇到載入錯誤時,先從錯誤位置往上找最近的父鍵,確認列表層級和欄位類型;語法檢查通過後,再檢查實際引用。如此可避免同時修改拼字和策略,最後無法判斷是哪一步修正了問題。
通用連接埠、監聽範圍與運作模式
選擇入口並確認實際監聽狀態
連接埠欄位描述核心在本機接收請求的入口,不是遠端節點的服務連接埠。混合連接埠可接收 HTTP 代理和 SOCKS 請求,適合兩種應用共用同一個位址。若應用明確要求各自使用獨立入口,可以分別設定 HTTP 和 SOCKS 連接埠。多個監聽入口應使用不同連接埠,不要把三個欄位都設成相同數值。
| 欄位 | 控制對象 | 檢查重點 |
|---|---|---|
mixed-port | HTTP 與 SOCKS 混合代理入口 | 應用程式仍須選擇符合自身需求的代理協定。 |
port | HTTP 代理入口 | 透過代理連線至 HTTPS 網站,不代表本機入口要設定為 HTTPS 代理。 |
socks-port | SOCKS 代理入口 | 確認應用程式傳送的是目標網域名稱,還是已解析的位址。 |
allow-lan | 是否允許區域網路裝置連線至本機代理入口 | 僅供本機使用時設為 false。 |
bind-address | 允許區域網路連線時的綁定位址 | 需要共用時,請明確選擇介面位址並檢查存取範圍。 |
external-controller | 核心控制介面 | 它不是代理連接埠,也不應與代理入口一併對外開放。 |
以下範例為兩種入口分配不同連接埠。若用戶端已接管這些欄位,請在介面中設定對應值,或檢查覆寫後的最終檔案。設定中出現連接埠號碼,不代表程序已成功監聽。舊執行個體仍在執行、位址已被其他工具占用,或系統限制程序監聽,都可能導致連接埠無法使用。發生連接埠衝突時,先找出占用中的程序,再決定要關閉舊執行個體或更改連接埠。
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
本機應用程式通常填入迴圈位址 127.0.0.1,再填上該協定對應的連接埠。驗證時先查看監聽記錄,再用可手動設定代理的應用程式送出請求。如果該應用成功連線,而其他應用沒有連線記錄,請優先檢查其他應用是否使用系統代理,或是否有自己的代理設定。不要只看代理圖示亮起,就認定所有應用都已透過相同入口連線。
用戶端的系統代理開關通常會寫入系統層級的代理設定,是否採用則由應用程式決定。TUN 是在網路介面和路由層接管指定流量,通常還需要系統授權。兩者處理的是流量如何進入核心;流量進入後選用哪個出口則是另一回事。單獨修改 mode 不會啟用系統代理,也不能取代 TUN 的介面設定。初次排查問題時,請先固定使用一種接入方式。
區分規則、全域與直連模式
rule 模式會依規則順序選擇出口,適合有明確分流需求的設定。global 模式使用全域選擇,不會逐條比對規則列表;使用前請確認用戶端目前選取了哪個出口,不要預設流量一定經過某個遠端節點。direct 模式則會讓已進入核心的流量直接連線;這不代表關閉本機監聽,也不代表還原系統代理設定。
同一網站在規則模式與全域模式下結果不同時,先查看兩次連線記錄中的實際出口。全域模式下連線成功,只表示當次選用的路徑可用,不能據此判定整份規則有誤。也可能是規則命中直連、引用的策略組選了不同項目,或兩次使用了不同的網域解析結果。以直連模式測試時,請留意該網站是否允許目前網路直接存取。
平時建議將記錄層級維持在 info。排查問題時可暫時提高至 debug,重現一次後再調回原設定。記錄中的目標位址和設定名稱可能透露使用環境,分享時請只截取與問題相關的內容。請分辨「請求抵達入口」、「規則選中出口」和「遠端完成連線」這三個階段;只完成第一步時,不能直接將問題歸因於目標網站。
界定本機與區域網路的存取範圍
需要其他裝置連線時,再考慮啟用區域網路存取。遠端裝置應使用執行核心的主機在區域網路中的位址,不能填入遠端裝置自己的迴圈位址。開放前先確認使用的介面和防火牆範圍,測試完畢且不再需要時請關閉。控制介面應另外評估:能透過代理存取網路,不代表呼叫端也需要控制核心。排查本機連線問題時,不要把代理和控制連接埠都改成監聽所有介面。
有意更改連接埠後,也要檢查系統代理、瀏覽器個別設定和終端機環境變數是否仍保留舊值。若重開機前可用、重開機後卻無法使用,請記錄前後的實際監聽位址和設定名稱,並確認啟動的是同一個執行個體。系統設定入口與平台授權的差異,可先參考快速入門,再回到這裡對照核心欄位。
DNS 欄位與 fake-ip 行為
確認 DNS 查詢是否經由核心解析
在設定中啟用 DNS,代表核心會啟用自己的解析模組;僅靠這個開關,不會接管作業系統上的所有 DNS 查詢。瀏覽器可能使用自身的加密 DNS,應用程式也可能將解析後的位址交給代理。系統代理和 TUN 的接入方式不同,能否接收 DNS 請求也取決於具體設定。排查前先確認是哪個應用程式發起查詢,以及查詢實際進入哪個解析器。
DNS 設定中的 nameserver 是一般網域使用的解析器列表;nameserver-policy 可為指定網域選擇解析器。default-nameserver 用於啟動階段解析 DNS 伺服器主機名稱等引導情境,並不是逐一嘗試所有請求的備用列表。使用主機名稱作為加密解析位址時,請確保引導解析器在目前網路中可連線,否則設定雖能載入,第一次查詢仍可能逾時。
proxy-server-nameserver 用於解析代理節點的伺服器網域名稱。它解決的是「尚未連上節點時,如何先取得節點位址」的問題,與一般網站解析不同。如果節點使用網域名稱,而解析它所需的上游又只能透過該節點存取,就會形成循環依賴。遇到這種情況時,先為節點位址準備一條在建立連線前確實可用的解析路徑,再決定一般網站查詢要走哪條路徑。
位址映射、過濾與本機查詢範例
在 fake-ip 模式下,核心可以為收到查詢的網域指派一個虛擬位址,並保存網域與該位址的映射。連線以該位址回到同一個核心時,核心有機會還原網域,並依網域規則進行判斷。這個虛擬位址不是目標伺服器公開的真實位址,也不能脫離目前核心中的映射單獨使用。如果查詢經過核心,後續連線卻直接交由系統路由處理,應用程式可能會嘗試連線至無法到達的虛擬位址。
mixed-port: 7890
allow-lan: false
mode: rule
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- 'localhost'
- '+.lan'
nameserver:
- system
rules:
- MATCH,DIRECT
範例在迴圈位址開放獨立的 DNS 連接埠,並將一般查詢交給系統解析器。這適合手動將測試查詢送至該連接埠,不會替你修改系統 DNS。使用此範例時,請確保系統解析器不會把查詢重新送回這個監聽入口。如果已有工具使用相同連接埠,請先改用閒置連接埠。也請確認虛擬位址範圍沒有與本機現有路由或其他代理執行個體的虛擬網段衝突。
在範例的預設過濾行為下,fake-ip-filter 會將列出的名稱排除在虛擬位址指派之外。將某個本地域名加入列表,解決的是「需要取得真實解析結果」的問題,不會憑空建立該網域的記錄。如果某個內部後綴必須由組織的解析器回覆,還要確認系統解析能回傳該網域,或為該後綴另行設定可連線的解析器,並驗證路由允許存取該解析服務。
另一種增強模式是 redir-host,通常會回覆應用程式真實位址。是否仍能命中網域規則,取決於網域資訊是否隨代理請求傳送,或核心能否從實際接入路徑取得資訊。切換模式並不能解決所有網域比對問題。請同時檢查相同目標的 DNS 回覆和連線記錄;只有前者改變,不能代表後者已命中預期規則。
區分解析失敗、快取與後續連線失敗
如果系統有支援指定伺服器與連接埠的查詢工具,可以執行以下兩項查詢。第一項明確使用範例中的監聽端點;第二項使用工具預設的系統解析路徑。請記錄回覆狀態和位址類型,不必要求兩邊的位址值相同。在虛擬位址模式下,結果不同可能是預期行為。若監聽端沒有收到請求,先排查使用的位址和連接埠,不要急著更換上游解析器。
dig @127.0.0.1 -p 1053 example.com A
dig example.com A
若有收到回覆但連線仍失敗,請確認連線是否進入保存映射的同一個執行個體,再查看網域規則、策略組和出口記錄。切換設定後,瀏覽器和作業系統可能仍使用快取位址,已建立的連線也可能持續沿用。請用新連線重新測試,必要時只清除測試應用程式的相關狀態。每次只改一個因素,避免同時切換 DNS、啟用流量接管和更換節點。
啟用雙堆疊的環境也應分別觀察 IPv4 與 IPv6。DNS 的 ipv6 選項控制核心 DNS 對 IPv6 查詢的處理方式,不等於停用系統的 IPv6 堆疊,也不能取代對 IPv6 接入路徑的檢查。診斷時請記錄查詢類型與實際目標位址;其中一種位址族連線成功,不代表另一種也使用相同策略和路徑。
代理節點欄位與提供器
依協定設定一筆出口記錄
proxies 是節點記錄的列表。常見記錄包含名稱、協定類型、伺服器和連接埠,協定專用欄位則依實際服務填寫。名稱用於引用和顯示,位址與連接埠決定連線目標。位址應填主機名稱或位址本身,不能填入含有通訊協定和路徑的訂閱連結。訂閱位址用於取得或產生設定,節點位址則用於建立一條出口連線;兩者在載入流程中負責不同工作。
以下範例將節點連接至既有的本機 SOCKS 服務。需要另一個 SOCKS 服務已在本機 1080 監聽,且允許此用戶端存取;使用範例不必修改該服務。核心接收入站流量的連接埠是 7890。不要把該節點的服務連接埠改成同一個核心的混合入口,否則請求可能從出口折返入口,造成重複處理或連線失敗。
mixed-port: 7890
allow-lan: false
mode: rule
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
rules:
- DOMAIN-SUFFIX,example.com,Local-SOCKS
- MATCH,DIRECT
此範例只會將符合範例網域的連線導向該節點,其他連線仍會直連。如果沒有現成的 SOCKS 服務,可以先依照最小基準設定驗證入口;不要把節點範例失敗誤認為 YAML 載入失敗。節點出現在用戶端列表中,只代表記錄已載入。要確認節點是否可用,請分別確認位址可連線、協定交握成功,以及目標請求經由該出口完成。三個步驟中任何一個失敗,都可能在介面上只顯示逾時。
切換協定時,不要只修改 type,卻沿用所有舊欄位。以 Shadowsocks 為例,密碼和加密方法必須與伺服器一致;採用 TLS 的其他協定還可能需要服務名稱、憑證驗證和傳輸方式等設定。設定結構相似,不代表交握方式相容。遇到憑證錯誤時,先核對服務名稱、系統時間和伺服器憑證,不要把關閉驗證當成一般修復方式。
udp 用於宣告部分節點是否啟用 UDP 轉送,不會讓不支援 UDP 的服務自動具備這項能力。應用程式能透過節點瀏覽網頁,只能證明該次網頁連線成功,不能推論語音或其他 UDP 應用也能使用。排查時應同時檢查入口是否承載這類流量、策略是否選到相容出口,以及伺服器是否能實際轉送。不要用網頁能否開啟取代協定層檢查。
代理提供器的路徑與載入順序
有一批獨立維護的節點時,可以使用 proxy-providers。主設定宣告資源來源,策略組則透過 use 引用提供器名稱。以下示範本機檔案方式;請事先在核心工作目錄建立指定檔案。範例沿用前述的獨立 SOCKS 服務,實際接入前仍須確認該服務已啟動。若找不到檔案,請先修正相對路徑或確認啟動時使用的工作目錄。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-providers:
local-source:
type: file
path: ./local-proxies.yaml
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
use:
- local-source
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
開啟策略組,確認提供器的成員已出現,再手動選取它。不要只看規則記錄顯示了組名;如果組內目前選取的成員仍是直連,就還沒驗證節點。若改用 HTTP 提供器,請確認取得的是核心可辨識的節點資源,而不是登入頁面或另一份完整設定。提供器的工作路徑和更新週期應分開管理,避免多個資源共用同一個快取檔案。
檢查資源更新時,請分別記錄「下載成功」、「解析成功」和「成員可用」。更新可能移除原有成員,也可能以同名記錄取代伺服器參數。若手動選取的成員在更新後消失,先查看提供器的新成員列表,再確認策略組目前的選擇;不要只拿舊截圖比對。分享設定片段時,請移除訂閱位址、認證欄位和內部主機名稱,只保留能說明結構的欄位。
策略組類型、成員與健康檢查
策略組負責選擇出口
proxy-groups 定義出口選擇策略,不會建立新的代理協定。組名是規則引用的目的地,成員可以是單一節點、內建出口、其他策略組或來自提供器的節點。策略組能讓規則維持穩定:替換或調整成員時,不必同步修改引用該組的規則。請先明確界定策略組的用途,再決定成員來源;不建議用只差一個字元的多個組名代表不同用途。
| 類型 | 選擇方式 | 注意事項 |
|---|---|---|
select | 由使用者選取成員 | 確認用戶端是否還原上次手動選取的項目。 |
url-test | 依探測結果選取成員 | 探測位址、探測週期和切換容差都會影響選擇。 |
fallback | 依列表優先順序選取可用成員 | 主要與備援的順序由成員列表決定,不會依延遲由低到高排序。 |
load-balance | 依設定的策略分配連線 | 連線可能使用不同出口,請確認應用情境是否要求固定出口。 |
靜態成員寫在 proxies 下,內容是已宣告的名稱,不是將整筆節點記錄再次嵌入策略組。提供器寫在 use 下,內容是提供器名稱,不是資源位址。把節點名稱寫進 use,或將提供器名稱誤寫在 proxies,都是引用層級錯誤。移轉設定時,先保留一個精簡的靜態策略組驗證引用,再逐步加入提供器成員。
以下範例沿用上一章的 Local-SOCKS 節點;請將原檔的規則列表替換成這裡的規則,並在頂層加入策略組定義。此例保留直連作為手動比較選項。預設比對規則放在最後,確保只有選定網域會進入手動策略組。測試時分別選擇兩個選項並建立新連線,比較記錄中的最終成員是否隨選擇改變。
proxy-groups:
- name: PROXY
type: select
proxies:
- Local-SOCKS
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
巢狀策略組適合將自動選擇放在手動入口下方,例如讓手動組同時包含自動組和固定節點。引用方向必須清楚可追蹤,不能讓甲組引用乙組,而乙組又引用甲組,也不能引用自身。遇到循環引用時,先畫出「外層組指向內層組」的關係,從每條規則的目標一路追到節點或內建出口;若再次遇到已走過的同一個組,就應調整結構。
探測結果不能取代實際使用情境驗證
若要將前面的手動組改為主備組,可使用以下組定義,規則仍引用同一個組名。interval 的單位是秒。範例使用公開的文件網域說明探測欄位的寫法;實際使用時,請選擇裝置獲准存取且回應穩定的探測位址,並確認各個候選出口都能正常連線。探測測量的是對指定位址送出請求的結果,不代表整個網際網路都可用。
proxy-groups:
- name: PROXY
type: fallback
proxies:
- Local-SOCKS
- DIRECT
url: https://example.com/
interval: 300
此處使用直連作為備援,只用來比較行為。如果某項業務要求固定使用特定出口,就不應將直連加入策略組作為自動備援;候選項目全部無法使用時,應依業務需求處理失敗。也不要只為了看到更多可用結果,就把用途不同的出口混在同一個組裡。策略組是否可用,不只取決於是否有成員能連線,也取決於該成員是否符合目標存取條件。
為 url-test 策略組設定切換容差,可減少探測時間些微起伏造成的頻繁切換。探測間隔太短會增加額外請求,也更容易把偶發波動誤判為穩定差異。若單次測試發現某個成員較慢,請先觀察差異是否持續,再確認應用目標的問題能否重現。探測成功但應用程式失敗時,請比較兩者的網域、協定和最終出口,不要先縮短探測週期。
提供器也可以設定自己的健康檢查。排查時應分別確認「資源中有哪些成員」、「各成員的探測狀態」以及「策略組目前選取的成員」。策略變更通常只影響新連線;應用程式若維持舊工作階段,不會立即顯示變化。若用戶端啟用了選擇記憶,重新載入設定後也可能恢復先前的成員。必要時重新建立工作階段,並以該次連線記錄為準。
規則語法、比對順序與規則集
從第一條命中的規則開始檢查
在規則模式下,核心會依列表順序檢查規則,並採用第一條符合條件的結果。常見語法是「類別、比對條件、目標」,部分類別還能指定其他選項。MATCH 不需要比對條件,只需指定目標。範圍寬廣的規則若排在前面,後續較具體的規則可能永遠不會命中;因此應將例外排在通用規則之前,並確認列表末尾的預設規則符合預期。
以下範例不依賴遠端節點,而是透過直連和拒絕來區分幾種情況。完整名稱比對會優先直連,同一後綴範圍內的其他名稱則會命中拒絕規則。目標為迴圈位址的連線若命中位址規則,就會直連;其他請求則由預設規則處理。範例只會影響進入該核心的請求;直接依系統路由送出的流量,不會因設定中有拒絕項目就受到攔截。
mode: rule
rules:
- DOMAIN,example.com,DIRECT
- DOMAIN-SUFFIX,example.com,REJECT
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- MATCH,DIRECT
DOMAIN 檢查完整網域名稱;DOMAIN-SUFFIX 用於該網域及其子網域,不是任意比對字串結尾。若只想影響單一主機名稱,請勿改用後綴規則,以免連同相同主網域下的其他服務一起受影響。DOMAIN-KEYWORD 依關鍵字比對,涵蓋範圍更廣;使用前最好先檢查其他含有該關鍵字的名稱,再決定是否採用。
IP-CIDR 用於 IPv4 位址範圍,IPv6 則使用 IP-CIDR6。需要目標位址的規則若只收到網域名稱,核心可能必須先查詢位址。no-resolve 用於避免只為這條規則額外發起解析,不會清除請求中已有的目標位址,也不是停用全域 DNS 的指令。若規則命中需要依賴解析,請先確認該規則是否允許解析,再確認解析結果是否落在指定網段內。
GEOIP 和 GEOSITE 分別依賴核心可讀取的地理位址資料和網域分類資料。它們表示資料中的分類結果,不是即時測量連線位置或歸屬。兩個環境若使用不同資料檔案,即使規則文字相同,命中結果也可能不同。排查這類差異時,請記錄資料來源和用戶端啟用的設定;不要用單一網站的行為推論整份分類表。
將規則資料與處理動作分開
一批比對條件需要獨立維護時,可以使用 rule-providers。主檔案透過 RULE-SET 指定規則集及其處理動作,資源本身只宣告比對條件。以下本機範例使用網域集合,將指定網域及其子網域導向直連。請先建立檔案,再載入設定;相對路徑應以核心工作目錄為準,不要依編輯器目前開啟的目錄猜測。
mode: rule
rule-providers:
reference-domains:
type: file
behavior: domain
format: yaml
path: ./reference-domains.yaml
rules:
- RULE-SET,reference-domains,DIRECT
- MATCH,REJECT
payload:
- '+.example.com'
此組範例的最後一條規則會拒絕列表中未列出的目標,只適合用於刻意測試允許範圍的設定,不應直接取代日常使用的規則。behavior: domain 接收網域形式的條件;ipcidr 用於位址範圍;classical 可承載由規則類別與參數組成的條件。不要把 DOMAIN-SUFFIX,example.com,DIRECT 整行放進網域集合,也不要把出口名稱寫進由主檔案統一指定動作的條件中。
用連線記錄確認命中依據
發現目標落入預設規則時,先查看用戶端記錄的目標是網域名稱還是數值位址。若應用程式自行解析後只傳送位址,網域條件可能沒有可用的比對資訊;這不是單純調整規則順序就能修正的問題。接著確認前方是否有範圍更廣的規則,最後確認規則集檔案已成功載入。若連線記錄已顯示正確的命中規則,接下來應檢查策略組成員和出口,不必再調整比對條件。
一個網頁可能同時連線至主文件、靜態檔案和其他服務,每條連線都會獨立比對規則。主文件能開啟,不代表頁面上的所有資源都使用相同出口;某個資源失敗,也不一定需要修改整個主網域的規則。先選一筆失敗連線,記錄目標、命中規則和最終成員,再決定是否新增例外。需要依術語尋找欄位時,可參考名詞解釋中的分流規則分類。
覆寫、合併與更新後的差異
先確認由誰執行合併
覆寫是用戶端產生最終設定的流程,不是核心看到兩個同名鍵就會自動執行的通用操作。不同用戶端對映射、列表和空值的合併方式可能不同,也可能分別提供介面覆寫和指令碼處理功能。修改前先確認使用哪個入口,以及它套用於單一設定還是所有設定。第三方教學中專供覆寫使用的鍵,不能直接放進主 YAML 當作核心欄位。
建議將變更分為純量、映射和順序敏感的列表。連接埠與模式通常只需替換單一值;DNS 是映射,整區覆蓋可能會刪除原有的解析器或過濾項目;規則是有序列表,追加、置頂和整份替換的結果都不同。即使用戶端標示「深度合併映射」,也不能據此推論它會追加列表。檢查時應以實際輸出為準,不是看覆寫檔有多少行。
| 資料類型 | 修改範例 | 確認結果 |
|---|---|---|
| 純量 | 將 mixed-port 改成其他閒置連接埠 | 最終設定、實際監聽連接埠和應用程式的連線目標一致。 |
| 映射 | 修改 dns.enhanced-mode | 需要的解析器和策略映射仍然保留。 |
| 有序列表 | 在 rules 中加入例外規則 | 例外規則排在涵蓋其範圍的舊規則之前。 |
| 物件列表 | 為 proxy-groups 新增一個策略組 | 原有策略組仍存在、名稱不重複,且所有成員引用皆有效。 |
以下展示修改前後的完整檔案。目標是調整混合連接埠,並讓範例網域在預設規則之前命中拒絕。這裡提供的是人工合併後的結果,不依賴特定用戶端理解某種補丁語法。即使用戶端能產生相同內容,也要確認輸出中只有一份規則列表、例外排在第一條,而且原有模式和監聽範圍沒有變更。
mixed-port: 7890
allow-lan: false
mode: rule
rules:
- MATCH,DIRECT
mixed-port: 7892
allow-lan: false
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,REJECT
- MATCH,DIRECT
如果用戶端只支援將新規則追加至現有列表,前例新增的規則就會排在 MATCH 後方,因而無法命中。請改用明確支援置頂的功能,或整理完整規則列表後整份替換。採用整份替換時也必須自行維護:訂閱新增的重要規則不會自動加入這份自訂列表。更新後應重新比對上游規則,不要只確認設定仍可啟動。
重新命名、空值與 YAML 合併鍵
新增策略組前,先確認名稱沒有衝突。若覆寫器依名稱合併物件,同名策略組可能會取代舊組;若只會追加物件,結果則可能出現無法載入的重複組名。刪除節點、策略組或提供器前,應逐一搜尋對應引用。規則目標若是原有組名,只要保留同名策略組並提供有效成員,就不必同步修改所有規則;若刪除策略組本身,則必須移轉相關引用。
帶有空值的欄位也要分辨清楚。鍵後留空通常會解析為 null,不代表「沿用原值」;空列表也不會自動代表「不修改」。覆寫器可能將它們解讀為清除、取代或無效輸入,不支援時甚至可能直接拒絕。若目標是保留訂閱中的欄位,通常應從覆寫檔省略該欄位,再核對最終檔案;不要用空值表達尚未確認的合併意圖。
YAML 錨點與別名只適用於單一 YAML 文件的解析範圍,無法讓獨立的覆寫檔共用訂閱原文中的錨點。部分解析器支援 << 合併鍵,但它主要用於合併映射,不是串接規則列表的運算;用戶端讀取並重新輸出時,也可能展開或改變這種寫法。若需跨平台維護,請優先保留簡單結構,並以最終匯出的標準 YAML 作為核對依據。
將訂閱更新視為重新產生設定
更新訂閱前,先保留上次可用的最終設定和本機覆寫,並分開存放。更新後先比對頂層連接埠和 DNS 映射,再檢查節點、策略組和規則三類引用,最後對同一目標重新測試。若某次更新導致問題,可以先暫時停用覆寫,用原始設定驗證,再一次只啟用一項本機變更。如此便能分別找出來源資料、用戶端合併和執行階段選擇的差異。
移轉至其他用戶端時,也只移植能確認含義的核心欄位。同樣使用 mihomo 核心,不代表兩個介面採用相同的覆寫順序,也不保證設定目錄和提供器路徑相同。若要將舊設定移轉至 mihomo,可參考mihomo 核心與原版 Clash 的欄位差異,再確認目標用戶端實際使用的核心和設定入口。
設定驗證、連線測試與常見問題
先驗證檔案,再檢查執行狀況
開始排查時,先保留一份已知可用的設定,並為待測檔案使用不同名稱。在圖形介面用戶端中,確認目前選取的設定,以及覆寫後用於啟動的設定。使用獨立核心時,請明確指定檔案路徑和工作目錄。如果同一系統有多個安裝來源,也要確認終端機呼叫的執行檔與介面實際使用的核心是否相同;否則一邊測試通過,另一邊載入失敗並不矛盾。
以下指令適用於已能在終端機執行 mihomo 的環境。範例假設目前目錄中有 config.yaml;工作目錄必須能讀取該設定所需的資料和本機資源。測試通過只代表核心完成這次設定檢查,不代表所有監聽連接埠都能成功綁定、解析器都能連線,也不代表節點已完成協定交握。
mihomo -t -d . -f ./config.yaml
發生錯誤時,請依階段逐步縮小範圍。語法錯誤先檢查錯誤行和前一筆記錄是否漏寫冒號、縮排錯誤或引號未閉合;引用錯誤則檢查策略組、節點和提供器名稱;資源錯誤應核對工作目錄、路徑和檔案格式。不要同時更改檔名、規則和訂閱位址。每次修正後都重複相同的檢查,直到確認錯誤已進入下一階段,再繼續排查。
依入口、比對和出口逐層重新測試
啟動後先確認本機監聽狀態,再指定代理入口送出簡單請求。以下指令假設混合連接埠正在 127.0.0.1:7890 監聽,而且目前策略允許存取目標。如果使用前文的連接埠覆寫範例,請同步調整指令中的連接埠。若正在測試拒絕規則,被拒絕是預期結果;不要因為請求失敗就判定入口無法使用。
curl --noproxy "" --proxy http://127.0.0.1:7890 \
--max-time 15 --head https://example.com/
上述續行符號適用於常見的類 Unix 命令列環境;若終端機不支援這種續行方式,請將指令寫在同一行,並使用實際的 curl 程式。--noproxy "" 會清空本次指令的代理略過清單,方便確認代理入口。收到目標伺服器的回覆,不代表所有應用程式都會使用系統代理;此測試只涵蓋明確指定的連線路徑,與介面圖示狀態無關。
若沒有新的連線記錄,請檢查代理協定、位址和連接埠是否正確,以及應用程式是否略過代理。若已有記錄但命中規則不符預期,請核對當時的模式、傳給核心的目標格式和規則順序。若規則比對和出口選擇都正確,再檢查出口交握、節點網域解析和目標服務的回應。每次記錄目標、模式、命中項目和最終成員,這四項資訊比只記下「無法連線」更有助於排查。
所有節點都逾時,與只有單一節點逾時,應分開判斷。全部逾時時,先檢查共用的訂閱、入口、解析和本機網路條件;只有單一節點異常時,可以維持相同入口和目標,改用另一個成員比較。完成檢查前不要頻繁同時切換多個選項。要依故障症狀繼續排查,可參考節點逾時排查順序;需要重新設定系統接入方式時,請回到快速入門教學。
常見設定問題
為什麼載入成功後,用戶端仍使用舊連接埠?
先確認介面顯示的新連接埠是否已寫入最終設定,再檢查是否完成重新載入並成功監聽。如果核心已監聽新連接埠,但應用程式仍向舊連接埠送出請求,請同步修改系統代理、應用程式的代理選項或終端機環境變數。若舊連接埠仍有服務回應,請檢查是否還有另一個執行個體正在執行,避免誤把舊執行個體的記錄當成本次測試結果。
為什麼規則命中了正確的策略組,結果卻不如預期?
組名只代表入口策略。手動組可能還原先前選取的項目,主備組可能改用備援成員,自動組也可能因探測結果變化而選擇其他成員。先確認該筆連線最後使用哪個成員,再檢查策略組中的成員是否符合用途。更改選擇後請建立新連線重新測試;應用程式若繼續使用原有連線,可能不會立即反映變化。
為什麼還原 YAML 後,系統網路設定沒有一起還原?
系統代理、虛擬介面、路由和作業系統 DNS 設定由相應的系統功能或用戶端管理,不會只因還原設定檔就自動撤銷。在用戶端介面中,依需求關閉一開始啟用的接入功能,檢查系統目前仍使用哪些設定,再透過新請求驗證。如果還原設定前後都能重現問題,也應區分系統層級狀態和核心設定問題。