Clash 設定檔欄位參考

YAML 結構總覽與載入順序

頂層映射決定核心讀取的內容

Clash 設定檔本質上是一份 YAML 文件。最外層通常由多個鍵值組成：連接埠與執行參數使用純量，dns 使用巢狀映射，proxies、proxy-groups 與 rules 使用清單。核心啟動時會先解析 YAML 語法，再驗證欄位型別與引用關係，最後建立監聽連接埠、DNS 模組、代理出口、策略組與規則樹。語法能成功解析，不代表設定一定可以執行；例如策略組引用不存在的節點，往往要到設定驗證階段才會報錯。

YAML 以縮排表示層級，不使用大括號包住物件。建議統一使用兩個空格縮排，禁止在同一份檔案中混用定位字元。冒號後需要空格；清單項目以連字號加空格開頭。包含冒號、井字號、星號、方括號或前後空格的名稱應加上引號，避免被解析器視為語法符號。節點名稱雖可使用中文，但策略名稱與規則目標會反覆引用，名稱越短越容易檢查。

mixed-port: 7890
mode: rule
log-level: info
ipv6: false

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip

proxies:
  - name: "範例節點-A"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

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

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

上例構成一個最小閉環：入站流量進入 mixed-port，網域解析交由 DNS 模組處理，規則將請求分配給「節點選擇」，策略組再選擇具體節點或 DIRECT。如果刪除 proxy-groups，規則目標就必須直接寫節點名稱或內建動作；如果刪除 rules，在 rule 模式下通常無法得到完整的分流行為。實際訂閱會包含更多節點，但結構關係仍然相同。

純量、清單與映射的型別不能互換

mode: rule 是純量，不能寫成清單；rules 是有順序的清單，不能改成以規則類型為鍵的映射；dns 是映射，其中每個子欄位都有自己的型別。布林值建議寫成小寫 true 或 false，不要用「是」、「否」或加引號的字串代替。連接埠應寫整數，寫成 "7890" 有時仍能相容處理，但會增加不同用戶端之間的差異。

錨點與別名是 YAML 內建功能，例如用 &common 定義共用參數，再用 <<: *common 合併。它可以減少重複，卻不適合需要在多個用戶端之間同步的訂閱設定，因為部分覆寫器會在序列化時展開或遺失錨點。對於需要長期維護的檔案，優先明確寫出關鍵欄位；只有確認整個匯入流程都能保留 YAML 語意時，才使用錨點。

載入路徑、訂閱檔案與執行時設定

圖形化用戶端通常會先將遠端訂閱下載到本機設定目錄，再把選定的設定交給 mihomo 核心。介面中看到的設定名稱、訂閱網址與更新時間屬於用戶端管理層，不一定會出現在 YAML 中。核心只處理最終產生的設定檔。部分用戶端還會在載入前套用腳本、全域覆寫或本機修補，因此從介面匯出的檔案可能與訂閱伺服器回傳的原文不同。

排查解析失敗時，應先區分下載階段與解析階段。瀏覽器能開啟訂閱網址，只能證明伺服器有回應，不能證明回應內容是 YAML；回傳登入頁、流量限制提示或 JSON 錯誤物件時，用戶端仍會將它儲存下來，接著在第一行報出語法錯誤。可依訂閱解析失敗自查步驟核對回應狀態、內容類型、縮排與快取。若要手動編輯，應保留一份原始檔案，將修改拆成小批次，每次只調整一個結構區段並重新驗證。

一般欄位：連接埠、模式與控制介面

入站連接埠與區域網路存取

port 只提供 HTTP 代理，socks-port 只提供 SOCKS5 代理，mixed-port 則在同一個連接埠上相容兩類連線。桌面用戶端通常使用 mixed-port，讓系統代理、瀏覽器與支援 SOCKS 的工具共用同一個監聽連接埠。三者不必同時啟用；同時設定時必須使用不同連接埠，否則核心無法繫結監聽位址。連接埠數字本身沒有網路加速含義，只要未被佔用且與系統代理設定一致即可。

allow-lan 控制是否允許區域網路裝置連線。設為 false 時，通常只接受本機存取；設為 true 後，還要檢查 bind-address、作業系統防火牆與路由器隔離設定。開放區域網路監聽會擴大可存取範圍，應同時設定存取認證或限制防火牆來源，不要把代理連接埠直接暴露到公網。行動裝置借用電腦代理時，填寫的是電腦的區域網路位址和 Clash 入站連接埠，而不是遠端節點伺服器位址。

mixed-port: 7890
allow-lan: false
bind-address: "*"
authentication:
  - "local-user:your-password"

mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

只有確實需要區域網路共用時才啟用 allow-lan。部分用戶端會用介面開關覆蓋 YAML 中的值，因此修改後應回到執行狀態頁確認實際監聽位址。若系統代理已啟用但瀏覽器無法連線，可先檢查用戶端日誌是否出現「address already in use」，再確認系統代理連接埠是否仍指向舊設定。Windows 應用程式容器也可能受到 UWP 回送限制，這屬於系統網路權限問題，不是規則欄位本身的問題。

