Clash 設定檔完整參考

一、YAML 結構與設定讀取順序

Clash 設定檔本質上是一棵由鍵、值、清單與映射組成的資料樹。頂層通常包含連接埠、執行模式、日誌層級、DNS、代理節點、策略群組與規則等部分。核心啟動時會先解析 YAML 語法，再驗證欄位型別，接著初始化監聽連接埠、DNS 模組與出站代理，最後載入規則。只要前面的語法解析失敗，後面的節點與規則就不會進入執行狀態，因此排錯時應先確認檔案能完整解析，再討論某條規則是否命中。

YAML 依靠縮排表達層級，建議統一使用兩個空格，不要混用定位字元。冒號後通常要留一個空格；清單項目以連字號開頭；包含冒號、井字號、大括號或特殊空格的文字適合放在引號內。未置於引號中的井字號代表註解，後面的內容不會參與解析。布林值應使用 true 或 false，連接埠等數字不要誤寫成帶引號的文字。不同客戶端可能在儲存時重新排列欄位，但只要層級與型別不變，順序通常不會影響頂層欄位的意義。

如何擴充最小結構

一份便於理解的設定可以從監聽連接埠、模式、節點、策略群組與規則五個部分開始。以下範例只展示結構關係：節點先在 proxies 中定義，策略群組再引用節點名稱，規則最後把流量交給策略群組。引用名稱必須完全一致，包括大小寫、空格與符號。若規則指向不存在的策略群組，核心通常會在驗證階段回報找不到目標。

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

proxies:
  - name: "example-node"
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: "手動選擇"
    type: select
    proxies:
      - example-node
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,手動選擇
  - MATCH,DIRECT

範例中的位址僅供文件說明，實際連線需要使用訂閱提供的伺服器資訊。手動編寫節點時，先確認協定類型與必要欄位，再加入協定專用參數。訂閱產生的設定通常更長，因為還會包含 DNS、嗅探、規則集與多個策略群組；閱讀時不必從第一行一路看到最後一行，可以先找出頂層鍵，再沿著「規則目標 → 策略群組 → 節點」的引用鏈向前追蹤。

錨點、別名與重複鍵

YAML 支援錨點與別名，可用來重複使用一組參數，但並非所有客戶端的圖形化編輯器都能完整保留這類寫法。設定經過訂閱轉換、圖形介面儲存或遠端覆寫後，錨點可能會展開成一般欄位。如果設定需要頻繁在不同客戶端間遷移，直接明確寫出欄位通常更穩妥。另一個常見問題是重複鍵：同一個映射層級出現兩個 mode 或兩個 dns 時，解析器可能採用後者，也可能直接拒絕。不要依賴覆蓋行為，應在合併前消除重複的頂層鍵。

檔案編碼建議使用 UTF-8。策略群組與節點名稱可以使用中文，但由外部腳本處理設定時，英文短名稱更方便比對。換行格式一般不影響解析，不過從網頁或聊天工具複製設定時，容易混入全形冒號、彎引號與不可見空格。看到「此處不允許映射值」一類錯誤時，優先回到錯誤所在行及上一行檢查縮排、冒號與引號是否閉合，而不是立即刪除整段設定。

二、通用欄位、監聽連接埠與執行模式

通用欄位決定核心如何接收本機或區域網路流量，以及如何輸出執行資訊。最常見的入口是 mixed-port，它在同一個連接埠接受 HTTP 與 SOCKS 代理請求，方便瀏覽器、終端機與系統代理共同使用。也可以分別設定 port 與 socks-port，但這會增加連接埠管理成本。客戶端介面中顯示的「系統代理連接埠」通常就來自這些欄位，修改檔案後還要確認圖形客戶端沒有以自身設定再次覆蓋。

allow-lan 控制其他裝置能否透過目前裝置的代理連接埠接入。設為 false 時適合單機使用；設為 true 後，還應搭配 bind-address 限定監聽範圍，並檢查作業系統防火牆。允許區域網路連線不等於自動完成身分驗證，也不代表路由器會把流量轉送到該連接埠。若只是手機與電腦各自執行客戶端，沒有必要開啟區域網路監聽。

