Clash 設定檔完全參考

YAML 結構總覽

設定檔在哪裡

GUI 用戶端一般不會讓你直接面對檔案本體:Clash Verge Rev 在「訂閱 / 設定」頁管理多份設定,Clash Plus 在 App 內維護訂閱與本機設定,檔案存放在各自的應用程式資料目錄裡,介面上都有「開啟設定目錄」之類的入口。而 mihomo 核心(以及 Clash for Windows 這類舊用戶端)直接讀取一個 YAML 檔案,預設檔名 config.yaml,啟動時用 -d 參數指定它所在的目錄。無論走哪條路徑,最終生效的都是同一份結構的 YAML:最上層先是一組標量欄位(連接埠、模式、記錄層級),接著是 dns、proxies、proxy-groups、rules 四個功能段落,外加 proxy-providers、rule-providers 兩個外部資源段。理解這份骨架,就理解了所有 Clash 系用戶端共通的設定邏輯。

YAML 語法四條鐵律

YAML 的寫法約束很少,但每一條都直接決定檔案能否被解析:

1. 縮排只能用空格,不能用 Tab。這是新手報錯的第一來源,在編輯器裡把 Tab 設為自動轉換成兩個空格可以一勞永逸。
2. 鍵與值之間是「冒號加一個空格」。寫成 port:7890 或 port : 7890 都會解析失敗,或得到意料之外的結果。
3. 清單項目以「- 」開頭,短橫線後面同樣要接一個空格;清單可以跟父鍵同列書寫,也可以再縮排一級,兩種寫法等價,全檔案統一即可。
4. 字串裡出現冒號、#、花括號、方括號、逗號等特殊字元時,用英文雙引號整段包起來;# 之後的內容是註解,不參與解析。

另外,YAML 支援錨點與引用(& 定義錨點、* 引用、<< 合併),多個節點共用一段參數時可以少寫重複行,具體範例見「代理節點欄位」一節。

頂層欄位速覽

一份完整設定的頂層大致分三組:網路監聽(port、socks-port、mixed-port 等)、執行行為(mode、log-level、ipv6、external-controller 等)、功能段落(dns、proxies、proxy-groups、rules)。下表先給全景,後面逐段展開。

# config.yaml 骨架:先標量,後段落
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  # ...詳見「DNS 欄位」一節

proxies:
  - name: "node-a"
    # ...詳見「代理節點欄位」一節

proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["node-a", DIRECT]

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - MATCH,PROXY

通用欄位:連接埠、模式與全域行為

連接埠欄位

Clash 對外提供四種入站監聽。port 是經典 HTTP 代理連接埠;socks-port 是 SOCKS5 連接埠,支援 UDP 轉發;mixed-port 把兩種協定合併到同一連接埠,核心依請求特徵自動辨識,目前絕大多數 GUI 用戶端預設只開混合連接埠;redir-port 與 tproxy-port 面向 Linux 透明代理,桌面用戶用不到。啟動時報「bind: address already in use」就是連接埠被佔用:換一個連接埠,或找出並關閉佔用中的程序。混合連接埠配合區域網路共享的實際用法,技術筆記裡有一篇專文說明。

執行模式

mode 決定請求的出口走向,共三個數值:rule 依 rules 清單逐條比對,是日常使用的預設;global 把全部流量交給 GLOBAL 策略組(通常等於你在面板裡選的那個節點),排查「是不是規則寫錯了」時切到它最直接;direct 全部直連,用來確認代理本身是否正常運作。GUI 用戶端首頁的模式切換按鈕,改的就是這個欄位。

區域網路與外部存取

allow-lan 打開後,同一區域網路裡的手機、平板可以把代理指向這台電腦的 IP 與連接埠,共用一個代理出口;bind-address 控制監聽網卡,預設 "*" 表示所有網卡,只有配合 allow-lan 才有實際意義。external-controller 是核心的 RESTful 管理介面,GUI 面板靠它讀取狀態、切換節點、拉取記錄;secret 是該介面的存取金鑰。若把這個介面的監聽位址改成 0.0.0.0 對外開放,必須同時設定 secret,否則等於把代理控制權交給整個網路。external-ui 指向一個靜態面板目錄,可讓瀏覽器直接存取管理介面。

記錄、延遲與其他行為欄位