mode 決定規則是否參與決策

mode 常用值為 rule、global 與 direct。在 rule 模式下，請求會依序比對 rules；在 global 模式下，流量通常交給全域策略組；在 direct 模式下，會直接建立連線，不使用一般規則分流。調試設定時應優先維持 rule，因為它最接近長期使用狀態。暫時切換到全域模式可以判斷某個故障是否由規則造成，但不能據此證明 DNS、節點或系統代理全部正常。

圖形化用戶端中的模式開關經常屬於執行時狀態。訂閱重新整理後，用戶端可能保留上次選擇，也可能重新採用 YAML 的 mode。需要穩定行為時，應同時檢查設定檔與用戶端的全域覆寫設定。規則模式下「某網站走錯策略」應查看規則命中記錄；全域模式下所有請求都進入同一個策略，修改網域規則不會產生效果，這是排錯時最常見的情境遺漏。

日誌、IPv6 與並行連線

log-level 控制日誌詳細程度，常用值包括 silent、error、warning、info 與 debug。日常使用維持 info 即可；定位解析、握手或規則命中問題時，暫時切換到 debug，排查結束後再恢復，避免大量日誌掩蓋關鍵資訊。日誌中的網域、節點名稱與目標位址可能反映存取行為，轉發排錯截圖前應先刪除敏感內容。

ipv6 決定核心是否處理 IPv6 相關解析與連線。關閉它不等於作業系統完全停用 IPv6，只表示 Clash 的對應模組採用受限行為。網路具備穩定 IPv6，且代理節點與上游 DNS 也支援時可以啟用；若出現部分網站優先取得 AAAA 記錄卻無法連線，可先對照 DNS 查詢結果與節點能力，而不是直接反覆切換規則。tcp-concurrent 允許對目標位址進行並行連線嘗試，在多位址解析情境中可能縮短等待時間，但也會增加短時間內的連線數量。

unified-delay 用於讓延遲測試更接近統一的計算標準。它會影響策略組測試結果的解讀，不會把不可用節點變成可用。延遲測試只代表連線到測試位址的情況，實際存取還會受到目標網站、協定握手、出口品質與規則路徑影響，因此不應只依單次數值排列節點。節點選擇方法可參閱延遲、倍率、地區與協定說明。

外部控制器與管理介面

external-controller 會公開核心控制介面，圖形化用戶端透過它讀取連線、切換策略及重新載入設定。常見的監聽形式是本機位址加連接埠。若繫結到非本機位址，應設定 secret 並透過防火牆限制來源。external-ui 指向靜態管理介面目錄，只負責前端資源，不會自動下載介面檔案。一般圖形化用戶端已包含管理層時，無須另行設定。

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"
external-ui: dashboard

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

profile.store-selected 用於儲存策略組選擇，重新啟動後可恢復上次選項；profile.store-fake-ip 用於儲存 Fake-IP 對映，減少重新啟動後對映變化造成的影響。實際持久化位置由用戶端工作目錄決定。設定檔只宣告意圖，如果用戶端每次啟動都清理快取目錄，持久化欄位也無法保留狀態。多裝置同步時不建議直接同步整個執行目錄，應同步訂閱、覆寫與明確需要的設定檔，避免一併複製鎖定檔、快取與平台路徑。

DNS 欄位、Fake-IP 與解析路徑

DNS 模組位於連線決策之前

網域請求通常會先經過 DNS 解析，再由規則與出口建立連線。Clash 的 DNS 模組不只負責「將網域轉換成位址」，還會影響網域規則能否保留、Fake-IP 對映如何建立、不同上游如何分流，以及由誰解析代理節點伺服器位址。許多「代理已連線但網頁打不開」的問題，實際上發生在 DNS 上游無法連線、回傳結果遭污染、Fake-IP 過濾不完整或系統請求繞過核心。

dns.enable 啟用內建 DNS，listen 定義監聽位址。桌面用戶端可能透過系統 DNS 劫持、TUN 或本機連接埠將查詢送入此模組。只在 YAML 中啟用 DNS，不代表作業系統一定會使用它；還需要用戶端正確設定系統 DNS 或啟用相應的接管方式。反過來，若連接埠已被其他 DNS 服務佔用，核心會啟動失敗或略過監聽。

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.example/dns-query
    - tls://dns.example:853
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver-policy:
    "geosite:cn":
      - 223.5.5.5

default-nameserver 主要用於解析加密 DNS 上游自身的網域，因此通常填寫可直接存取的 IP 位址。若這裡仍填寫網域，就可能形成「需要先解析上游網域才能使用上游，而解析上游網域又依賴該上游」的循環。nameserver 是主要查詢上游，可使用 UDP、TCP、DoT 或 DoH 等形式。範例中的 dns.example 是虛構網域，實際設定必須換成可用服務。

