Clash 設定檔 YAML 手冊

01設定檔總覽:YAML 語法與頂層結構

Clash 設定採用 YAML 格式。YAML 靠縮排表達層級,規矩不多但每條都不能破:統一用空格縮排(約定兩個空格一層),禁止使用 Tab;鍵與值之間的冒號後必須跟一個空格;清單項目以「短橫線 + 空格」開頭;# 到行尾是註解。字串通常不需要引號,但當值裡含有冒號、井號、花括號等特殊字元,或以數字、*、~ 開頭時,應當用引號包住,否則解析結果可能與預期不符——密碼、訂閱 URL、萬用字元網域這三類值建議一律加引號。

設定檔在哪裡

圖形用戶端(Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu 等)自行管理設定目錄:訂閱匯入後以 profile 形式儲存,查看與修改都透過用戶端內建的編輯器或覆寫功能完成,一般不需要手動到檔案系統裡找路徑。直接執行核心的使用者(伺服器、路由器場景)預設從工作目錄讀取 config.yaml,Linux 下慣例路徑是 ~/.config/mihomo/config.yaml,也可以用 -f 參數明確指定檔案、-d 指定工作目錄。

頂層區塊一覽

一份完整設定由若干頂層區塊組成,各管一塊、互不越界。下表是全文的地圖,後續章節按此順序逐個展開:

最小可用範例

下面這份設定去掉了一切可選項,只保留「一個入站連接埠、一個節點、一個策略群組、三條規則」,是能通過語法檢查並正常運作的最小骨架。讀懂它,後面每一章都是在這個骨架上加肉:

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

proxies:
  - name: "範例節點"
    type: ss
    server: example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "範例節點"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,節點選擇
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

三個區塊的協作關係:proxies 定義「有哪些出口」,proxy-groups 把出口組織成「怎麼選」,rules 決定「什麼流量交給哪個群組」。規則的出口既可以是群組名,也可以直接寫節點名或內建的 DIRECT(直連)、REJECT(拒絕)。想看這份骨架更口語化的逐段拆解,可讀部落格《Clash 設定檔結構逐段拆解》。

02通用欄位:連接埠、模式與運作控制

通用欄位位於設定最頂部,不屬於任何區塊,決定核心「以什麼姿態運作」。它們出錯不會導致分流異常,但會導致連不上、連錯埠或是日誌狂刷,值得逐個弄清楚。

入站連接埠與區域網路共享

port 監聽 HTTP 代理,socks-port 監聽 SOCKS5,而 mixed-port 在同一個連接埠同時接受兩種協定——現代設定基本只寫 mixed-port: 7890 一行,省掉兩個連接埠的維護成本。Linux 專屬的 redir-port 與 tproxy-port 用於透明代理場景,桌面使用者可以忽略。allow-lan 控制是否接受區域網路內其他裝置的連線:設為 true 後,同一 Wi-Fi 下的手機、電視可以把代理位址指向這台機器;bind-address 進一步限定監聽的網路卡位址,預設 "*" 表示全部網路卡。

mode:三種工作模式

mode 只有三個合法值。rule 按 rules 區塊逐條比對分流,是日常唯一建議的模式;global 讓所有流量走同一個出口,只在測試單一節點時暫時使用;direct 全部直連,相當於保留監聽連接埠但不做任何代理。三種模式在用戶端介面上都有對應開關,含義與設定欄位完全一致,操作層面的選擇建議見教學頁第二步。

日誌、外部控制與狀態持久化

log-level 從少到多依序是 silent、error、warning、info、debug。日常用 info;排查分流問題時暫時切到 debug,能看到每條連線命中了哪條規則,查完記得改回來,否則日誌檔案增長很快。external-controller 開啟 RESTful API(慣例監聽 127.0.0.1:9090),網頁面板與第三方工具都靠它讀取狀態、切換節點;secret 是這個 API 的存取口令,監聽位址一旦不限於本機就必須設定。profile 區塊控制兩項持久化:store-selected 記住每個策略群組上次手動選中的節點,重新啟動不會遺失;store-fake-ip 把 fake-ip 映射表寫入磁碟,減少重新啟動後的解析抖動。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "your-secret"
profile:
  store-selected: true
  store-fake-ip: true

03dns 區塊:網域解析與 fake-ip

分流規則裡大量條目按網域比對,而網域解析本身又可能被污染或劫持——如果核心直接沿用系統 DNS 的結果,規則判斷和實際連線都會被帶偏。dns 區塊讓核心自己接管解析:用什麼上游、走加密通道與否、要不要啟用 fake-ip,全部在這裡宣告。開啟 TUN 模式時該區塊必須啟用,否則劫持來的 DNS 查詢無處回應。

enhanced-mode:fake-ip 與 redir-host