log-level 從 silent 到 debug 共五檔,排查問題時暫時調到 debug,平時維持 info。ipv6 控制是否處理 AAAA 紀錄,網路沒有 IPv6 出口時建議關閉。unified-delay 讓測速把 TCP/TLS 交握時間計入延遲,各節點間的數字才有可比性;tcp-concurrent 讓候選節點並行建立連線,首次連線更快;find-process-mode 控制是否解析本機程序名稱,PROCESS-NAME 規則依賴它;global-client-fingerprint 指定 TLS 用戶端指紋偽裝(常見數值 chrome),對依賴 uTLS 的協定有意義;profile 段的 store-selected 會記住面板裡的手動選點,重新載入設定後選擇不會遺失。另有 tun 段用於虛擬網卡層級的接管,屬於進階主題,一般桌面場景不必開啟。

入站與出站的其他形態

除了頂層的連接埠欄位,mihomo 還支援 listeners 清單宣告更多入站:每項一個 name、type(http、socks、mixed、redir、tproxy、tun、shadowsocks、vmess 等)與 port,可以在同一份設定裡同時監聽多個連接埠、執行不同協定,例如為區域網路單獨開一個帶驗證的 SOCKS 連接埠,或把某個連接埠直接做成 Shadowsocks 伺服端供其他裝置接入。頂層連接埠欄位與 listeners 可以共存,核心會把它們合併成完整的入站清單。出站方向除了 proxies 裡的節點,還有三個內建出口:DIRECT 直連、REJECT 靜默丟包、REJECT-DROP 直接中斷連線;REJECT 會立即回傳拒絕,適合廣告與追蹤網域,REJECT-DROP 不回應任何資料,適合讓掃描類請求逾時放棄。理解這兩組概念,後面讀規則與策略組時「出口」一欄的含義就完整了。

介面與外部資源欄位

external-ui 指向一個靜態面板目錄後,瀏覽器存取 external-controller 的位址即可開啟圖形面板,適合核心裸跑在路由器、NAS 上的場景;external-ui-url 可以讓用戶端啟動時自動下載官方面板壓縮包。geodata-mode 與 geo-update-interval 控制地理資料檔的格式與更新週期;keep-alive-interval 調整連線重用的心跳間隔,行動網路下適當調大可以省電。這些欄位都有合理預設值,只有明確遇到對應需求時才需要寫進設定。

port: 7890
socks-port: 7891
mixed-port: 7897
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: ""
unified-delay: true
tcp-concurrent: true
find-process-mode: strict
global-client-fingerprint: chrome
profile:
  store-selected: true
  store-fake-ip: true

DNS 欄位:防污染與防洩漏

為什麼 DNS 要獨立成段

代理只解決「流量怎麼走」,DNS 決定「網域名稱先解析成什麼」。系統預設 DNS 走電信業者 UDP 53:明文、可被劫持,還會把存取意圖暴露給本機網路——這就是常說的 DNS 洩漏。Clash 的 dns 段在核心裡內建了一個 DNS 伺服器:接管查詢請求,依策略把不同網域交給不同上游;搭配 fake-ip 模式還能做到「先按網域名稱比對規則、再決定要不要代理」,繞開「先解析出被污染的 IP、規則卻是依網域名稱寫」的死結。

基礎欄位

enable 是總開關;listen 是內建 DNS 的監聽位址,GUI 用戶端不做系統層級接管時可以不設。enhanced-mode 有兩個數值:redir-host 回傳真實解析結果,由核心記錄網域與 IP 的對應關係;fake-ip 直接回傳 198.18.0.0/16 段的假位址,連線進來時再反查網域走規則比對,速度更快、對污染免疫,是目前的主流選擇。fake-ip-filter 列出不走 fake-ip 的網域——區域網路裝置名稱、NTP 校時、部分依賴真實 IP 的服務,清單內的網域按真實解析處理。default-nameserver 只負責解析「上游 DNS 伺服器本身的網域」,必須填純 IP 的傳統 UDP 伺服器,否則會陷入「要先解析 DoH 網域、又得先問 DoH」的循環。

上游伺服器

nameserver 是主力上游清單,可寫多行並行查詢取最快結果。fallback 是備用群組,搭配 fallback-filter 依 GEOIP 判斷:解析結果落在境外 IP 段時改用 fallback 重查。mihomo 更推薦 nameserver-policy:依網域集合直接指定上游,例如 geosite:cn 走台灣或大陸境內的 DoH、其餘走可信境外 DoH,比 fallback 的「先查再判斷」更明確。proxy-server-nameserver 專門解析代理節點的網域,避免節點網域被污染後連不上伺服器。respect-rules 打開後,DNS 請求本身也依規則選擇出口(透過代理查詢境外 DNS),代價是設定複雜度提高。另有 sniffer 嗅探段,可從 TLS/HTTP 交握中還原網域,修正「應用程式直接連 IP」時規則比對失準的問題。

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - time.*.com
    - ntp.*.com
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://doh.pub/dns-query
  nameserver-policy:
    "geosite:geolocation-!cn":
      - https://dns.cloudflare.com/dns-query
      - https://dns.google/dns-query

