進階設定 2026-05-08 預計閱讀 9 分鐘

Clash 設定檔 YAML 結構逐段解析:從連接埠設定到 rules 規則段

完整的 Clash 設定檔由通用欄位、DNS、proxies、proxy-groups、rules 等段落組成。本文依序逐段說明各欄位作用、常用值與易錯的縮排格式問題。

設定檔的基本結構與載入方式

Clash 系列客戶端(包括原版 Clash、Clash Meta 及其分支核心 mihomo)讀取的核心設定是一份 YAML 格式文字,通常命名為 config.yaml。無論設定是來自訂閱連結自動下載,還是手動匯入本機檔案,客戶端最終都會把這份文字解析成結構化資料,再依其中宣告的連接埠、代理節點、策略群組、規則依序初始化對應模組。理解這份檔案的段落劃分,是排查「規則未生效」「節點分組顯示為空」等問題的前提。

一份設定檔按慣例由上而下分為五大段落:通用執行參數、DNS 解析設定、proxies 節點清單、proxy-groups 策略群組、rules 規則表。段落之間沒有強制的順序要求,核心解析時是依欄位名稱比對而非依行號比對,但絕大多數訂閱產生工具與主流範本都遵循這個順序,本文也依此順序講解,方便對照實際檔案逐段核對。

YAML 本身是一種依賴縮排表達層級關係的格式,不使用大括號或結束標籤,這意味著同一段落內,子欄位的縮排空格數必須完全一致,且不能用 Tab 字元取代空格。這是新手手動修改設定時最容易踩坑的地方,後文會另闢一節詳細說明。

通用欄位:連接埠、模式與日誌等級

檔案最頂端通常是一組獨立的鍵值對,不屬於任何巢狀結構,常見欄位如下:

port: 7890
socks-port: 7891
mixed-port: 7890
allow-lan: true
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: ""

各欄位的作用分別是:

  • port / socks-port:分別宣告 HTTP 代理連接埠與 SOCKS5 代理連接埠,系統或應用程式手動設定代理時需要用到具體數值。
  • mixed-port:一個連接埠同時支援 HTTP 與 SOCKS5 協定的混合監聽,設定它之後前兩項可以省略,大多數圖形化客戶端預設只使用這一項。
  • allow-lan:是否允許區域網路內其他裝置透過本機代理連接埠連線,手機、平板共用同一台電腦的代理時需要開啟。
  • mode:全域執行模式,常見取值 rule(依規則表分流)、global(全部流量走同一個代理)、direct(全部直連不經代理)。日常使用應選 rule,只有排查問題時才暫時切換到另外兩種做單一變因測試。
  • log-level:日誌詳細程度,取值 silent、error、warning、info、debug,排查連線失敗時把它暫時調成 debug 能看到更完整的交握過程。
  • external-controller:開放給外部管理面板(如內建 Dashboard)呼叫的 API 位址與連接埠,圖形化客戶端多數已內建管理介面,一般使用者無需更動。
  • secret:存取上述 API 的驗證密碼,留空代表不設密碼,僅限本機使用時可以不填,若開放給區域網路存取建議設定。

此外,TUN 模式相關欄位也放在這一段:

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

TUN 模式讓 Clash 建立一張虛擬網路卡,從系統網路層面接管全域流量,不再依賴應用程式逐一設定 HTTP/SOCKS 代理,常用於處理不支援代理設定的客戶端軟體或系統層級流量。stack 決定虛擬網路卡使用的協定堆疊實作,system 依賴系統內建能力,相容性較佳;gvisor 是使用者態實作,某些平台下效能更穩定。開啟 TUN 模式通常需要客戶端以系統管理員或 root 權限執行,這是獨立於代理連接埠設定之外的另一套流量接管機制。

DNS 段設定詳解

