Clash 設定檔欄位參考大全

Clash 系客戶端的一切行為都由一份 YAML 設定檔驅動:監聽哪個埠、DNS 如何解析、有哪些節點、流量按什麼規則分派,全部寫在這份檔案裡。圖形客戶端的開關與下拉選單,本質上只是這份檔案的視覺化編輯器——理解欄位本身,才能在介面選項不夠用、或訂閱內容需要微調時不至於束手無策。

本站對設定相關內容做了明確分工:使用文件負責「從下載到連通」的最短路徑,不展開欄位細節;常見問題收錄按症狀檢索的獨立問答;本頁則是系統化的欄位參考,按設定檔自上而下的書寫順序組織,適合整段通讀建立框架,也適合用頂部目錄直接跳到某個欄位所在章節。

欄位語意以 mihomo 核心為基準。原版 Clash 核心封存後,主流圖形客戶端——包括本站首推的 Clash Plus,以及 Clash Verge Rev、FlClash、Clash Nyanpasu 等——均已切換到 mihomo,本頁描述的欄位在這些客戶端上通用;個別 mihomo 擴充欄位在極舊的核心上不可用,文中會單獨標註。各客戶端的平台覆蓋與取得方式見安裝包頁面,專案間的譜系關係可參考文章《Clash、mihomo、Verge Rev 是什麼關係》。

頂層結構:一份最小可用骨架

config.yaml 是一個由若干頂層鍵組成的映射(mapping)。拋開所有可選項,一份能跑起來的最小設定只需要五個部分:運行參數、DNS、節點清單、策略組清單、規則清單。先看骨架,後續各章逐段展開:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://223.5.5.5/dns-query

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - HK-01
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

頂層鍵的載入沒有順序要求,核心按鍵名取值;但社群約定俗成按「運行參數 → dns → proxies → proxy-groups → rules」排列,與流量處理的邏輯順序一致,閱讀與排錯都更順手。下表列出常見頂層鍵及其類型:

書寫規範:縮排、引號與常見筆誤

YAML 對格式敏感,設定報錯的相當一部分根源是書寫問題,而非欄位用錯。三條鐵律:第一,縮排只能用空格,統一兩格,Tab 鍵會直接導致解析失敗,且報錯行號往往指向檔案後面很遠的位置,極難定位;第二,冒號後必須跟一個空格,port:7890 是非法寫法;第三,陣列元素以「短橫線 + 空格」開頭,短橫線的縮排層級決定它屬於哪個鍵。

字串預設不需要引號,但三種情況必須加:值裡含冒號、井號等特殊字元時;值是純數字卻希望按字串處理時;密碼、UUID 這類可能以特殊字元開頭的敏感值——統一加雙引號是最省心的習慣。另外注意 YAML 1.1 遺留坑:不帶引號的 yes、no、on、off 會被部分解析器當成布林值,節點名恰好叫這些詞時務必加引號。

埠族:mixed-port、port 與 socks-port

埠欄位決定本機應用程式如何把流量交給核心。mixed-port 是目前的建議寫法:單個埠同時接受 HTTP 與 SOCKS5 兩種協定的連入,系統代理只需指向這一個埠,是絕大多數客戶端預設產生的形態,約定值 7890。歷史寫法 port(純 HTTP)與 socks-port(純 SOCKS5)仍然有效,可與 mixed-port 並存,分別監聽不同埠,適合需要區分協定入口的偵錯場景。

此外還有 redir-port 與 tproxy-port,面向 Linux 透明代理(配合 iptables/nftables 轉發),桌面日常使用無需設定。所有埠共享同一條限制:不能與本機其他行程衝突。啟動時報 bind: address already in use,就是埠被佔用,定位與更改埠的完整步驟見文章《Clash 提示埠被佔用怎麼辦》。

allow-lan 與 bind-address

allow-lan 控制是否接受區域網路內其他裝置的連入連線,預設 false(只監聽 127.0.0.1)。設為 true 後,同一 Wi-Fi 下的手機、電視盒子可以把代理指向這台電腦的內網 IP 與埠,實現「一機開代理、全屋共享」。配套的 bind-address 限定監聽網卡:預設 "*" 表示所有網卡,多網卡環境可以填某張網卡的位址,把入口收窄到指定網段。開啟 allow-lan 意味著區域網路內任何裝置都能借道你的出口,公共網路環境(辦公室、飯店)下應保持關閉。

mode:三種分流模式