fake-ip 的運作原理與取捨

fake-ip 值得單獨展開,因為它決定了整套分流的行為方式。開啟後,核心對所有查詢回傳 198.18.0.0/16 段內的假位址,應用程式隨即向這個假位址發起連線;核心收到連線時依假位址反查出原始網域,再拿網域去比對規則。這樣做有三個直接好處:一是規則比對發生在解析之前,網域類規則永遠生效,不會被「先解析出被污染的 IP」帶偏;二是省掉了真實 DNS 的往返等待,首次連線更快;三是應用程式拿到的位址永不失效,不存在 DNS 快取過期造成的抖動。代價同樣明確:任何依賴真實 IP 的功能都會失靈——區域網路裡依 IP 存取裝置、需要真實位址做地域判斷的服務、以及直接 ping 網域除錯,都會拿到假位址。這正是 fake-ip-filter 存在的意義:把這類網域逐個列入,讓它們走真實解析。日常維護中,遇到「某個應用一開代理就異常、關掉就正常」,第一反應就是把它的網域加進 fake-ip-filter 試一次。

嗅探器 sniffer 的角色

並非所有應用都先查 DNS 再連線:部分用戶端內建了硬編碼 IP,或自行實作了 DNS。此時核心看到的只有目標 IP,網域類規則全部落空。sniffer 段開啟後,核心會嗅探 TLS 交握中的 SNI 與 HTTP 請求的 Host 標頭,把連線還原出網域再重新走一遍規則比對,命中率顯著提升。它對純 IP 的私有協定無能為力,但已足夠涵蓋絕大多數瀏覽器與常規應用。嗅探與 fake-ip 可以共存,二者解決的是同一問題的兩個側面:一個讓網域在解析前可見,一個在解析缺失時把網域找回來。

代理節點欄位:proxies 清單

通用欄位

proxies 是一個清單,每個元素對應一個節點。所有協定共用的欄位只有五個:name(顯示名稱,規則與策略組靠它引用,必須在整份檔案中唯一)、type(協定類型)、server、port、udp(是否轉發 UDP,節點支援就開)。其餘欄位隨協定而異。手動維護多個同協定節點時,可以用 YAML 錨點抽出共同部分,後續節點用合併鍵引用,只寫差異欄位:

proxies:
  - &ss-base
    name: "ss-a"
    type: ss
    server: 203.0.113.10
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true
  - <<: *ss-base
    name: "ss-b"
    server: 203.0.113.11
    port: 8389

各協定範例

以下範例涵蓋 mihomo 常用的五類協定,位址全部使用文件保留段,替換為真實伺服器資訊即可使用:

proxies:
  - name: "ss-example"
    type: ss
    server: 203.0.113.10
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "vmess-example"
    type: vmess
    server: 198.51.100.20
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    servername: example.com
    network: ws
    ws-opts:
      path: /ray
      headers:
        Host: example.com

  - name: "trojan-example"
    type: trojan
    server: 192.0.2.30
    port: 443
    password: "your-password"
    sni: example.com
    skip-cert-verify: false
    udp: true

  - name: "hy2-example"
    type: hysteria2
    server: 203.0.113.40
    port: 443
    password: "your-password"
    sni: example.com
    skip-cert-verify: false

  - name: "vless-example"
    type: vless
    server: 198.51.100.50
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    network: tcp
    tls: true
    udp: true
    flow: xtls-rprx-vision
    servername: www.microsoft.com
    reality-opts:
      public-key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      short-id: "0123456789abcdef"
    client-fingerprint: chrome

skip-cert-verify 只在確認證書鏈有特殊原因時暫時開啟,長期開啟等於放棄 TLS 的身分驗證。sni / servername 決定 TLS 交握時聲明的網域,填錯會直接連不上。

協定支援差異

原版 Clash 已停止維護,新協定只會進 mihomo 核心。這也是本站下載頁全數首推 mihomo 系用戶端的原因:

策略組欄位:proxy-groups

五種類型