規則、全域與直連模式

rule 是日常使用最常見的模式。核心會由上到下比對 rules，命中後便將連線交給對應的策略群組或出站。global 會略過逐條規則判斷，把流量統一交給全域策略；適合暫時確認某個節點是否可用，但不適合作為判斷規則是否正確的依據。direct 則讓流量直接連線，可用來快速區分問題來自代理鏈路還是本地網路。切換模式只會改變路由決策，不會自動修復 DNS、憑證、權限或系統代理未開啟等問題。

圖形客戶端中的「規則、全域、直連」按鈕通常會透過控制介面改變執行狀態，不一定會改寫原始 YAML。重新啟動後採用哪個模式，取決於客戶端是否保存執行狀態，以及設定中的 mode。排查「重新啟動後模式被還原」時，應同時檢查設定檔、客戶端設定與訂閱更新行為。訂閱每次更新都可能替換原始檔案，直接在訂閱檔案中修改通用欄位，往往會在下次更新時遺失，較適合使用客戶端提供的覆寫功能。

系統代理與 TUN 的界線

監聽連接埠只代表核心已準備好接受代理請求，不會自動讓所有應用程式把流量送進來。系統代理是作業系統公布的一組代理位址，只有讀取這項設定的應用程式才會使用；TUN 模式則透過虛擬網路介面接管更廣泛的 IP 流量。兩者可以使用同一份規則與策略群組，但流量入口不同。有關接管層級、相容性與排錯差異，可閱讀TUN 模式與系統代理的運作機制比較。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090

上例把控制介面限制在迴路位址，適合本機圖形客戶端呼叫。即使 allow-lan 為 false，也建議明確理解每個監聽位址的用途。發生連接埠衝突時，先關閉重複執行的客戶端或調整連接埠，再確認系統代理仍指向新的連接埠。只修改 YAML 卻不更新系統代理，會出現核心執行正常、瀏覽器卻無法連線的情況。

三、DNS 設定與網域解析路徑

DNS 是 Clash 設定中最容易被誤判的部分。存取網域時，應用程式可能先自行解析，也可能把網域交給代理協定；系統 DNS、瀏覽器安全 DNS、Clash DNS 模組與遠端代理都可能參與。設定中的 dns.enable 只控制核心 DNS 模組是否啟用，不能保證所有應用程式都把查詢送給它。使用系統代理時，部分應用程式仍會採用自身的解析路徑；使用 TUN 時通常更容易統一接管，但仍取決於 DNS 劫持與系統權限。

nameserver 是主要解析伺服器清單，default-nameserver 用於解析 DNS 伺服器本身的網域，避免出現「先解析解析器位址」的循環相依。若 nameserver 直接填入 IP，依賴較少；若填入加密 DNS 的網域，就應為 default-nameserver 提供可直接存取的基礎解析位址。fallback 與相關篩選欄位適合更複雜的解析分流，不應在不了解來源時機械式疊加，多條解析路徑反而會讓結果難以預測。

redir-host 與 fake-ip

enhanced-mode 常見值為 redir-host 與 fake-ip。redir-host 保留真實解析結果，較容易理解，但在透明代理情境中，核心可能較難從純 IP 流量還原網域。fake-ip 會為網域回傳保留位址池中的暫時位址，核心據此建立網域與連線的對應，再依網域規則處理。它不是將目標真正連線至該暫時位址，而是利用對應關係完成路由。fake-ip 通常更有利於規則比對與透明接管，但少數區域網路服務、裝置探索、遊戲平台或依賴真實 IP 的應用程式需要加入篩選清單。

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"
    - "+.stun.*.*.*"

範例展示欄位關係，不代表所有網路環境都應使用相同的解析服務。公司、校園或家庭網路可能依賴本地 DNS 解析內部網域，此時應保留區域網路解析路徑，或為內部網域設定專用的 nameserver-policy。fake-ip-range 應使用約定的保留位址範圍，不要與家庭區域網路、VPN 或容器網路正在使用的網段重疊。若出現區域網路裝置無法開啟、印表機探索異常或遊戲登入失敗，可先確認該網域是否應加入 fake-ip-filter，而不是直接關閉整個 DNS 模組。

