Clash 設定檔結構解析：從 port 到 rules 逐段讀懂 YAML

先了解 YAML 的階層與解析規則

Clash 設定檔通常採用 YAML。它不是一串互相獨立的開關，而是一棵具有階層的設定樹：頂層欄位控制核心行為，縮排欄位隸屬於上一層物件，以短橫線開頭的內容則代表列表項目。閱讀設定時，應先確認縮排，再判斷欄位用途。只看欄位名稱、不看所在階層，很容易把有效參數放錯位置。

縮排、冒號與列表

• 縮排統一使用空格，常見寫法是每層 2 個空格，請勿混用 Tab。
• 鍵名後的冒號需要接一個空格，例如 mode: rule。
• 像 dns:、profile: 這類欄位底下還有子項目，子項目必須繼續縮排。
• proxies:、proxy-groups: 與 rules: 通常包含列表，每個項目都以 - 開頭。
• 名稱若包含冒號、井字號、花括號等特殊字元，建議使用單引號或雙引號包住。

mode: rule
log-level: info

profile:
  store-selected: true
  store-fake-ip: true

proxy-groups:
  - name: '節點選擇'
    type: select
    proxies:
      - '自動選擇'
      - DIRECT

上例中，store-selected 屬於 profile，而 name、type 與 proxies 共同構成一個策略組物件。若 type 與 name 的縮排不一致，YAML 即使能通過解析，也可能形成完全不同的資料結構。

通用欄位：連接埠、區域網路與執行模式

設定檔開頭通常會放置監聽連接埠、執行模式、日誌層級與控制連接埠。這些欄位決定應用程式如何接收系統流量，以及圖形化用戶端如何與 Clash Meta（mihomo）核心通訊。

port: 7890
socks-port: 7891
mixed-port: 7893
redir-port: 7892
tproxy-port: 7895

allow-lan: false
bind-address: '*'
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: 'change-this-controller-secret'

不同連接埠分別接收哪些流量

port

HTTP 代理監聽連接埠。範例中的位址通常寫成 127.0.0.1:7890。

socks-port

SOCKS5 代理連接埠。支援 SOCKS5 的命令列工具或應用程式可以連線至 127.0.0.1:7891。

mixed-port

在同一個連接埠接收 HTTP 與 SOCKS5 請求。用戶端只需提供一個本機代理入口時，通常保留這項即可。

redir-port

用於 Linux 重新導向情境，通常搭配 iptables 或相容的流量轉送規則使用。

tproxy-port

用於 Linux TPROXY 透明代理，可處理需要保留目標位址的轉送流量。

這些連接埠不必全部啟用。桌面用戶端使用系統代理時，常見做法是只啟用 mixed-port: 7890，或分別啟用 HTTP 與 SOCKS 連接埠。若日誌出現 address already in use，應檢查其他代理程式、舊核心程序或開發服務是否已佔用相同連接埠，再修改設定或結束衝突程序。

mode、allow-lan 與控制介面

• mode: rule 會依照 rules 由上至下比對，是日常分流設定最常見的模式。
• mode: global 會將連線交由全域策略組處理，不再依一般規則逐條分流。
• mode: direct 會讓連線直接存取，適合暫時判斷問題是否來自代理鏈路。
• allow-lan: true 允許區域網路裝置連線至監聽連接埠。啟用後還需檢查系統防火牆、監聽位址與網路信任範圍。
• external-controller 是 REST API 控制介面。僅供本機用戶端使用時，應繫結至 127.0.0.1；需要遠端面板時，應設定有效的 secret 並限制網路存取範圍。

bind-address: '*' 表示監聽可用位址，但是否真正對區域網路開放，仍受 allow-lan 與防火牆控制。不要把「監聽位址」、「允許區域網路」和「控制介面」視為同一項設定，它們分別管理代理入口、區域網路存取許可與核心管理介面。

DNS 區塊：解析鏈路與 Fake-IP

DNS 設定決定網域名稱如何解析，也會影響網域規則能否在連線階段繼續比對。Clash Meta（mihomo）常見的增強模式包括 fake-ip 與 redir-host。前者會從保留位址範圍回傳一個對映位址，並在核心中保留網域與連線的對應關係；後者則更接近回傳實際解析結果的流程。

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'time.*.com'
    - 'time.*.gov'
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - 'https://dns.alidns.com/dns-query'
    - 'https://doh.pub/dns-query'
  fallback:
    - 'https://1.1.1.1/dns-query'
    - 'https://dns.google/dns-query'
  fallback-filter:
    geoip: true
    geoip-code: CN

三類 nameserver 的分工

• default-nameserver 通常填寫可直接連線的 IP 位址，用來解析 DoH 或 DoT 伺服器本身的網域名稱，避免啟動階段形成循環依賴。
• nameserver 是主要解析器，可以使用一般 UDP DNS，也可以填寫 DoH、DoT 等加密解析位址。
• fallback 是備用解析器。是否採用其結果，會受到 fallback-filter 等條件影響。