策略組是「節點的容器加選擇策略」。select 手動選擇,面板裡點哪個走哪個,幾乎每份設定都有一個總入口組;url-test 依固定間隔對組內節點測速,自動選延遲最低者;fallback 同樣會測速,但語義是「目前節點掛了才切下一個」,清單順序即優先順序;load-balance 把連線依策略分攤到多個節點(strategy 取 consistent-hashing 或 round-robin),適合多線疊加頻寬;relay 把多個節點串成鏈式代理,流量依序穿過,出口是最後一個節點。mihomo 還支援替策略組加 icon 欄位,在面板裡顯示自訂圖示。

測速參數

url 是測速目標,慣例用 http://www.gstatic.com/generate_204,204 無內容回應、開銷最小;interval 是測速間隔秒數,太短只會白白增加流量與耗電,300 是常見數值;tolerance 是切換門檻(毫秒),新節點要比目前節點快出這個數才會換,避免在兩條相近線路間來回跳動;lazy 為 true 時只有組被使用才會測速,冷門備用組不會白跑流量;timeout 是單次測速的逾時上限。

巢狀與引用

策略組的 proxies 清單裡可以再寫其他策略組的名稱——這就是巢狀:總入口 PROXY 裡放「香港」「日本」「美國」三個地區組,每個地區組是 url-test,手動選地區、組內自動選節點,兩層各司其職。use 欄位引用 proxy-providers 裡的訂閱來源,把整批節點拉進組;filter 用正規表達式篩選節點名稱,例如 filter: "香港|HK" 只保留名稱含香港的節點。DIRECT(直連)與 REJECT(封鎖)是兩個內建出口,可以直接寫進任何 proxies 清單,搭配 select 組就能做出「廣告攔截開關」這類功能組。

proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["HK-AUTO", "JP-AUTO", "US-AUTO", DIRECT]

  - name: "HK-AUTO"
    type: url-test
    use: ["provider-main"]
    filter: "香港|HK|Hong Kong"
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: "JP-AUTO"
    type: url-test
    use: ["provider-main"]
    filter: "日本|JP|Japan"
    url: http://www.gstatic.com/generate_204
    interval: 300

  - name: "US-AUTO"
    type: fallback
    use: ["provider-main"]
    filter: "美國|US|United States"
    url: http://www.gstatic.com/generate_204
    interval: 300

  - name: "AD-BLOCK"
    type: select
    proxies: [REJECT, DIRECT]

規則語法:rules 從上到下

比對順序

rules 是一個有序清單:核心從上到下逐條比對,命中第一條即停止,後面不再檢查。寫法上的鐵律是「精確的放前面,寬泛的放後面,MATCH 永遠墊底」。規則分兩類:網域類(DOMAIN / DOMAIN-SUFFIX / DOMAIN-KEYWORD / GEOSITE)在解析前就能判斷;IP 類(IP-CIDR / GEOIP)需要拿到解析結果。給 IP 類規則加 no-resolve 參數,表示「請求本來就是網域時,別為了比對這條規則去觸發 DNS 解析」,純網域請求會跳過該條繼續往下比對,可避免大量無謂查詢。GEOSITE 與 GEOIP 依賴地理資料檔,GUI 用戶端會自動維護,核心裸跑時需確保資料檔在設定目錄內或開啟自動更新。

規則類型速查

rule-providers 規則集

規則集把成千上百條規則抽成外部檔案,主設定只留一行引用。type 為 http 時依 url 定時拉取(interval 秒)並快取到 path;為 file 時讀取本機檔案。behavior 有三種:domain(純網域後綴集合,載入為網域樹,比對最快)、ipcidr(純 IP 段)、classical(經典規則行,可混寫各種類型)。規則集檔案本身可以是 yaml(payload 清單)或純文字每行一條。

rule-providers:
  reject-ads:
    type: http
    behavior: domain
    url: "https://example.org/rules/ads.yaml"
    path: ./ruleset/ads.yaml
    interval: 86400
  local-direct:
    type: file
    behavior: classical
    path: ./ruleset/direct.yaml

rules:
  - RULE-SET,reject-ads,AD-BLOCK
  - RULE-SET,local-direct,DIRECT
  - DOMAIN-SUFFIX,lan,DIRECT
  - GEOSITE,private,DIRECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - GEOSITE,geolocation-!cn,PROXY
  - MATCH,PROXY

規則排序的實戰思路