依網域選擇解析器

nameserver-policy 可以讓特定網域使用指定解析器。例如將內部網域交給路由器、本地域名交給區域網路 DNS，其餘網域使用主要 nameserver。它解決的是「由誰解析」，規則中的 DOMAIN-SUFFIX 則解決「連線從哪裡出去」，兩者屬於不同階段。解析器選擇正確，不代表後續連線一定會套用對應策略；反過來，代理規則正確，也無法修復已回傳錯誤位址的 DNS 結果。

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
    "+.internal.example":
      - 192.168.1.1

排查 DNS 時可以分三層觀察：先確認系統或應用程式將查詢送往何處，再看 Clash 日誌中是否出現網域與規則比對，最後檢查目標連線使用了哪個策略。若瀏覽器啟用了獨立的安全 DNS，可能會繞過系統設定；若規則只寫 IP-CIDR，而連線日誌中保留的是網域，命中順序也可能與預期不同。不要同時修改 DNS 模式、規則與節點，逐項變更更容易找出真正原因。

IPv6 與解析結果

dns.ipv6 控制 DNS 模組是否回傳 AAAA 結果，頂層 ipv6 則影響核心對 IPv6 的整體處理。裝置網路支援 IPv6、解析器回傳 IPv6 位址，且代理節點也具備相應能力時，連線才可能順利完成。若本地只有不穩定的 IPv6 路徑，應用程式可能優先嘗試 AAAA 位址並等待逾時，看起來就像代理速度變慢。應在確認網路條件後決定是否啟用，而不是把開關當成固定答案。

四、代理節點欄位與協定參數

proxies 是靜態節點清單，每個項目至少包含名稱、協定類型、伺服器位址與連接埠，其他欄位則由協定決定。訂閱通常已產生完整節點，手動維護時不要只憑名稱猜測協定參數。同一台伺服器可能開放多個協定入口，它們的驗證方式、傳輸層與 TLS 設定並不相通。核心驗證通過只代表欄位格式可接受，不代表遠端服務一定可連線。

name 是設定檔內部的引用鍵，也是客戶端代理頁面顯示的文字。策略群組引用節點時必須使用該名稱。名稱重複會造成選擇與覆寫困難，應在匯入階段保持唯一。server 可以是網域或 IP；使用網域時會涉及 DNS 解析。port 必須是整數。像是 udp、skip-cert-verify、servername 等欄位，只在協定與傳輸條件需要時使用，不應將某個節點的參數整段複製到不同協定。

SOCKS 與 HTTP 上游代理

SOCKS5 與 HTTP 節點常用於連線至既有的上游代理。它們的欄位相對簡單，可以作為理解節點結構的起點。若上游要求驗證，填寫使用者名稱與密碼；不要求時則省略。是否支援 UDP 取決於協定、核心與上游服務三方的能力。文件範例中的位址僅用於說明格式。

proxies:
  - name: "office-socks"
    type: socks5
    server: 192.0.2.20
    port: 1080
    username: "example-user"
    password: "your-password"
    udp: false

  - name: "upstream-http"
    type: http
    server: 192.0.2.30
    port: 8080
    username: "example-user"
    password: "your-password"
    tls: false

密碼等敏感欄位不適合放進公開儲存庫或截圖。設定需要在多台裝置間同步時，應使用受控的私人管道，並確認客戶端日誌不會輸出完整驗證資訊。節點無法連線時，先驗證伺服器與連接埠的網路可達性，再檢查驗證與傳輸參數；如果一開始就修改策略群組或規則，會把節點問題與路由問題混在一起。

TLS、SNI 與憑證驗證

使用 TLS 的協定通常需要正確的伺服器名稱。servername 或同類型的 SNI 欄位會告知遠端在握手時使用哪個主機名稱，這個名稱可能與 server 不同。透過 IP 連線但憑證簽發給網域時，缺少正確的 SNI 會導致握手失敗。skip-cert-verify 會略過憑證驗證，不應作為處理所有 TLS 錯誤的通用開關；更合適的做法是核對系統時間、伺服器名稱、憑證鏈與中間網路。訂閱提供者明確給出此欄位時，再結合實際環境判斷。