proxy-server-nameserver 專門處理代理節點伺服器網域。節點的 server 若寫入網域，核心必須先取得其實際位址才能建立代理連線；若這一步又被送入尚未建立的代理鏈，就會形成依賴迴圈。為此欄位指定可直接連線的解析上游，可以將節點網域解析與一般網站查詢分開。節點直接填寫 IP 時不會經過這一步，但也會失去網域切換後端位址的能力。

Fake-IP 模式如何保留網域資訊

使用 enhanced-mode: fake-ip 時，核心會先向應用程式回傳保留位址範圍中的對映位址，應用程式接著連線到該位址，核心再透過對映表還原原始網域並執行規則。即使應用程式只發起 IP 連線，核心仍能依網域規則進行判斷。fake-ip-range 預設應使用專門保留的測試位址範圍，不應與實際區域網路、企業 VPN 或容器網路重疊。

Fake-IP 不是遠端伺服器位址，也不會被傳送到公網。它是本機核心維護的暫時對映。看到系統連線指向 198.18.x.x 並不表示 DNS 解析錯誤；真正需要檢查的是該連線是否由 Clash 接管。如果應用程式繞過系統代理，同時 TUN 又未接管流量，它會直接嘗試連線到保留位址，表現為逾時。此時應檢查接管路徑，而不是把所有網域加入過濾清單。

fake-ip-filter 用於讓特定網域回傳實際位址。區域網路服務、網路探測、時間同步、部分遊戲或需要本機探索的服務，可能不適合使用對映位址。過濾範圍應盡量精確，過寬的萬用字元會讓大量網域失去 Fake-IP 帶來的網域識別能力。修改後還要清除舊 DNS 快取或重新啟動相關應用程式，否則應用程式可能繼續使用先前的結果。

dns:
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"
    - "time.*.com"
    - "time.*.gov"

redir-host 與 Fake-IP 的取捨

redir-host 回傳實際解析位址，理解路徑較直接，對依賴真實 IP 的應用程式相容性較好；但在透明代理情境中，核心可能只能看到目標 IP，需要透過嗅探或解析對映還原網域，網域規則的穩定性取決於接管鏈路。fake-ip 更適合希望完整保留網域資訊的 TUN 情境，但需要處理少數不接受保留位址的程式。選擇模式時應根據系統接管方式與應用程式相容性決定，不應把它當成節點速度開關。

respect-rules 讓 DNS 查詢參考現有規則，但它要求解析上游與代理策略之間沒有循環依賴。若主要 DoH 上游必須經過代理，而代理節點伺服器網域又依賴主要 DoH，就可能無法完成初始連線。解決方向是為節點網域準備獨立的直連解析器，或讓至少一個基礎上游無須代理即可存取。日誌持續出現 DNS timeout 時，應從依賴鏈最底層開始核對。

nameserver-policy 的分流邊界

nameserver-policy 依網域或 geosite 集合選擇解析上游。它決定「要向哪裡查詢 DNS」，不會直接決定後續連線使用 DIRECT 還是代理。連線策略仍由 rules 控制。若同一網域在不同上游取得不同位址，解析策略會間接影響連線目標，因此 DNS 分流與規則分流應採用一致的地域意圖，避免中國大陸網域由遠端上游解析到跨區位址，或代理網域被本地上游回傳異常結果。

排查 DNS 時建議分三步：先確認系統查詢已進入 Clash；再確認 Clash 能存取指定上游；最後確認回傳位址與規則命中符合預期。只測試瀏覽器頁面，無法區分快取、HTTP/3 與系統代理的影響。可以暫時關閉瀏覽器安全 DNS、清除應用程式快取，並在核心日誌中觀察網域查詢與連線記錄。更完整的網路排查順序請見系統代理、DNS 與規則模式排查清單。

代理節點欄位與協定參數

每個節點都需要可引用的唯一名稱

proxies 中的每一項代表一個靜態出口節點。一般欄位包括 name、type、server、port，其餘欄位由協定決定。name 是策略組與規則引用的識別名稱，同一份設定內應保持唯一。名稱重複時，用戶端可能覆蓋前一項，也可能在介面中顯示兩個同名選項，之後便無法判斷規則實際引用哪一個。訂閱產生器應在節點名稱中保留地區或用途，但不宜塞入過長的公告文字。

server 可以是 IP 或網域，不能附帶協定前綴與路徑。port 是遠端服務連接埠，不是本機的 mixed-port。連線失敗時要區分本機入站與遠端出站：系統代理先連到本機連接埠，核心再依節點欄位連線到伺服器。把兩組連接埠混用，是手動設定中的常見錯誤。

proxies:
  - name: "SS-範例"
    type: ss
    server: 192.0.2.20
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojan-範例"
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: gateway.example.com
    skip-cert-verify: false
    udp: true

  - name: "VMess-範例"
    type: vmess
    server: 192.0.2.30
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    alterId: 0
    cipher: auto
    tls: true
    servername: edge.example.com
    network: ws
    ws-opts:
      path: /proxy
      headers:
        Host: edge.example.com