寫規則時先想清楚三件事:哪些必須直連、哪些必須代理、剩下的交給誰。直連組放最前:區域網路與保留位址(GEOSITE,private)、系統與校時服務、公司內部網域,這些命中即走,不消耗代理資源。攔截組緊隨其後:廣告與追蹤網域交給 REJECT,越早攔截越省後續處理。然後是指定代理的精確規則:常用境外服務用 DOMAIN-SUFFIX 或 GEOSITE 分類點名,命中進 PROXY。寬泛的地理規則放後段:GEOSITE,cn 與 GEOIP,CN 兜底境內直連,GEOSITE,geolocation-!cn 兜底境外代理。最後 MATCH 收尾。這個順序的核心原則是「判斷成本遞增、涵蓋範圍遞增」:精確規則判斷快、範圍小,放前面;地理資料庫比對要查資料檔、範圍大,放後面。規則數量與啟動速度直接相關,幾千條以內無需擔心,超過這個量級就應考慮把穩定的大段規則遷移到 rule-providers,主設定只留高頻調整的部分。

程序分流與連接埠分流的邊界

PROCESS-NAME 規則依發起連線的程序名稱分流,是「讓某個應用單獨走代理或直連」的最直接手段,但它有兩個前提:find-process-mode 必須開啟,且該應用不能走系統代理之外的路徑。macOS 與 Linux 上程序解析的可靠性不如 Windows,遇到規則不生效先查記錄裡程序名稱是否被正確識別。DST-PORT 規則依目標連接埠分流,典型用法是把 22(SSH)、873(rsync)等管理連接埠固定直連,避免代理出口 IP 頻繁變化觸發伺服器的安全告警。這兩類規則都屬於「特例通道」,數量宜少不宜多,放在精確網域規則之後、地理規則之前。

覆寫與合併:訂閱與自訂共存

為什麼不能直接改訂閱檔案

訂閱的本質是「服務方下發的完整設定檔」,用戶端每隔一段時間重新拉取並整份覆蓋。你在訂閱檔案裡加的自訂規則、改的策略組,下次更新全部消失。正確做法是把「訂閱內容」與「本機自訂」分成兩層:訂閱負責節點,覆寫負責你的規則與欄位,兩者在用戶端執行時合併成最終設定。這樣訂閱隨便更新,本機層始終不動。

用戶端覆寫機制

以 Clash Verge Rev 為例:在訂閱清單上按右鍵進入編輯,可以維護一段全域擴充設定(Merge),對所有訂閱生效。Merge 支援兩類鍵:一是 prepend- / append- 前綴的追加鍵,把內容插到對應清單的開頭或結尾;二是與最上層同名的覆蓋鍵,直接取代訂閱裡的值。Clash Plus 同樣提供訂閱之外的自訂設定入口,做法相同。仍在使用 Clash for Windows 的讀者請注意:該專案已停止維護,其 Mixin 機制多年未更新,建議按《遷移到 Clash Verge Rev 與 Clash Plus 的方案》一文換到持續維護中的用戶端。

# 全域擴充設定(Merge)範例
prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
append-proxy-groups:
  - name: "MY-SELECT"
    type: select
    use: ["provider-main"]
mixed-port: 7897

三條路線對比

驗證、除錯與常見錯誤

用核心做靜態檢查

mihomo 內建設定檢查:把 config.yaml 放進一個目錄,執行 ./mihomo -t -d ./目錄,通過會印出檢查成功的提示,失敗則給出欄位名稱與行號。改動較大時先在命令列跑一次 -t,再讓 GUI 載入,比反覆重啟用戶端試錯快得多。Windows 使用者把核心執行檔與設定放同一目錄,在 PowerShell 裡執行相同命令即可。

熱重載與記錄

external-controller 開著時,可以不重啟核心直接重新載入設定:

curl -X PUT "http://127.0.0.1:9090/configs?force=true" \
  -H "Content-Type: application/json" \
  -d '{"path": "/絕對路徑/config.yaml"}'

force=true 會強制斷開並重新連線現有連線,日常重載可以不加。記錄層面,把 log-level 調到 debug 之後,每條連線的比對過程(網域、命中的規則、出口節點)都會印出,是定位「這條流量為什麼沒走代理」的第一手段;GUI 用戶端的記錄 / 連線面板,本質上就是這些資料的圖形化呈現。

高頻錯誤對照

到這裡,一份設定從骨架到欄位、從規則到覆寫的完整脈絡就齊了。日常使用中更具體的問題——連不上、速度慢、某個應用不走代理——常見問題頁依症狀整理了排查路徑;還沒安裝用戶端的讀者,下載頁依平台列出了目前維護中的選擇;想先快速跑通最小流程,再回本頁查欄位的,可從教學頁開始。