WebSocket、gRPC 等傳輸層還會包含路徑、主機標頭或服務名稱。YAML 層級必須放在協定要求的位置，例如 ws-opts 下的 path 與 headers。欄位放錯層級時，有些解析器會忽略未知鍵，結果是設定可以載入，但握手參數缺失。遇到這種情況，應對照核心日誌與協定欄位說明，不要只看客戶端是否顯示該節點名稱。

proxies:
  - name: "example-tls-node"
    type: trojan
    server: edge.example.net
    port: 443
    password: "your-password"
    sni: edge.example.net
    udp: true
    skip-cert-verify: false
    network: ws
    ws-opts:
      path: /gateway
      headers:
        Host: edge.example.net

節點提供器與靜態節點的差異

靜態 proxies 會將節點直接寫入主設定，方便單一檔案閱讀；proxy-providers 則從本機檔案或遠端資源載入節點集合，適合訂閱更新與多來源組合。策略群組引用 provider 時使用 use，引用靜態節點時使用 proxies。兩者可以同時存在，但要留意重複節點名稱、更新間隔與快取檔案路徑。客戶端內建的訂閱管理通常已處理這些細節，一般使用者不必為了「看起來簡潔」而主動改成 provider。

在 Windows、macOS、Android、iOS 與 Linux 圖形客戶端中，節點參數通常由訂閱維護。首推的 Clash Plus，以及 Clash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、ClashX Meta 等客戶端，設定顯示方式可能不同，但底層引用關係相近。需要比較平台與客戶端定位，可前往橫向評測，不要根據介面名稱推斷某個協定欄位一定受到支援。

五、策略群組類型與組合設計

策略群組位於規則與節點之間。規則不必直接寫入某個節點名稱，而是將流量交給「手動選擇」、「自動選擇」或「應用程式分流」等策略群組，再由群組決定實際出站。這樣更新節點清單時不必重寫規則，也能在客戶端介面中快速切換。設計策略群組的關鍵不在數量，而在於讓每一層職責清楚：頂層負責使用者選擇，中間層負責自動測試或故障切換，底層才是節點與 DIRECT。

select 是最直觀的類型，依使用者選擇使用某個節點或子策略群組。它不會自動挑選速度較快的節點。url-test 會依設定的位址定期測試候選節點，並選擇測試結果較合適者；測試只反映連線至指定目標的表現，不等同於所有網站的實際體驗。fallback 著重可用性，在目前候選不可用時切換至下一項。load-balance 會依策略將連線分配給多個節點，可能影響登入工作階段、出口位址一致性與風控判斷，不適合作為預設群組任意啟用。

兩層策略群組的常見結構

一個實用結構是頂層「代理選擇」使用 select，群組內放入「自動選擇」、數個地區群組與 DIRECT；「自動選擇」再使用 url-test 引用具體節點。規則統一指向頂層群組，使用者需要穩定的手動控制時直接選擇節點，需要省心時則選擇自動群組。不要讓兩個策略群組互相引用，否則會形成循環。也不要讓每條規則都指向不同節點，這會讓訂閱更新後的維護成本迅速增加。

proxy-groups:
  - name: "代理選擇"
    type: select
    proxies:
      - 自動選擇
      - 手動節點
      - DIRECT

  - name: "自動選擇"
    type: url-test
    proxies:
      - node-a
      - node-b
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

  - name: "手動節點"
    type: select
    proxies:
      - node-a
      - node-b

interval 表示測試間隔，過短會增加請求量與裝置耗電，過長則無法及時反映網路變化。tolerance 用於減少結果接近時的頻繁切換。測試位址應穩定、回應內容小，並能代表希望驗證的連線路徑。客戶端介面顯示的測試結果只是一項參考，節點壅塞、目標網站線路與無線網路變化都會影響實際存取。

使用 filter 管理 provider 節點

當節點來自 proxy-providers 時，可以透過 use 引用整個 provider，並用 filter 依名稱篩選。篩選通常使用正規表示式，名稱中的地區寫法不一致時，表示式需要相容於簡稱、英文與符號。篩選結果為空會讓策略群組失去候選項，因此修改後必須驗證。與其撰寫過於寬泛的表示式，不如先觀察實際節點名稱，再逐步增加比對分支。