範例中的位址與認證資料僅用於展示欄位關係。Shadowsocks 的 cipher 必須與伺服器端一致；Trojan 通常透過 TLS 建立連線，sni 用於傳送伺服器名稱；VMess 的 uuid、傳輸方式、TLS 與 WebSocket 參數必須成組對應。單獨修改其中一個欄位通常無法解決握手失敗，反而會造成用戶端與伺服器端設定不匹配。

TLS、SNI 與憑證驗證

啟用 TLS 的協定通常需要區分連線位址、SNI 與 HTTP Host。server 決定連線到哪裡，sni 或 servername 決定 TLS 握手宣告哪個主機名稱，WebSocket 的 Host 則屬於 HTTP 請求標頭。三者可能相同，也可能依伺服器部署需求設定為不同值。出現憑證名稱不匹配時，應核對伺服器憑證涵蓋的網域與 SNI，而不是直接啟用 skip-cert-verify。

skip-cert-verify: true 會跳過憑證有效性驗證，只適合明確掌握伺服器憑證狀況的臨時測試。長期設定應維持 false，並修正系統時間、憑證鏈、SNI 或伺服器部署。系統時間錯誤會讓尚未生效或已經過期的判斷全部異常，這類錯誤在日誌中通常表現為 TLS 驗證失敗，與規則或策略組無關。

傳輸層選項必須依層級巢狀設定

WebSocket 參數放在 ws-opts，gRPC 參數放在 grpc-opts，HTTP 參數放在對應的傳輸選項中。它們不能與 server 同層後任意改名。YAML 縮排錯誤可能讓 headers 離開 ws-opts，設定看起來仍像可讀文字，但核心會忽略位於未知位置的欄位，或直接拒絕載入。排錯時應依照協定文件逐層確認，而不是只比較欄位值。

  - name: "VLESS-gRPC-範例"
    type: vless
    server: 192.0.2.40
    port: 443
    uuid: "00000000-0000-4000-8000-000000000001"
    network: grpc
    tls: true
    servername: grpc.example.com
    udp: true
    grpc-opts:
      grpc-service-name: example-service

udp 表示節點是否允許承載 UDP。啟用此欄位還要求協定、伺服器與網路路徑都支援 UDP。某個遊戲或語音應用程式無法運作時，不能只看節點設定中是否寫了 udp: true，還要確認 TUN 接管、策略組選擇、伺服器轉發與應用程式本身的協定。UDP 故障與 TCP 網頁存取正常可以同時存在。

協定欄位差異與選擇原則

節點欄位應來自實際伺服器端或訂閱，不應靠猜測補齊。用戶端之間的相容性差異，通常發生在新增協定特性、傳輸參數命名或核心能力上。遇到「不支援的代理類型」或「未知欄位」時，先確認目前用戶端使用的核心類型，再檢查訂閱是否為該用戶端產生合適格式。需要更換用戶端時，下載頁提供 Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、ClashX Meta、Surfboard 等對應平台入口。

靜態節點適合少量手動設定；節點數量較多或需要遠端更新時，應使用 proxy-providers。兩者可以同時存在，策略組也可以同時引用靜態節點與提供器。無論採用哪種來源，最終進入策略組的名稱都必須能被核心解析，遠端檔案下載成功也必須具備合法的節點結構。

策略組類型、巢狀與健康檢查

策略組是規則與節點之間的控制層

proxy-groups 將多個節點、其他策略組與內建動作組織成可引用的目標。規則通常不直接指向某個具體節點，而是指向「節點選擇」、「自動選擇」、「串流媒體」等策略組。如此一來，節點變更時只需調整組內成員，不必修改大量規則。策略組名稱同樣區分大小寫，而且不能與預期引用名稱多出空格。

select 是手動選擇組，使用者可在用戶端介面指定成員；url-test 會定期測試成員並選擇測得表現較佳的節點；fallback 會依序尋找可用成員；load-balance 則依指定策略在多個成員間分配連線。不同類型解決的問題不同。需要穩定固定出口時使用手動組，不應依賴自動組頻繁切換；希望故障時依優先順序退回備用節點時，fallback 比單純選擇最低延遲更符合需求。

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "自動選擇"
      - "故障轉移"
      - "SS-範例"
      - "Trojan-範例"
      - DIRECT

  - name: "自動選擇"
    type: url-test
    proxies:
      - "SS-範例"
      - "Trojan-範例"
      - "VMess-範例"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: "故障轉移"
    type: fallback
    proxies:
      - "Trojan-範例"
      - "SS-範例"
    url: https://www.gstatic.com/generate_204
    interval: 300
    lazy: true

url 是健康檢查目標，應選擇穩定、回傳內容小且所有候選節點都能存取的位址。測試成功只能表示節點能存取該目標，不能保證所有網站都可用。interval 是測試間隔，過短會產生不必要的連線，過長則可能在節點失效後遲遲不更新。啟用 lazy 後，策略組未被實際使用時可減少主動測試。tolerance 用於避免多個結果接近時頻繁切換，不應理解為固定的速度差。