listen: 127.0.0.1:1053 只允許本機存取 DNS 監聽連接埠。若用戶端已自動接管系統 DNS，通常不必手動將作業系統 DNS 改至此連接埠。TUN 模式下，核心也可能透過 DNS 劫持接收 53 連接埠的請求，實際行為取決於用戶端產生的 TUN 設定。

fake-ip-filter 應該放入哪些項目

區域網路網域、裝置探索網域、部分時間同步網域，以及依賴回傳實際位址的應用程式網域，可以加入 fake-ip-filter。不要任意將大範圍萬用字元加入過濾列表，否則大量網域會繞過 Fake-IP 對映，網域規則的命中方式與首次連線延遲都可能改變。

proxies：如何定義單一節點

proxies 是靜態節點列表。每個節點至少需要名稱、協定類型、伺服器位址與連接埠，之後再依協定填寫驗證與傳輸參數。節點欄位必須與伺服器端的實際設定一致；協定名稱相同，不代表連接埠、加密方式、TLS 主機名稱或 WebSocket 路徑可以互換。

proxies:
  - name: '範例-Trojan'
    type: trojan
    server: edge.example.com
    port: 443
    password: 'example-password'
    udp: true
    sni: edge.example.com
    skip-cert-verify: false

  - name: '範例-VMess'
    type: vmess
    server: vm.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000001
    alterId: 0
    cipher: auto
    udp: true
    tls: true
    servername: vm.example.com
    network: ws
    ws-opts:
      path: /connect
      headers:
        Host: vm.example.com

節點名稱是後續引用的鍵值

name 不只是介面顯示文字，策略組也會透過完全相同的字串引用節點。若節點名稱是 範例-Trojan，策略組中寫成 範例 Trojan 就會變成不存在的引用。重新命名節點時，請同步檢查所有 proxy-groups、規則目標與鏈式代理設定。

TLS 與傳輸層欄位必須相互對應

• server 是建立連線時使用的伺服器位址。
• sni 或 servername 用於 TLS 交握時的伺服器名稱，應依節點提供者給出的值填寫。
• skip-cert-verify: false 表示正常驗證伺服器端憑證。
• network: ws 表示使用 WebSocket 傳輸，對應參數位於 ws-opts。
• udp: true 表示允許該節點處理 UDP，最終能否通訊仍取決於協定、伺服器端與網路環境。

從訂閱匯入時，節點經常不是直接寫入 proxies，而是由用戶端轉換後產生，或透過 proxy-providers 載入。兩種方式可以並存，但同名節點會增加策略組引用與排錯的難度。

proxy-providers 與 proxy-groups：從節點到策略

proxy-providers 負責從本機檔案或遠端網址載入一批節點，proxy-groups 則將節點組織成可選擇、測速或進行故障切換的策略。規則通常指向策略組，而不是直接指向特定節點。

proxy-providers:
  provider-main:
    type: http
    url: 'https://subscription.example.com/clash'
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      url: 'https://www.gstatic.com/generate_204'
      interval: 600

proxy-groups:
  - name: '節點選擇'
    type: select
    proxies:
      - '自動選擇'
      - DIRECT
    use:
      - provider-main

  - name: '自動選擇'
    type: url-test
    use:
      - provider-main
    url: 'https://www.gstatic.com/generate_204'
    interval: 300
    tolerance: 80

  - name: '故障切換'
    type: fallback
    use:
      - provider-main
    url: 'https://www.gstatic.com/generate_204'
    interval: 300

常見的策略組類型

• select：手動選擇節點或另一個策略組，適合放在規則最後引用的位置。
• url-test：定期請求測試網址，並從候選節點中選擇延遲較低者。範例每 300 秒檢測一次，tolerance: 80 用來減少延遲接近時的頻繁切換。
• fallback：依可用性選擇候選項目，目前連線路徑失效時切換至後續可用節點。
• load-balance：依策略在多個節點間分配連線，不等於直接疊加單一下載工作的頻寬。

proxies 用於明確列出節點或策略組名稱，use 則用於引用 provider。策略組可以繼續巢狀，例如「節點選擇」包含「自動選擇」，而「自動選擇」再從 provider 取得節點。檢查設定時，應沿著引用關係逐層確認名稱存在，避免形成自己引用自己的循環。

rules：依序執行的分流表

rules 是設定檔末尾最關鍵的列表之一。Clash 會依由上至下的順序比對，命中一條後通常不再繼續檢查。因此，更具體的網域、程序或網段規則應放在前面，範圍較大的 GeoIP、GeoSite 與兜底規則則放在後面。

rules:
  - DOMAIN-SUFFIX,example.org,節點選擇
  - DOMAIN,api.example.net,自動選擇
  - DOMAIN-KEYWORD,stream,節點選擇
  - 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,no-resolve
  - MATCH,節點選擇