proxy-groups:
  - name: "地區選擇"
    type: select
    use:
      - primary-subscription
    filter: "(?i)Hong Kong|HK|香港"

  - name: "可用性優先"
    type: fallback
    use:
      - primary-subscription
    url: "https://www.gstatic.com/generate_204"
    interval: 600

策略群組名稱本身也是規則目標，因此重新命名屬於結構性變更。將「代理」改為「代理選擇」後，應同步搜尋 rules、rule-providers 的行為目標，以及其他策略群組中的引用。客戶端可能會記住上次選擇；當舊節點消失或群組內容改變時，執行狀態中的選擇可能回落至第一項。設定發布給多台裝置時，第一項應是可解釋且可用的預設策略，而不是剛好排在最前面的單一節點。

DIRECT 與 REJECT 的位置

DIRECT 表示直接連線，適合區域網路、受信任的本地服務，或明確希望使用本地出口的目標。REJECT 表示拒絕連線，可用於阻擋已確認的網域或位址。它們既可以直接作為規則目標，也能放入 select 群組供使用者暫時選擇。將 DIRECT 放入總策略群組會提高彈性，但也代表使用者可能讓原本應代理的規則暫時直連；是否保留取決於使用情境。

六、規則語法、比對順序與自訂規則

rules 是有順序的清單。連線到達後，核心通常會從第一條開始判斷，第一個符合的結果立即生效，後面的規則不再檢查。因此「規則內容正確但沒有作用」通常不是語法錯誤，而是前面已有更寬泛的規則先命中。精確網域、特定程序或區域網路位址通常放在前面，範圍較大的網域後綴、IP 網段與地區規則放在後面，最後用 MATCH 處理剩餘流量。

一條基礎規則由規則類型、比對內容與目標策略組成，以英文逗號分隔。例如 DOMAIN,api.example.com,代理選擇 只會比對完整網域；DOMAIN-SUFFIX,example.com,代理選擇 可涵蓋根網域及其子網域；DOMAIN-KEYWORD,example,代理選擇 範圍更廣，任何包含該關鍵字的網域都可能命中，應謹慎使用。規則目標可以是策略群組、節點、DIRECT 或 REJECT。

網域、IP 與程序規則

DOMAIN 類規則在核心掌握網域時最清楚。IP-CIDR 用於 IPv4 網段，IP-CIDR6 用於 IPv6 網段，網段以 CIDR 前綴表示。IP 規則可能觸發網域解析；若只希望使用既有目標 IP 而不額外解析，可依核心支援方式加入 no-resolve。GEOIP 依 IP 所屬地區比對，結果取決於對應資料庫。PROCESS-NAME 與 PROCESS-PATH 依賴作業系統提供的程序資訊，在不同平台、權限與 TUN 實作下可能有不同表現，不適合作為唯一的跨平台規則方案。

rules:
  - DOMAIN,api.example.com,代理選擇
  - DOMAIN-SUFFIX,example.org,代理選擇
  - DOMAIN-KEYWORD,streaming,媒體服務
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - PROCESS-NAME,example-app.exe,代理選擇
  - GEOIP,CN,DIRECT
  - MATCH,漏網之魚

上例只是展示順序與格式。區域網路網段應依實際網路調整；程序名稱也應以系統工作資訊為準。MATCH 應位於末尾，它會比對先前尚未處理的連線。如果 MATCH 放在中間，後面的規則永遠沒有執行機會。設定中出現多個 MATCH 沒有實際意義，應保留一個明確的最終出口。

如何插入自訂規則

訂閱設定更新時，直接追加到原始檔案的規則通常會被覆蓋。更穩妥的方法是使用客戶端的覆寫、擴充腳本或規則前置功能，將自訂規則插入訂閱規則之前。前置適合精確例外，例如讓某個內部網域始終直連；後置只適合在訂閱末尾的 MATCH 之前仍有機會執行的規則。如果訂閱已經以 MATCH 結尾，把新規則直接追加到檔案末端不會生效。