組巢狀需要維持單向引用

策略組可以引用另一個策略組，例如「節點選擇」包含「自動選擇」，「串流媒體」再包含「節點選擇」。這種巢狀適合建立預設策略與用途策略，但不能形成迴圈。若 A 包含 B，而 B 又包含 A，核心無法得到最終出口。設計組關係時，可以畫成從業務組到基礎組再到節點的單向樹，任何路徑最終都應到達具體節點、DIRECT 或 REJECT。

巢狀層數過多也會增加排錯成本。請求命中「串流媒體」後，可能由它進入「地區選擇」，再進入「自動選擇」，最後才到節點。介面只看到最外層選擇時，容易誤判實際出口。建議基礎設定維持在三層以內：規則目標組、選擇或測試組、具體節點。需要為不同服務固定地區時，可在業務組中直接引用地區組，不必複製節點清單。

filter 與 use 管理提供器節點

策略組透過 use 引用 proxy-providers，再透過 filter 依節點名稱篩選成員。過濾運算式通常按正規表示式處理，字元需要正確跳脫。節點名稱由訂閱提供方決定，可能隨更新改變，因此過濾詞應涵蓋穩定的地區標記，同時避免匹配範圍過寬。例如只寫「美」可能同時匹配公告文字，寫清楚常見地區代碼與中文名稱會更穩妥。

proxy-groups:
  - name: "美國節點"
    type: url-test
    use:
      - remote-nodes
    filter: "(?i)美國|US|United States"
    exclude-filter: "測試|過期|到期"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: "業務分流"
    type: select
    proxies:
      - "美國節點"
      - "節點選擇"
      - DIRECT

當過濾結果為空時，策略組可能無法使用。訂閱更新後突然出現組內沒有節點，應先查看提供器是否更新成功，再檢查節點命名是否改變，最後檢查正規表示式是否受 YAML 引號與反斜線影響。雙引號字串會處理跳脫字元，複雜正規表示式可考慮使用單引號，減少反斜線層級。

DIRECT、REJECT 與 PASS 的含義

DIRECT 表示直接連線到目標，不經過代理節點；REJECT 表示拒絕連線；PASS 常用於特定規則組合或子規則集，讓匹配繼續交由後續流程處理。它們是內建動作，不需要在 proxies 中宣告。將 DIRECT 放入手動策略組，表示允許使用者暫時切換為直連；將 REJECT 用於廣告或惡意網域規則時，應考慮誤攔截對頁面資源造成的影響。

策略組是否加入 DIRECT 取決於業務邊界。預設代理組加入它有助於診斷，但也可能被誤選後讓敏感流量直連；固定用途組若明確要求代理，可以不提供直連成員。設定設計應讓組名反映行為，例如「節點選擇」表示允許手動調整，「自動選擇」表示由測試決定，「中國大陸直連」表示規則目標，而不是節點地區。

自動策略組不是「節點越多越好」。候選成員過多會增加測試流量，品質差異過大時也會讓結果不穩定。先按地區、用途與協定篩選，再在有限候選中測試，通常更容易得到穩定行為。需要多台裝置保持相同策略結構時，可參考多裝置設定同步方案，將訂閱、覆寫與裝置專屬設定分層儲存。

規則語法、優先順序與兜底順序

規則依宣告順序首次命中

rules 是有順序的清單。核心會由上到下檢查，某條規則命中後通常不再繼續比對後面的普通規則。因此具體規則應放在前面，寬泛規則放在後面，最後以 MATCH 兜底。規則不存在「網域規則天然優先於 IP 規則」的全域機制，實際優先順序由檔案順序決定。把 MATCH 放在中間，會讓它後面的規則全部失去機會。

常見格式是「規則類型、匹配內容、策略目標」，部分規則還有附加參數。逗號是欄位分隔符，匹配內容若需要表達複雜值，應使用對應規則類型或規則提供器，不要任意增加逗號。策略目標必須是已存在的策略組、節點或內建動作。規則本身不會建立策略組。

rules:
  - DOMAIN,api.example.com,節點選擇
  - DOMAIN-SUFFIX,example.com,節點選擇
  - DOMAIN-KEYWORD,example,節點選擇
  - GEOSITE,cn,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

DOMAIN 只匹配完整網域；DOMAIN-SUFFIX 匹配指定網域及其子網域；DOMAIN-KEYWORD 只要網域中包含關鍵字就可能命中，範圍最寬，也最容易誤匹配。能用完整網域時不要使用關鍵字，能用後綴時也應確認是否需要涵蓋根網域。例如 DOMAIN-SUFFIX,example.com 會涵蓋 example.com 與 www.example.com，更適合整個網站採用同一策略的情境。

IP 規則與 no-resolve

IP-CIDR 用於 IPv4 位址範圍，IP-CIDR6 用於 IPv6 位址範圍。請求已有目標 IP 時可以直接匹配；請求仍以網域表示時，核心可能需要先解析才能判斷是否落入位址範圍。附加 no-resolve 表示不要為了該規則主動觸發解析，常用於私有位址和已明確是 IP 的連線，以減少不必要的查詢。