mode 取三個值。rule 為規則模式,每條連線逐條比對 rules 清單決定走向,是日常使用的標準形態;global 為全域模式,跳過規則,所有流量交給全域出口(介面上通常表現為直接選一個節點);direct 為直連模式,所有流量不經代理,相當於暫時停用分流但保留核心運行。排查「某網站到底走了哪條規則」時,可以在 global 與 rule 之間切換對照,快速判斷問題出在規則還是節點。

日誌與外部控制器

log-level 控制核心日誌詳細程度,從簡到繁依次為 silent、error、warning、info、debug。日常建議 info;排錯時切到 debug,可以看到每條連線命中的具體規則與 DNS 解析路徑;確認穩定後調回,避免日誌檔案無謂膨脹。external-controller 宣告 RESTful 控制介面的監聽位址(約定 127.0.0.1:9090),圖形客戶端與網頁面板都透過它讀取狀態、切換節點;配套的 secret 為介面設定存取口令,凡是把控制器監聽到 0.0.0.0 或開放給區域網路的場景,secret 必須設定,例如 secret: "your-secret"。

其他常用開關

ipv6 預設 false,設為 true 後核心會解析並連線 AAAA 記錄,本機或節點端 IPv6 不通時反而造成部分網站逾時,建議確認連線支援後再開啟。unified-delay(mihomo 擴充)讓延遲測試扣除交握開銷,不同協定節點的延遲數字更具可比性。profile 區塊下的 store-selected: true 會記住每個策略組上次選中的節點,重啟或更新訂閱後不必重選,幾乎所有客戶端範本都預設開啟。

為什�麼需要內建 DNS

分流的前提是「知道這條連線要去哪」,而網域解析恰恰是最容易被污染或洩漏的環節:如果解析交給不可信的上游,拿到的 IP 可能是錯的;如果所有解析都走本地電信業者,存取記錄又會完整暴露。dns 模組讓核心接管解析過程,配合規則系統決定「哪些網域用哪組 DNS、解析結果如何交還給應用程式」。在 TUN 模式或透明代理下,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"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://223.5.5.5/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enhanced-mode:fake-ip 與 redir-host

這是 dns 區塊裡影響最大的欄位。fake-ip 模式下,核心對每個網域先回傳一個保留網段(由 fake-ip-range 定義,預設 198.18.0.0/16)裡的假位址,應用程式拿假 IP 發起連線,核心在假 IP 與網域之間維護對映——好處是應用端完全跳過真實解析,規則可以直接按網域比對,連線建立快且無解析洩漏;代價是少數依賴真實 IP 的程式(區域網路探索、某些遊戲連線、NTP 校時)會異常,需要把這類網域加進 fake-ip-filter 白名單,命中白名單的網域回落為真實解析。redir-host 模式則始終回傳真實 IP,相容性最好,但網域資訊在部分連線上會遺失,規則命中率與解析速度都不及 fake-ip。桌面客戶端範本普遍預設 fake-ip,遇到特定應用異常再補 filter 即可。

三組上游:default-nameserver、nameserver 與 fallback