設計自訂規則時，先回答三個問題：比對對象是網域還是 IP；目標是既有策略群組還是新群組；它應涵蓋哪些現有規則。若只處理一台主機，優先使用 DOMAIN；處理某個網站的所有子網域，使用 DOMAIN-SUFFIX；只有名稱結構不穩定時才考慮 DOMAIN-KEYWORD。過於寬泛的關鍵字可能誤傷無關網域，尤其是短詞、品牌縮寫或常見單字。

rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - DOMAIN-SUFFIX,docs.example.net,代理選擇
  - RULE-SET,private-network,DIRECT
  - RULE-SET,service-list,代理選擇
  - MATCH,代理選擇

規則命中日誌的閱讀方式

日誌通常會顯示目標網域或 IP、命中的規則類型、選取的策略群組以及最終節點。排錯時先發起一次可重複的存取，再依時間定位對應連線。看到規則目標正確但最終節點不符，應檢查策略群組目前的選擇；看到 MATCH 命中，則向前檢查預期規則是否載入、網域是否一致、規則集是否更新成功；看到 IP 規則卻沒有網域資訊，則檢查 DNS 與嗅探路徑。

瀏覽器開啟頁面時會產生多個連線，包括主站、圖片、腳本與第三方介面，不能只看第一筆日誌就判斷整個頁面的路由。更適合選擇一個明確網域進行測試，或在開發者工具中確認失敗請求的主機名稱。應用程式也可能快取 DNS 或維持既有連線，修改規則後應建立新連線，必要時重新啟動應用程式，而不是假設所有舊工作階段會立即切換策略。

規則的可維護性

規則應依用途分段並加入簡短註解，例如區域網路、個人例外、業務分流、公共規則集與最終比對。註解說明「為什麼存在」比重複欄位含義更有價值。長期不使用的例外應及時刪除，否則日後很難判斷它是否仍有必要。規則目標盡量引用穩定的策略群組名稱，不要直接綁定經常變動的節點名稱。如此一來，訂閱新增或刪除節點時，路由層無需同步調整。

七、規則集、節點提供器與外部資源

當規則數量較多時，把所有內容塞進 rules 會讓主設定難以維護。rule-providers 允許從本機檔案或遠端位址載入規則集合，主規則只需使用 RULE-SET 引用。它解決的是規則內容的組織與更新問題，不會自動決定策略目標；同一個規則集可以在主設定中指向不同策略群組。相似地，proxy-providers 管理節點來源，策略群組透過 use 引用。

規則提供器常見的 behavior 包括 domain、ipcidr 與 classical。domain 適合純網域規則，ipcidr 適合位址網段，classical 可以容納較完整的規則表示式。behavior 必須與檔案內容相符；將 DOMAIN-SUFFIX 形式的 classical 規則當成純 domain 資料讀取，可能導致解析失敗或內容無法命中。format 則描述檔案格式，例如 yaml、text 或 mrs，實際支援範圍應以所使用的核心為準。

規則提供器的完整定義

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

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

rules:
  - RULE-SET,private-network,DIRECT
  - RULE-SET,service-list,代理選擇
  - MATCH,代理選擇

type: http 表示從遠端取得，path 是本機快取位置，interval 是更新間隔。首次載入需要網路存取；遠端更新失敗時，核心通常會嘗試繼續使用既有快取，但首次下載失敗且沒有快取時就無法取得規則內容。路徑所在目錄需要具備寫入權限，桌面客戶端還可能將相對路徑解讀為其設定工作目錄，而不是使用者目前開啟終端機的位置。

遠端位址應來自可信賴且持續維護的來源。規則更新會改變流量路徑，影響範圍可能比單一節點更大。使用第三方規則集前，應了解其分類邏輯、更新頻率與預設目標，不要只憑名稱判斷內容。對於公司內部網域或個人例外，保留少量本機前置規則通常比等待公共清單收錄更合適。

規則集檔案的內容格式

YAML payload 格式通常以 payload 為頂層鍵，下面是規則項目。classical behavior 的項目可包含 DOMAIN、DOMAIN-SUFFIX 或 IP-CIDR 等前綴；domain behavior 通常只儲存網域模式；ipcidr behavior 則儲存網段。不同格式不能任意混用，副檔名也不能取代 format 宣告。