GEOIP 根據位址資料庫判斷地區，結果取決於本機資料庫內容與更新狀態。它適合大範圍兜底，不適合要求精確的單一服務。雲端服務與內容傳遞網路的位址會變動，同一網域也可能依網路回傳不同地區的位址，因此服務級規則優先使用網域或維護明確的規則集。啟用 IPv6 後，還要確認規則是否同時涵蓋對應的位址族。

程序、連接埠與網路類型規則

桌面平台可能支援 PROCESS-NAME、PROCESS-PATH 等程序規則，但可用性取決於系統權限、核心執行方式與平台能力。程序名稱規則適合將某個應用程式固定到策略組，路徑規則更精確，卻容易因安裝目錄變更而失效。行動平台通常無法依桌面方式讀取程序路徑，因此跨平台設定不應完全依賴程序規則。

DST-PORT、SRC-PORT 等連接埠規則可以處理特定協定或本機服務，但連接埠不等於應用程式身分。大量現代服務共用 443 連接埠，使用 DST-PORT,443 做寬泛代理會涵蓋幾乎所有 HTTPS 流量。連接埠規則更適合已知服務連接埠、區域網路管理連接埠或除錯情境，並應放在不會遮蔽更具體規則的位置。

rules:
  - PROCESS-NAME,example-client.exe,業務分流
  - DST-PORT,22,DIRECT
  - NETWORK,udp,節點選擇
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - MATCH,節點選擇

NETWORK,udp 會匹配廣泛的 UDP 流量，是否適合取決於節點是否支援 UDP、DNS 是否由獨立模組處理以及應用程式用途。把所有 UDP 強制交給不支援 UDP 的策略，會造成語音、遊戲或 QUIC 連線失敗。若只是希望特定應用程式走代理，應優先使用網域、程序或連接埠組合，而不是一條涵蓋所有 UDP 的規則。

規則設計應先寫意圖，再寫語法

維護規則前，可以先將需求整理成幾層：私有網路直連；明確需要拒絕的網域；必須使用特定地區的業務；常用本地區域直連；其餘流量進入預設策略。再將每一層轉換成規則，依「例外在前、一般在後」排列。這比直接拼接多個網路設定片段更容易發現衝突。

例如某個網域整體應直連，但其中一個 API 子網域必須代理，應先寫完整 API 網域規則，再寫整個網域後綴直連。若順序相反，後綴規則會先命中，例外規則永遠不會執行。排錯時應在連線日誌中查看實際命中的規則類型與目標策略，而不是只搜尋檔案中是否存在某條規則。

rules:
  - DOMAIN,api.example.com,節點選擇
  - DOMAIN-SUFFIX,example.com,DIRECT
  - GEOSITE,private,DIRECT
  - GEOIP,LAN,DIRECT,no-resolve
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

規則數量增加後，重複與衝突很難只靠肉眼發現。可以將穩定的公共規則移入 rule-providers，本地 rules 只保留少量高優先級例外與最終兜底。遠端規則集也應檢查行為類型與策略目標，不能因為檔案來源可信就忽略其涵蓋範圍。規則更新後若出現網站走錯路徑，應比較更新前後的命中結果，而不是立即更換節點。

代理提供器與規則提供器

proxy-providers 管理遠端節點集合

proxy-providers 將節點清單從主設定中拆出。每個提供器通常包含類型、下載網址、本機快取路徑、更新間隔與健康檢查。策略組透過 use 引用提供器，而不是把每個節點名稱逐一寫入 proxies。這種結構適合訂閱更新，也方便為多個來源分別設定篩選與檢查。

type: http 表示從遠端位址取得，path 是下載後的本機快取位置，interval 控制更新間隔。遠端檔案應是核心支援的代理提供器格式，不能直接把完整 Clash 設定當成純節點集合。若訂閱回傳完整設定，需要由用戶端訂閱管理層匯入，或透過可信的轉換流程產生 provider 檔案。

proxy-providers:
  remote-nodes:
    type: http
    url: "https://subscription.example/nodes.yaml?token=xxxx"
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      lazy: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "提供器選擇"
    type: select
    use:
      - remote-nodes
    proxies:
      - DIRECT

範例訂閱網址使用明顯的虛構值。真實訂閱通常包含存取認證，不應寫入公開儲存庫、截圖或共用文件。提供器下載失敗時，核心可能繼續使用本機快取，因此介面仍能顯示舊節點。排錯時要同時查看「這次更新是否成功」與「快取是否仍可讀取」，不能只因節點清單存在就判斷訂閱正常。

path 應位於用戶端允許寫入的設定目錄。使用絕對路徑會降低跨平台可攜性，Windows、macOS、Linux 與 Android 的目錄結構也不同。優先使用用戶端工作目錄下的相對路徑，並確保不同提供器使用不同檔名。多個提供器寫入同一路徑會互相覆蓋，表現為重新整理一個來源後，另一個來源的節點突然改變。