三個清單分工明確。default-nameserver 只做一件事:解析後面兩組上游裡 DoH/DoT 伺服器本身的網域,因此必須填純 IP,否則出現「解析器網域沒人解析」的死結。nameserver 是主力上游,承擔日常全部解析,建議填加密協定位址(https:// 開頭的 DoH 或 tls:// 開頭的 DoT),避免明文 53 埠在連線上被竄改。fallback 是備用上游,與 fallback-filter 連動:當 nameserver 的解析結果命中過濾條件(典型設定 geoip: true 且 geoip-code: CN,即「結果不屬於中國大陸 IP」)時,改用 fallback 的結果——用於對抗污染,讓境外網域拿到乾淨解析。若不需要這套機制,可以只留 nameserver,結構更簡單。

所有協定共有的四個欄位

proxies 陣列的每個元素定義一個節點。無論什麼協定,四個欄位必填:name(節點名,全檔案內必須唯一,策略組與規則都靠它引用,重名會導致載入失敗)、type(協定類型)、server(伺服器網域或 IP)、port(伺服器埠)。可選的 udp 宣告該節點是否轉發 UDP 流量,遊戲與即時通話場景建議開啟(前提是伺服器端支援)。mihomo 支援的協定相當廣:ss、vmess、trojan、vless、hysteria2、tuic、wireguard、socks5、http 等均可作為 type 取值,下面挑三種最常見的展開。

Shadowsocks(type: ss)

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

核心是加密參數:cipher 與 password 必須與伺服器端完全一致。常用 cipher 有 aes-256-gcm、chacha20-ietf-poly1305,以及新一代的 2022-blake3-aes-256-gcm(要求密碼為 Base64 編碼的定長金鑰,不能隨手填字串)。加密參數不匹配的典型症狀是連線立即中斷且日誌報解密錯誤。若伺服器端啟用了外掛(如 obfs),還需補 plugin 與 plugin-opts 兩個欄位。

VMess(type: vmess)

  - name: "JP-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 23ad6b10-8d1a-40f7-8ad0-e3e35cd38297
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ray
      headers:
        Host: jp01.example.com

身份憑證是 uuid,由伺服器端下發,一字不差照抄。alterId 在現代部署下固定為 0(啟用 AEAD)。network 決定傳輸層形態:tcp 直連、ws 走 WebSocket(常配合 CDN 中轉)、grpc 走 gRPC;選了 ws 就要在 ws-opts 裡給出 path 與 Host 標頭,三者與伺服器端不一致都會導致交握失敗。tls: true 時可用 servername 單獨指定 SNI(用於 server 填 IP 而憑證簽給網域的場景)。

Trojan(type: trojan)

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

Trojan 天然運行在 TLS 之上,偽裝為一般 HTTPS 流量。sni 應與伺服器端憑證的網域一致;skip-cert-verify 控制是否跳過憑證驗證,保持 false 是底線——設為 true 意味著放棄對伺服器身份的驗證,任何中間人都能冒充節點。只有自簽憑證的測試環境才有理由臨時打開。代理連線上憑證報錯的成因與排查方法,詳見文章《開啟代理後 HTTPS 憑證報錯的幾種成因》。

策略組是什麼

proxy-groups 在節點與規則之間加了一層抽象:規則不直接指向某個節點,而是指向一個策略組;組內再按既定策略(手選、自動測速、故障轉移等)決定實際出口。好處顯而易見——換節點只需在組裡換,幾百條規則一行不動;訂閱更新導致節點改名,也只影響組的成員清單。組的 proxies 成員可以是節點名、內建策略 DIRECT(直連)與 REJECT(拒絕),也可以是另一個組的名字,由此可以搭出「地區組 → 總出口組」的層級結構;唯一的限制是不能出現循環引用。

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - AUTO
      - HK-01
      - JP-01
      - DIRECT

  - name: "AUTO"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - HK-01
      - JP-01
      - SG-01

五種組類型逐一說明

自動類組(url-test/fallback/load-balance)依賴三個測速參數:url 指定探測位址,慣用回傳 204 空回應的輕量端點;interval 為探測週期(秒),300 是常見平衡點,調得過小會產生持續的測速流量;tolerance 僅 url-test 使用,表示「新舊最佳節點延遲差超過該毫秒數才切換」,用於抑制兩個延遲接近的節點來回抖動。lazy: true(mihomo 擴充)讓組在未被使用時暫停探測,節點很多時能明顯減少背景請求。load-balance 另有 strategy 欄位:consistent-hashing 讓同一目標網站盡量固定走同一節點(登入狀態友善),round-robin 則嚴格輪流。

組的組織建議

實務上建議三層結構:最上層一個 select 總出口(規則主要指向它);中間按地區各建一個 url-test 自動組;底層是節點本身。再為串流媒體、AI 服務這類有落地地區要求的業務單獨建 select 組,成員引用地區組。這樣日常零操作(自動測速接管),特殊業務可人工釘住地區,訂閱更新的影響面也被隔離在地區組內部。

基本格式與比對順序

rules 陣列的每個元素是一行字串,格式為 類型,比對值,策略 三段逗號分隔;策略段可以填組名、節點名或內建的 DIRECT/REJECT。核心對每條新連線自上而下逐條比對,命中第一條即停止——這條紀律決定了一切:精確規則(完整網域)必須寫在寬泛規則(後綴、關鍵字、GEOIP)之前,否則永遠輪不到;清單末尾以 MATCH 兜底,吸收所有未命中流量。規則數量對效能影響很小(網域規則走前綴樹索引),但順序錯誤造成的分流錯誤非常隱蔽,建議每次改動後用日誌驗證命中情況。

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,tracker,REJECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOSITE,category-ads-all,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

規則類型對照

no-resolve 與網域/IP 規則的相互作用

IP 類規則(IP-CIDR/GEOIP)有一個容易被忽略的副作用:當連線目標還是網域時,想比對 IP 就必須先解析——這次解析可能走本地 DNS,造成洩漏,也拖慢比對。給 IP 規則追加第四段 no-resolve,表示「目標本來就是 IP 才比對,是網域就跳過本條」,內網網段規則應當一律帶上。整體排序心法:網域類規則在前、IP 類在後、MATCH 收尾;廣告封鎖(REJECT)放在同類網域規則的最前面。規則書寫的完整專題(含自訂規則應插在訂閱規則之前還是之後)見文章《Clash 自訂規則怎麼寫》。

rule-providers:把規則外置

rule-providers:
  streaming:
    type: http
    behavior: classical
    format: yaml
    url: https://example.com/rules/streaming.yaml
    path: ./rules/streaming.yaml
    interval: 86400

rules:
  - RULE-SET,streaming,PROXY

成千上萬條規則塞進主檔案既難維護也難分享,rule-providers 允許從外部 URL 或本地檔案載入規則集,按 interval 秒數週期刷新。behavior 宣告集合內容形態:domain(純網域清單)、ipcidr(純網段清單)、classical(與 rules 相同的完整三段式)。behavior 與檔案實際內容不匹配時集合會靜默失效,這是外置規則「看起來載入了卻不生效」的頭號原因。

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

訂閱型使用者面對一個結構性矛盾:設定檔由服務商產生,每次更新訂閱整份檔案都會被重新下載覆蓋——你在裡面手動加的規則、改的埠,壽命只到下一次更新為止。正確的做法是把「服務商的基底設定」與「你自己的修改」分離存放,由客戶端在載入時合併成最終設定。這套機制在不同客戶端裡叫法不一:覆寫、Override、Merge、擴充設定,原理一致。

合併的基本語義

合併設定本身也是一份 YAML,只寫你要改動的部分。語義分兩類:標量與映射欄位直接取代——覆寫裡寫 mixed-port: 7891,最終設定的埠就是 7891,寫一個完整的 dns: 區塊則整塊取代基底的 dns;陣列欄位支援前插與追加——多數客戶端約定 prepend- 前綴表示插到基底陣列開頭、append- 前綴表示接到尾端,這對 rules 至關重要:前插的規則優先順序高於訂閱規則,追加的則只能兜底。一份典型覆寫:

mixed-port: 7891
log-level: warning

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

append-proxies:
  - name: "SELF-01"
    type: ss
    server: my.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

腳本覆寫與 proxy-providers

當宣告式合併不夠用——例如要按名字批量過濾節點、給所有組統一插入某個成員——部分客戶端(如 Verge Rev)支援 JavaScript 腳本覆寫:腳本接收解析後的設定物件,回傳修改後的物件,自由度最高,代價是出錯時整份設定載入失敗,應當小步修改、逐次驗證。另一條思路是反過來:不用服務商的整份設定,只透過 proxy-providers 引用訂閱的節點部分,策略組與規則完全自建。這樣訂閱更新只影響節點池,主設定永遠是你自己的,適合已經讀完本手冊、願意維護自有規則體系的使用者:

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

proxy-groups:
  - name: "PROXY"
    type: select
    use:
      - airport

注意組透過 use 欄位引用 provider(而不是 proxies),兩者可以並用;health-check 讓 provider 內的節點也參與可用性探測。

載入前:靜態驗證

改完設定不要直接重啟碰運氣。裝有 mihomo 核心可執行檔的環境下,一條命令即可做純語法與語義檢查,不啟動任何監聽:

mihomo -d . -t -f config.yaml

-t 表示測試模式,-d 指定工作目錄(GeoIP 資料等資源從這裡找),-f 指定待檢檔案。輸出 configuration file ... test is successful 即通過;報錯訊息會給出行號與原因,常見的有:縮排錯誤(yaml: line N)、節點重名(proxy N: name duplicated)、組引用了不存在的成員(proxy group ... proxy not found)、規則策略段拼字錯誤。圖形客戶端在匯入時也會做同等驗證,報錯彈窗裡的訊息與命令列一致,照行號回檔案定位即可。

載入後:驗證分流是否符合預期

設定載入成功不等於行為正確。三步驗證法:第一步看日誌,把 log-level 暫時調到 debug,存取目標網站,日誌會印出這條連線命中的規則與最終出口,是判斷「到底走了哪條規則」的唯一權威依據;第二步看連線面板,圖形客戶端的連線頁即時列出活動連線的目標、命中規則與出口組,適合觀察整體流量分佈;第三步做外部驗證,直連與代理狀態下分別存取 IP 偵測服務,確認出口位址確實隨策略變化。若分流正確但特定應用不走代理,優先懷疑應用程式繞過了系統代理——Windows 市集應用的回送限制就是典型案例,解法見文章《Windows 市集應用不走代理的原因》。

高頻故障速查

更多按症狀組織的問答收錄在常見問題頁;若懷疑問題出在客戶端本身而非設定,可到安裝包頁面換用其他客戶端交叉驗證——全平台首推 Clash Plus,同一份設定在不同客戶端上的表現差異,往往能快速鎖定問題層級。