payload:
  - DOMAIN,api.example.com
  - DOMAIN-SUFFIX,example.org
  - IP-CIDR,203.0.113.0/24,no-resolve

在主設定中使用 RULE-SET 時，策略目標寫在引用處，因此規則集內部通常不再寫入「代理選擇」這類目標。如此一來，同一份清單可以由不同設定重複使用。若下載的檔案本身已包含完整的三段式規則，就應確認 provider 的 behavior 與核心解析方式是否相符。看到「規則項目參數數量不正確」時，重點應放在檢查內容格式，而不是修改主規則的策略群組。

節點提供器、健康檢查與快取

proxy-providers:
  primary-subscription:
    type: http
    url: "https://subscription.example.net/profile.yaml"
    path: ./providers/primary.yaml
    interval: 21600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

proxy-groups:
  - name: "訂閱節點"
    type: select
    use:
      - primary-subscription
    proxies:
      - DIRECT

provider 回傳的內容應符合節點提供器所需的結構，不一定是一份完整的 Clash 設定。將完整設定位址直接當作節點 provider 使用，可能因頂層結構不同而失敗。圖形客戶端中的「訂閱」通常是完整設定訂閱，和 proxy-providers 的概念不能簡單等同。若客戶端已負責更新完整設定，應優先沿用客戶端流程，而不是額外再嵌套一層 provider。

健康檢查會對 provider 中的節點發起測試，方便自動群組判斷可用性，但頻率過高會增加資源使用量。行動裝置還要考慮電量與背景限制。測試失敗不一定代表節點對所有目標都不可用，可能只是測試位址遭到阻擋或目前網路無法存取。判斷時應結合實際連線日誌，避免僅根據一個測試標記刪除節點。

更新失敗的分層排查

外部資源失敗可分為下載、寫入、解析與引用四個層次。下載層檢查 URL、DNS 與目前出站；寫入層檢查快取目錄權限；解析層核對 format、behavior 與檔案內容；引用層確認 RULE-SET 或 use 名稱與頂層定義一致。遠端規則更新也可能經過目前代理，錯誤的分流會形成「需要規則才能下載規則」的依賴。可為設定資源網域設定明確路徑，或確保首次啟動時具備可用的基礎連線。

八、覆寫、合併、驗證與故障排查

訂閱設定需要定期更新，而個人設定希望長期保留，這正是覆寫與合併存在的原因。直接編輯訂閱產生的 YAML 最直觀，但更新後容易被替換；將自訂內容放在獨立的覆寫層，可以讓「上游節點與公共規則」和「本地連接埠、DNS、個人規則」各自維護。不同客戶端對覆寫的稱呼與能力不完全相同，可能提供欄位覆蓋、規則前置、規則後置、腳本處理或 YAML 合併。使用前應先確認它是替換整個欄位，還是遞迴合併映射。

映射適合依鍵遞迴合併，清單則最容易產生歧義。對於 dns 這類映射，覆寫一個子鍵可能保留其他子鍵；對於 rules、proxies 與 proxy-groups 這類清單，有些工具會整體替換，有些則支援前置或追加。如果誤以為清單會自動串接，可能導致訂閱原有規則全部消失；誤以為會替換，則可能留下兩個同名策略群組。不了解客戶端語意時，不要一次覆寫大量清單。

安全的覆寫界線

通用連接埠、日誌層級、區域網路開關與少量 DNS 子項，通常適合欄位覆寫。個人網域例外適合規則前置。需要新增策略群組時，應同時處理群組定義、引用的節點來源與規則目標，最好作為一個完整變更進行驗證。節點驗證參數通常交由訂閱維護，除非明確是在管理自己的靜態節點。覆寫檔案應比主設定更短，只表達與上游不同的部分。

# 本機覆寫示意，具體合併語法以客戶端為準
mixed-port: 7890
log-level: info
allow-lan: false

dns:
  enable: true
  ipv6: false

prepend-rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,internal.example,DIRECT