健康檢查屬於提供器層級的可用性觀察

提供器的 health-check 會檢查節點是否能存取測試位址。它與策略組的 url-test 有關聯但目的不同：前者為提供器節點維護可用狀態，後者在組內成員之間進行選擇。兩處都設定過短的間隔會重複產生大量測試請求。一般設定可以讓提供器以較長週期檢查，再由需要自動選擇的策略組依合理週期測試。

測試位址應穩定且回應輕量。某個節點無法存取測試位址，可能是節點故障，也可能是該目標受到出口網路限制。若所有節點同時失敗，先測試 DNS 與測試位址本身；若只有個別協定失敗，再查看握手日誌。健康檢查不是頻寬測試，也不會驗證影片、登入或特定地區內容是否可用。

rule-providers 拆分大型規則集

rule-providers 用於載入遠端或本機規則集合。常見的 behavior 包括 domain、ipcidr 與 classical。domain 集合面向網域項目，ipcidr 面向位址範圍，classical 可以容納帶有類型的傳統規則。行為類型必須與檔案內容一致，否則會出現解析失敗或規則不生效。

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example/private-domain.yaml"
    path: ./rules/private-domain.yaml
    interval: 86400

  service-rules:
    type: http
    behavior: classical
    format: yaml
    url: "https://rules.example/service-rules.yaml"
    path: ./rules/service-rules.yaml
    interval: 86400

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-rules,業務分流
  - MATCH,節點選擇

規則提供器只提供匹配集合，使用時仍需在主設定的 rules 中透過 RULE-SET 指定策略目標。同一規則集可以在不同設定中對應到不同策略組。遠端檔案更新後，匹配範圍可能改變，因此應記錄來源用途，並避免將未知的大型集合直接放在最高優先級。

format 需要與遠端內容一致。YAML 規則檔通常以 payload 清單組織；二進位格式則依賴核心支援與對應擴充功能。只修改檔案副檔名不會轉換內容。下載的檔案若實際上是 HTML 錯誤頁，解析器通常會在開頭報錯。遇到提供器更新失敗時，應先查看 HTTP 狀態與回應內容，再檢查行為類型、格式與本機路徑權限。

提供器與主設定的更新邊界

主設定控制連接埠、DNS、策略組結構與最終規則順序；提供器負責可變的節點集合或規則集合。將穩定結構放在主設定，將頻繁變動的資料放在提供器，能降低訂閱更新覆蓋本機設定的機率。若所有內容都由遠端訂閱產生，本機個人化設定應透過覆寫層加入，而不是每次更新後直接修改快取檔案。

多個節點來源可以分別建立提供器，再由策略組組合。需要注意節點同名問題：不同來源可能包含相同顯示名稱，組內篩選與日誌識別會變得困難。可以在訂閱轉換或覆寫階段為來源加上前綴，而不是在規則中依賴同名節點。規則提供器也應避免職責重疊，例如兩個大範圍網域集分別指向不同策略時，實際行為仍由它們在 rules 中的先後順序決定。

覆寫、合併、驗證與故障定位

覆寫層應修改穩定結構，不要直接修改訂閱快取

訂閱更新通常會重新下載並替換快取檔案，直接編輯訂閱內容很容易在下次更新時遺失。較穩妥的做法是保留遠端訂閱作為資料來源，再使用用戶端提供的全域覆寫、擴充腳本或本機合併檔案來修改連接埠、DNS、策略組與規則。不同用戶端支援的覆寫格式不同，Clash Plus、Clash Verge Rev、FlClash 等介面中的名稱與執行順序也可能不同，應先確認覆寫是在訂閱解析前還是後發生。

覆寫可以分為「替換純量」、「合併映射」、「追加清單」、「前置清單」與「刪除欄位」。純量如 mode 通常直接替換；dns 作為映射可以只修改其中幾個子欄位；rules 是有順序的清單，簡單追加到末尾可能落在 MATCH 之後而失效，因此本機高優先級規則應插入清單前段。策略組清單若依名稱合併，需要確認用戶端是否支援依物件鍵識別，否則可能產生兩個同名策略組。

# base.yaml
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
rules:
  - GEOSITE,cn,DIRECT
  - MATCH,節點選擇

# override.yaml 的目標語意
dns:
  ipv6: false
  fake-ip-filter:
    - "*.lan"
    - "*.local"

# 需要前置到 MATCH 之前的本機規則
rules-prepend:
  - DOMAIN,api.example.com,業務分流
  - DOMAIN-SUFFIX,internal.example,DIRECT

rules-prepend 是覆寫工具可能採用的語意範例，並非所有核心都能直接識別的頂層欄位。最終交給 mihomo 的檔案仍應展開為標準 rules 清單。使用某個用戶端的擴充欄位時，應將它留在用戶端覆寫檔案中，不要複製到準備直接交給核心的設定裡。要判斷某欄位屬於用戶端還是核心，可以查看匯出的最終設定與啟動日誌。