DNS 段決定網域名稱解析請求如何處理,直接影響分流準確性與解析速度,是最容易被忽略卻又最容易出問題的部分:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://dns.google
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
  • default-nameserver:用於解析下面 nameserver、fallback 欄位裡那些 DoH/DoT 伺服器網域名稱本身,必須是純 IP 位址,不能再套一層網域解析,否則會出現循環依賴。
  • nameserver:實際用於解析一般網域名稱的伺服器清單,支援傳統 UDP、DoH(https://)、DoT(tls://)等多種協定前綴。
  • fallback:當依規則判斷某個網域應該走代理時使用的備用解析伺服器,通常填寫海外或加密解析服務,避免污染。
  • fake-ip-range:開啟 fake-ip 模式後,給網域臨時分配的虛擬 IP 位址範圍,客戶端拿到這個虛擬 IP 後再由核心在建立連線時還原成真實目標,這是規則依網域比對卻要在 IP 層轉發之間的一層橋接機制。
  • fake-ip-filter:宣告哪些網域不走 fake-ip、直接回傳真實 IP,常見於區域網路裝置探索、直播彈幕等依賴真實 IP 的情境,漏設會導致這類功能異常。

DNS 設定錯誤的典型表現是:規則表看起來完全正確,但某些網站依然走錯了出口,或是出現連得上卻經常逾時的情況。這類問題往往不是規則寫錯,而是網域解析階段就已經拿到了不符預期的結果,建議排查順序是先看 DNS 段再看 rules 段。

proxies 與 proxy-groups 段:節點與策略群組的關係

proxies 是一個清單,每一項描述一個具體的代理節點,包含協定類型、伺服器位址、連接埠、加密方式等連線參數,範例:

proxies:
  - name: "HK-01"
    type: ss
    server: example-hk.example.com
    port: 8443
    cipher: aes-256-gcm
    password: "your-password"
  - name: "SG-02"
    type: vmess
    server: example-sg.example.com
    port: 443
    uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    alterId: 0
    cipher: auto

常見的 type 取值包括 ss(Shadowsocks)、vmess、trojan、socks5、http 等,不同協定要求填寫的欄位不完全相同,缺少必填欄位會導致該節點在客戶端裡顯示為無法使用或直接被跳過載入。這部分內容如果來自訂閱連結,通常不需要手動編寫,由訂閱提供方產生;手動新增節點時才需要逐項核對欄位名稱是否與協定相符。

proxy-groups 段把上面列出的節點組織成可供規則呼叫的「策略群組」,規則表引用的是策略群組名稱,而不是單個節點名稱,這樣切換出口時只需要在策略群組內部調整,不需要更動規則表。常見策略群組類型:

type 取值行為說明典型用途
select手動在多個節點/子策略群組之間切換,不做自動判斷日常手動選線
url-test定時向指定 URL 發起測速,自動選用延遲最低的節點自動擇優
fallback依清單順序偵測可用性,首個可用節點失效才切換下一個主備容錯
load-balance依雜湊或輪詢演算法在多個節點間分攤連線多節點分攤負載
 
proxy-groups:
  - name: "自動選擇"
    type: url-test
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300
  - name: "手動選擇"
    type: select
    proxies:
      - 自動選擇
      - HK-01
      - SG-02
      - DIRECT

注意策略群組也可以互相巢狀引用(如上面「手動選擇」把「自動選擇」當作一個選項列進去),但不能出現循環引用,否則核心載入設定時會直接報錯拒絕啟動。

rules 規則段:撰寫順序與比對邏輯

rules 段是一份由上到下依序比對的清單,核心對每一筆網路請求依序逐條比對規則,命中第一條符合的規則後立即執行對應策略,不再繼續往下比對。這意味著規則的排列順序本身就是邏輯的一部分,順序寫錯會導致後面精確的規則永遠輪不到。

rules:
  - DOMAIN-SUFFIX,google.com,自動選擇
  - DOMAIN-KEYWORD,github,自動選擇
  - DOMAIN,ad.example.com,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,手動選擇

常見比對類型包括 DOMAIN(精確網域)、DOMAIN-SUFFIX(網域尾碼,能連帶比對子網域)、DOMAIN-KEYWORD(網域中包含關鍵字即比對成功)、IP-CIDR(依 IP 範圍比對)、GEOIP(依 IP 所屬國家/地區資料庫比對)、MATCH(兜底規則,放在最後一行,比對所有未命中前面規則的請求)。缺少 MATCH 兜底行是設定檔常見的疏漏,會導致部分請求找不到對應策略而走向不可預期的預設行為。

規則右側填寫的目標必須是已在 proxy-groups 裡定義好的策略群組名稱,或是內建的 DIRECT(直連)、REJECT(拒絕連線,常用於封鎖廣告網域)。策略群組名稱區分大小寫,且不能包含規則表裡未宣告過的空策略群組,否則同樣會在載入階段報錯。

注意 NOTICE 規則集(rule-provider)引用的遠端規則檔本質上也是依上述幾種比對類型逐行組成,只是被獨立存放並可定期更新。使用 RULE-SET 類型規則前,需要先在 rule-providers 段宣告對應規則集的來源位址與本機快取路徑,否則規則表載入時會因引用不存在的規則集而失敗。

常見縮排錯誤與排查方法

YAML 對縮排的要求比多數設定格式更嚴格,以下幾類問題在手動編輯設定檔時最常出現:

  1. 同層欄位縮排空格數不一致

    同一個清單下的多個項目,前面的空格數量必須完全相同,哪怕只差一個空格,核心也會判定為層級錯誤而拒絕載入整份檔案,而不是僅跳過出錯的那一行。

  2. Tab 與空格混用

    多數文字編輯器預設用 Tab 縮排,但 YAML 標準不接受 Tab 字元,建議使用支援「將 Tab 轉換為空格」功能的編輯器,並統一採用兩個空格為一級縮排。

  3. 冒號後缺少空格

    YAML 的鍵值對要求冒號後接一個空格再寫值,例如 name:HK-01 缺少空格會被解析成一個不合法的鍵名,應寫成 name: HK-01。

  4. 字串未加引號導致誤判類型

    密碼、UUID 等欄位如果以數字開頭或包含特殊符號,建議明確加上雙引號,否則可能被解析成數字或布林值而不是字串,導致連線驗證失敗。

排查這類問題最直接的方法,是把修改後的設定檔放進任意線上 YAML 語法檢查工具先跑一遍縮排檢查,確認語法層面無誤後再交給客戶端載入;客戶端啟動日誌(或把 log-level 調成 debug 後的輸出)通常也會明確指出載入失敗的具體行號,依行號定位比逐段肉眼檢查效率更高。修改設定檔建議先備份原始檔案,改動後如果客戶端無法正常載入,可以直接回退到備份版本,避免因排查耗時導致長時間無法連上網路。

下載客戶端