規則由比對器、值與目標組成

以 DOMAIN-SUFFIX,example.org,節點選擇 為例，第一段是規則類型，第二段是待比對值，第三段是命中後使用的策略。策略名稱必須與 proxy-groups 中的名稱完全一致，也可以使用 DIRECT 或 REJECT 這類內建目標。

• DOMAIN 精確比對一個完整網域名稱。
• DOMAIN-SUFFIX 比對指定網域及其子網域，適合依網站範圍進行分流。
• DOMAIN-KEYWORD 依網域中的關鍵字比對，涵蓋範圍較廣，應避免使用過短的關鍵字。
• IP-CIDR 與 IP-CIDR6 分別比對 IPv4 與 IPv6 位址範圍。
• GEOIP 依賴地理 IP 資料庫判斷目標位址所屬區域。
• GEOSITE 依賴網域分類資料庫；可用分類取決於目前的 mihomo 版本與資料檔案。
• MATCH 比對先前尚未命中的流量，應放在規則列表末尾。

no-resolve 表示這條 IP 類規則不為了比對而額外觸發網域解析。它常用於區域網路網段或 GEOIP 規則，但是否加入仍應配合前面的 DNS 模式與規則需求判斷。將它加到網域規則沒有意義。

規則順序錯誤的典型表現

1. 把 MATCH 放在中間，後續規則就永遠沒有機會執行。
2. 先寫範圍寬泛的 DOMAIN-KEYWORD，導致後面的精確網域規則無法命中。
3. 區域網路網段未提前設定直連，存取路由器、NAS 或開發伺服器時被送入代理。
4. 規則目標名稱已修改，但規則表仍引用舊策略組，載入時提示找不到代理或策略。
5. 使用 GEOSITE、GEOIP 卻未準備對應資料庫，導致規則載入或比對異常。

TUN 與 profile：常見的尾端設定

TUN 模式透過虛擬網路介面接管更多系統流量，適合無法主動讀取系統代理設定的程式。它與 mixed-port 並不衝突：前者從網路層接管，後者仍可供明確支援 HTTP 或 SOCKS5 的應用程式使用。

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
  auto-route: true
  auto-detect-interface: true
  strict-route: false

profile:
  store-selected: true
  store-fake-ip: true

auto-route 讓核心自動設定路由，auto-detect-interface 用於辨識目前的出口網卡。不同作業系統對 TUN 驅動程式、管理員權限與路由設定的要求各異，圖形化用戶端通常會在「設定」→「網路」或「設定」→「TUN 模式」中產生並管理這些參數。若用戶端已代管 TUN 設定，不應同時在多個覆寫層重複宣告同名欄位。

store-selected: true 用於儲存策略組選擇，重新啟動後會繼續使用上次選取的項目。store-fake-ip: true 會儲存 Fake-IP 對映，有助於減少重新啟動後對映變更造成的連線中斷。這兩個欄位屬於 profile，不是 dns 的子項目。

從載入到命中的完整檢查順序

設定能通過 YAML 語法檢查，不代表節點一定可以連線；節點可以連線，也不代表規則與 DNS 已依預期運作。排查時依固定順序逐步檢查，比同時修改多個區段更容易定位問題。

1. 檢查 YAML 解析。先查看用戶端設定頁或核心日誌，確認沒有縮排、重複鍵、未知欄位或型別錯誤。
2. 檢查本機監聽。確認 7890、7891、7893、9090、1053 等實際啟用的連接埠未被其他程序佔用。
3. 檢查節點交握。在代理頁選取單一節點進行延遲測試，再查看 TLS、驗證、逾時或網路無法連線等日誌。
4. 檢查策略組引用。確認規則目標、策略組成員與 provider 名稱完全一致。
5. 檢查 DNS。觀察網域查詢是否逾時，以及 DoH 伺服器網域能否透過 default-nameserver 完成初始解析。
6. 檢查規則命中。開啟連線或日誌頁面，查看目標網域命中了哪條規則，最後選用了哪個策略組與節點。
7. 最後啟用 TUN。先確認一般系統代理運作正常，再開啟 TUN，以便區分節點問題與路由接管問題。

設定檔的閱讀路線

閱讀陌生設定時，可以從頂層連接埠開始，依序查看 dns、proxies 或 proxy-providers、proxy-groups、rules，最後檢查 tun 與 profile。這條路線正好對應流量處理流程：應用程式先進入本機連接埠或 TUN，網域經 DNS 解析後，由規則選擇策略組，再由策略組選定具體節點。

真正決定設定是否容易維護的，不是欄位數量，而是引用關係是否清楚。節點名稱、provider 名稱、策略組名稱與規則目標構成一條連續鏈路。修改其中任何名稱，都要沿著鏈路檢查後續引用。完成修改後，使用用戶端的設定驗證功能重新載入，再透過連線日誌確認實際命中結果。