合併清單時必須明確順序與去重方式

合併規則清單最重要的是順序。建議將本機強制規則放在遠端規則之前，把補充規則放在地區規則之前，並將最終兜底保留在唯一的末尾。合併後應檢查是否存在多個 MATCH、是否把私有網路規則放到代理兜底之後，以及是否有同一網域被更早的寬泛規則覆蓋。規則文字重複不一定會造成啟動錯誤，但會增加匹配與維護成本。

策略組與節點清單的去重不能只比較整行文字。節點物件可能名稱相同但伺服器不同，也可能伺服器相同而名稱不同。一般手動維護應以唯一名稱為第一項約束，再核對協定、伺服器與連接埠。策略組同名通常比節點同名更危險，因為規則只按組名引用，重複定義的處理方式可能隨解析器或用戶端而異。

合併 DNS 映射時，特別要注意清單欄位是替換還是追加。若覆寫器完全替換 nameserver，基礎設定中的備用上游會消失；若追加 fake-ip-filter，通常符合補充過濾的意圖。不能只看覆寫片段本身，必須檢查合併後的最終 YAML。圖形化用戶端若提供「查看執行設定」或「匯出目前設定」，應以該結果作為驗證對象。

設定驗證應分四個層級進行

第一層是 YAML 語法：縮排、冒號、引號、清單與資料型別必須正確。第二層是欄位驗證：核心是否識別欄位，協定必要參數是否齊全。第三層是引用關係：規則目標、策略組成員、提供器名稱與本機路徑是否存在。第四層是執行行為：連接埠能否監聽、DNS 能否存取上游、節點能否完成握手、規則是否命中預期策略。四層應依序檢查，前一層未通過時，後續網路測試沒有意義。

# 使用用戶端內建驗證功能時，以實際核心路徑與設定路徑為準
mihomo -t -f config.yaml

# 若設定通過，輸出通常會表示設定測試完成
# 若失敗，重點記錄報錯行號、欄位名稱與引用名稱

命令列中的可執行檔名稱與參數取決於實際安裝方式，圖形化用戶端通常已提供設定檢查入口。測試時應使用與用戶端一致的 mihomo 核心，避免一個核心接受欄位、另一個核心卻不支援。報錯行號指向解析器發現問題的位置，不一定是根因位置，例如上一行缺少引號，錯誤可能到下一行才暴露。

修改設定後，不要一次重寫多個章節。建議採用二分法定位：先恢復到可執行版本，再逐塊加入 DNS、節點、策略組與規則；某個區塊觸發錯誤後，再繼續縮小到具體欄位。遠端提供器可暫時替換成一兩個靜態範例節點，以判斷問題位於下載鏈路還是策略結構。排錯結束後再恢復完整來源。

常見錯誤的定位路徑

若設定能啟動但無法上網，應先確認不經過 Clash 時基礎網路是否正常，再驗證本機入站連接埠，接著檢查 DNS、策略組、節點握手與規則命中。不要一開始就刪除所有規則或關閉全部安全設定，這會破壞故障現場。日誌中保留首次失敗的時間點，並對照當時選擇的模式與策略組，通常比反覆重新啟動更有效。

如果只有瀏覽器異常，檢查瀏覽器是否啟用了獨立安全 DNS、代理擴充功能或 QUIC；如果所有應用程式都異常，檢查系統代理或 TUN；如果區域網路裝置異常而本機正常，檢查監聽範圍與防火牆；如果某個策略組異常而其他組正常，檢查組內成員與健康檢查。不同範圍對應不同設定層級，先界定範圍可以避免無關修改。

建立可維護設定的最終檢查表

完成設定後，確認頂層欄位只有一份有效定義；連接埠彼此不衝突；DNS 上游存在基礎解析路徑；每個節點名稱唯一；策略組引用形成單向關係；所有規則目標都存在；MATCH 只在末尾出現一次；提供器快取路徑互不覆蓋；本機覆寫不包含訂閱認證資料的公開副本；最終執行設定可以通過目前核心驗證。接著分別測試直連網域、代理網域、IP 目標與 UDP 應用程式，確認不是只在單一網頁上偶然成功。

設定檔應與訂閱來源、覆寫檔案及執行狀態分開備份。需要跨裝置重複使用時，先移除平台專屬路徑與控制連接埠，再為每台裝置保留獨立的系統接管設定。遠端訂閱負責節點變化，本機覆寫負責穩定偏好，用戶端執行目錄負責快取與選擇狀態。釐清三者後，訂閱更新、用戶端升級與裝置遷移就不會互相覆蓋。

遇到無法歸類的問題，可前往幫助中心，依基礎認知、安裝設定、使用技巧與故障排查繼續查找。若需要從安裝到首次連線重新建立可工作的基線，返回入門指南逐步執行；若需要重新選擇用戶端或核心安裝套件，前往安裝套件頁面按平台查看。排錯時始終先儲存目前設定，再進行可回復的小範圍修改。