prepend-rules 並不是標準主設定頂層欄位，而是部分覆寫工具可能採用的表示方式，不能直接複製到所有客戶端。實際操作時，應使用客戶端明確提供的「規則前置」入口。本例重點在於區分主設定欄位與覆寫指令：前者由核心讀取，後者由客戶端或轉換工具先行處理，處理後的最終 YAML 才交給核心。

合併後的檢查清單

每次修改後先查看最終產生的設定，而不是只看覆寫片段。確認頂層沒有重複鍵、監聽連接埠沒有衝突、DNS 層級完整、節點與策略群組名稱唯一、所有引用目標存在、策略群組沒有循環，且規則末尾只有一個明確的 MATCH。若使用 providers，還要檢查快取路徑、行為類型與引用名稱。設定驗證通過後，再啟動或熱重新載入。

使用核心進行設定驗證

直接執行 mihomo 的使用者可以使用核心提供的設定測試參數，在啟動服務前檢查檔案。不同安裝方式下，可執行檔名稱與設定目錄不同，應以實際路徑替換範例。圖形客戶端通常也會在匯入或切換設定時執行驗證，並在日誌頁顯示錯誤行。客戶端提示訊息遭截斷時，可以開啟日誌頁尋找完整原因。

# 在目前目錄檢查 config.yaml
mihomo -t -f ./config.yaml

# 指定設定工作目錄後檢查
mihomo -t -d ./clash-profile -f ./clash-profile/config.yaml

驗證成功只代表設定結構與已知欄位符合要求，不代表遠端節點、規則集或 DNS 服務一定可用。啟動後還需要觀察 provider 更新、連接埠監聽與連線日誌。若驗證提示某行錯誤，實際原因可能位於上一行，例如引號未閉合或父層縮排不正確。先查看錯誤行上下各數行，再逐步縮小範圍。

典型故障的處理順序

「客戶端無法開啟」應先排查權限、連接埠佔用、設定語法與核心檔案，可參考啟動崩潰與閃退處理步驟。「客戶端能啟動但所有連線失敗」應檢查系統代理或 TUN 是否真正啟用、連接埠是否一致、節點是否可用。「部分網站路徑不正確」則重點檢查 DNS、規則順序與策略群組目前的選擇。「訂閱更新後自訂內容消失」表示修改落在上游檔案中，應移至覆寫層。

發生連接埠佔用時，不要連續嘗試多個隨機連接埠卻忘記同步系統代理。先確認佔用程序，關閉重複的核心，或選擇一個明確的新連接埠並同步所有入口設定。規則未命中時不要立刻加入更寬泛的 DOMAIN-KEYWORD，先從日誌取得真實網域。DNS 異常時不要同時更換 nameserver、關閉 fake-ip 並重寫規則；一次只變更一個變數，保留可回復的設定副本。

「熱重新載入成功但行為沒有改變」可能是因為舊連線、應用程式快取、客戶端執行狀態的選擇，或覆寫未重新執行。建立新連線並檢查最終設定檔的修改時間與內容，確認核心實際讀取的是目標檔案。多設定客戶端常有目前設定、訂閱快取與執行時產生的設定三個層次，編輯錯誤檔案是常見原因。透過客戶端設定頁確認目前啟用的項目，再從日誌查看載入路徑，比在磁碟中逐一猜測更可靠。

建立可回復的維護流程

穩定的維護流程應包含四個步驟：保存一份已知可用的設定；針對單一目標進行小幅修改；先驗證再載入；透過日誌驗證實際行為。若修改失敗，回復至上一份可用設定，而不是繼續在錯誤設定上疊加修補。個人規則、DNS 例外與策略群組結構可以分別維護說明，記錄修改原因與相依關係，後續清理會更容易。

訂閱更新前後可以比較頂層欄位、策略群組名稱與規則末尾結構，不必逐行比較所有節點。上游新增節點通常不會影響個人規則，但策略群組改名、provider 名稱變更或規則目標調整會影響覆寫。定期刪除失效例外與不使用的 provider，可以降低日後更新衝突。設定的目標不是欄位越多越好，而是每個欄位都有明確作用、每條引用都能追蹤，發生問題時能快速回復。