fake-ip 是目前的主流模式:應用程式發起網域查詢時,核心立即從 fake-ip-range(慣例 198.18.0.1/16)取一個假位址回傳,同時記下「假位址 ↔ 網域」的映射;應用程式拿假位址發起連線時,核心憑映射還原出網域再做規則比對和真實解析。好處是省掉一次前置解析、規則始終能按網域精確比對;代價是有些程式拿到 198.18 開頭的位址會困惑——區域網路裝置探索、NTP 校時、部分遊戲平台屬於典型場景,這正是 fake-ip-filter 存在的意義:列在其中的網域跳過 fake-ip,直接回傳真實位址。redir-host 模式則始終回傳真實 IP,相容性最好但規則比對精確度與效能都略遜一籌,僅在確認 fake-ip 引發問題時才退回使用。

上游伺服器的三層結構

default-nameserver 是引導層,只負責解析後面 DoH 伺服器自己的網域,因此必須填純 IP;nameserver 是主力層,日常查詢都發給它,建議寫 DoH(https:// 開頭)或 DoT(tls:// 開頭)位址;fallback 是備用層,配合 fallback-filter 運作——典型策略是 geoip: true 加 geoip-code: CN:主力層解析結果落在中國大陸 IP 段就採信,否則改用 fallback 的結果,藉此對抗污染。還有一個精確制導工具 nameserver-policy,可以為特定網域指定專用上游,例如把公司內網網域交給內網 DNS。

dns:
  enable: true
  listen: 0.0.0.0:1053
  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
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

fake-ip-filter 支援兩種萬用字元:* 匹配一層,+ 匹配任意多層(+.local 能覆蓋 a.b.local)。修改 fake-ip 相關欄位後建議重新啟動核心並清空用戶端的 fake-ip 快取,讓舊映射失效。另外,TUN 模式下的 DNS 處理與瀏覽器憑證報錯之間有一條容易被忽視的因果鏈,展開分析見部落格《開代理後瀏覽器提示 HTTPS 憑證錯誤?》。

04tun 區塊:虛擬網路卡與系統層級接管

常規的「系統代理」只是向作業系統登記一個 HTTP/SOCKS 連接埠,願不願意使用全看應用程式自律——命令列工具、部分遊戲用戶端和不少背景服務從不讀取這項設定。TUN 模式換了思路:建立一塊虛擬網路卡並把預設路由指過去,所有流量在網路層被截獲,不給應用程式繞行的機會。代價是需要更高的系統權限,並且與系統代理屬於兩套並行機制。

關鍵欄位

stack 選擇協定堆疊實作:system 走系統網路堆疊,效能最好,是桌面平台的預設建議;gvisor 是使用者態實作,相容性場景備用;mixed 取兩者折衷。auto-route 自動改寫路由表,把預設路由導向虛擬網路卡,幾乎總是應該開啟;auto-detect-interface 自動識別真實的實體出口網路卡,避免流量在虛擬網路卡裡打轉形成迴圈。dns-hijack 宣告要劫持的 DNS 目標,寫 any:53 即攔下所有發往 53 埠的查詢交給核心 dns 區塊回應——這也是「開 TUN 必須開 dns」的原因。strict-route 進一步收緊路由防止繞過,個別虛擬機與容器環境下可能引發不通,遇到再關閉。

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
  mtu: 1500

各平台的權限與差異

05proxies:代理節點欄位

proxies 是一個列表,每一項完整描述一個節點。訂閱場景下這個區塊由機場生成、隨訂閱更新,通常不需要手寫;但讀懂欄位仍然必要——排查「某個節點連不上」時,第一步就是核對這裡的參數。所有協定共享四個基礎欄位:name(節點名稱,策略群組和規則靠它引用,同一設定內不得重名)、type(協定類型)、server 與 port(伺服器位址與連接埠);udp: true 宣告該節點支援 UDP 轉發,語音通話和遊戲依賴它。

Shadowsocks(ss)

欄位最少的協定:cipher 指定加密方法(常見 aes-128-gcm、chacha20-ietf-poly1305 等 AEAD 系列),password 為預共享金鑰。兩端的 cipher 與 password 必須完全一致,任何一個抄錯的表現都是「連線立即失敗」而非報錯提示。

VMess

以 uuid 作為身分憑證,alterId 在現代部署中固定為 0,cipher 通常寫 auto。VMess 常與傳輸層偽裝組合:network: ws 啟用 WebSocket 傳輸,配套的 ws-opts 裡 path 與 headers.Host 必須與伺服端約定一致;tls: true 在外層再套一層 TLS。這類節點參數多、相互耦合,連不通時優先逐欄位與訂閱來源比對。

Trojan 與較新的協定

Trojan 天生跑在 TLS 上,核心欄位只有 password 和 sni(TLS 交握時宣告的伺服器名稱)。skip-cert-verify 控制是否跳過憑證驗證——見下方警告。VLESS、Hysteria2、TUIC 等較新的協定需要 mihomo 核心支援,經典 Clash 核心無法解析;本站下載頁收錄的 Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu 均以 mihomo 為基礎,這些協定開箱可用。

proxies:
  - name: "SS-香港-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "VMess-日本-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /your-path
      headers:
        Host: jp01.example.com

  - name: "Trojan-新加坡-01"
    type: trojan
    server: sg01.example.com
    port: 443
    password: "your-password"
    sni: sg01.example.com
    udp: true

06proxy-groups:策略群組欄位

策略群組是節點與規則之間的中間層:規則不直接指向某個節點,而是指向一個群組,群組內再決定目前用哪個節點。這層間接讓「換節點」不必動規則、「節點失效」可以自動切換。每個群組必有 name、type 和成員清單(proxies),成員可以是節點名稱、其他群組名稱,以及內建的 DIRECT 與 REJECT。

五種群組類型

select 手動選擇,面板上點誰用誰,是最常見的「主開關群組」。url-test 定期向 url 指定的測試位址發起請求,自動選用延遲最低的成員;interval 是測試間隔(秒),tolerance 設定切換容差——新舊節點延遲差小於該毫秒數就不切換,避免在兩個水準接近的節點間反覆橫跳;lazy: true 讓群組在被規則實際用到之前不發起測試,省流量。fallback 按成員清單順序取第一個可用節點,首選掛了自動順延、恢復後自動切回,適合「主用一個、備用一串」的場景。load-balance 把連線分攤到多個成員,strategy 可選 consistent-hashing(同一目標網站固定走同一節點)或 round-robin(輪詢)。relay 把成員按順序串成鏈路,流量依次經過每一跳,延遲與故障率隨鏈長疊加,僅特殊需求使用。

群組的巢狀結構

群組可以引用群組,常見的分層寫法是:按地區各建一個 url-test 群組(香港自動、日本自動……),再建一個 select 總群組把這些地區群組和 DIRECT 收進來。日常只操作總群組,地區內部的擇優交給自動測速。需要注意 url-test 面板上顯示的毫秒數衡量的是「到測試位址的交握往返」,與實際頻寬不是一回事,選節點時不要唯延遲論——原理拆解見部落格《Clash 節點延遲測試原理》。

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "自動測速"
      - "故障轉移"
      - "SS-香港-01"
      - "VMess-日本-01"
      - DIRECT

  - name: "自動測速"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - "SS-香港-01"
      - "VMess-日本-01"
      - "Trojan-新加坡-01"

  - name: "故障轉移"
    type: fallback
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - "SS-香港-01"
      - "VMess-日本-01"

07rules:規則語法與比對順序

rules 是一個字串列表,每條形如 類型,比對值,出口(個別類型沒有比對值或帶附加參數)。核心對每條新連線自上而下逐條比對,第一條命中的規則立即生效,其後所有規則不再參與——順序就是優先度,這是理解一切分流行為的關鍵。列表末尾必須有一條 MATCH 兜底,否則未命中的流量行為未定義。

規則類型速查

no-resolve:別讓 IP 規則觸發解析

當目標還是網域時,IP 類規則(IP-CIDR、GEOIP 等)預設會先把網域解析成 IP 再比對——這次解析可能是多餘的,還會拖慢比對。在 IP 規則末尾追加 no-resolve 參數後,網域流量直接跳過該條,只有本來就以 IP 為目標的連線才參與比對。經驗法則:排在網域規則之後、僅為兜底 IP 流量服務的 IP 規則,一律加上 no-resolve;唯一的例外是希望 GEOIP,CN,DIRECT 對網域流量也生效的場景。

排序建議與常見誤傷

建議的排列順序:處理程序規則與精確網域規則放最前,DOMAIN-SUFFIX 批量規則居中,RULE-SET 與 GEOSITE 大型集合置於其後,GEOIP,CN,DIRECT 倒數第二,MATCH 收尾。兩個高頻翻車點:其一,DOMAIN-KEYWORD 比對面極廣,DOMAIN-KEYWORD,go,節點選擇 這類短關鍵字會誤傷大量無關網域;其二,把寬規則放在窄規則前面,導致後面的精細規則永遠輪不到——排查時開啟 log-level: debug 看連線實際命中了哪條即可定位。GEOIP 與 GEOSITE 依賴本地資料庫檔案,資料庫版本直接影響比對結果,下載來源選擇與更新方法見部落格《Clash GeoIP 與 GeoSite 資料庫更新教學》。

rules:
  - PROCESS-NAME,Telegram.exe,節點選擇
  - DOMAIN,dl.google.com,節點選擇
  - DOMAIN-SUFFIX,github.com,節點選擇
  - DOMAIN-SUFFIX,githubusercontent.com,節點選擇
  - DOMAIN-KEYWORD,youtube,節點選擇
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

08proxy-providers 與 rule-providers

Provider 機制把「節點清單」和「規則集」從主設定裡拆出去,變成可獨立下載、獨立更新的外部資源。好處直接:訂閱更新只刷新節點檔案,不碰你精心維護的策略群組與規則;規則集可以引用社群維護的現成清單,不必自己維護上千行網域。

proxy-providers:外部節點來源

每個 provider 有一個自訂鍵名。type: http 表示從 url 定期抓取(interval 單位為秒,86400 即一天一次),下載結果快取到 path;type: file 則直接讀本地檔案。health-check 子區塊為這批節點設定健康檢查,參數含義與 url-test 群組一致。策略群組透過 use 欄位引用 provider,與 proxies 清單可以並存——手寫的常駐節點和訂閱節點混編在同一個群組裡完全合法。訂閱連結本身有 Base64、Clash YAML 等多種格式,provider 需要的是 Clash YAML 格式的位址,格式識別與轉換方法見部落格《Clash 訂閱連結常見格式詳解》。

rule-providers:外部規則集

欄位與 proxy-providers 大體同構,多一個關鍵的 behavior:domain 表示檔案內容全部是網域(核心用網域樹高效比對)、ipcidr 全部是網段、classical 則允許混寫各種規則類型但比對開銷最大——能用前兩種就不要用 classical。規則檔案的格式由 format 宣告(yaml 或 text)。定義好之後,在 rules 裡用 RULE-SET,鍵名,出口 引用,該條的排序原則與一般規則完全相同。

proxy-providers:
  airport:
    type: http
    url: "https://example.com/sub?token=xxxx"
    path: ./providers/airport.yaml
    interval: 86400
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "節點選擇"
    type: select
    use:
      - airport
    proxies:
      - DIRECT

rule-providers:
  cn-domains:
    type: http
    behavior: domain
    format: yaml
    url: "https://example.com/ruleset/cn.yaml"
    path: ./ruleset/cn.yaml
    interval: 86400

rules:
  - RULE-SET,cn-domains,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

09覆寫與合併:改設定而不丟改動

訂閱是機場生成的完整設定,每次更新都會整體覆蓋本地 profile——直接在訂閱檔案裡改 dns、加規則,下次更新全部歸零。覆寫(Override / Merge)機制解決這個矛盾:你的修改單獨存放,用戶端在每次載入訂閱時把它自動疊加上去,訂閱隨便更新,改動始終生效。

用戶端裡的覆寫入口

本站下載頁收錄的主流用戶端(Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu)都提供訂閱覆寫能力,入口名稱略有差異,常見稱呼是「覆寫」「全域擴充設定」「Merge」。多數用戶端同時提供兩種形態:宣告式的 YAML 合併(寫一段片段,按鍵名疊加)和腳本式覆寫(用 JavaScript 函式直接加工設定物件,自由度更高)。日常需求用 YAML 合併就夠,腳本留給「按條件批量改節點名稱」這類程式化場景。

合併語義:什麼會被覆蓋,什麼會被追加

理解合併的關鍵是區分值類型:標量鍵(如 mode、log-level)與映射鍵(如整個 dns 區塊)在覆寫片段中出現時,直接取代訂閱裡的同名內容;列表鍵(如 rules、proxies)預設也是整體取代——這往往不是你想要的結果,所以 Clash Verge Rev 風格的合併提供了 prepend- 與 append- 前綴:prepend-rules 把若干條規則插到訂閱規則的最前面(利用「先命中先生效」搶佔優先度),append-rules 則補在 MATCH 之前的隊尾。同理還有 prepend-proxies、prepend-proxy-groups 等。

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - PROCESS-NAME,ssh,DIRECT

append-rules:
  - DOMAIN-KEYWORD,tracker,REJECT

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://doh.pub/dns-query

改完先驗證,再談生效

無論直接編輯還是覆寫,儲存前都值得過一遍語法檢查。圖形用戶端的內建編輯器一般會即時標紅錯誤行;命令列環境下,mihomo 自帶設定檢查參數,只驗證不啟動:

mihomo -t -f config.yaml

驗證通過後重新載入設定即可生效,不需要重新啟動整個用戶端。如果載入後行為不符合預期,按本手冊的區塊順序自查:入站連接埠對不對 → dns 是否啟用 → 規則順序有沒有被寬規則截胡 → 策略群組目前選中的是誰。仍未解決的問題,先查 FAQ 的「故障排查」分類;從零開始的完整操作路徑回看快速上手教學;還沒有安裝用戶端的讀者,直接前往取得用戶端頁,首選 Clash Plus。