Clash 設定欄位

YAML 結構與設定範圍

重點：設定檔描述的是一組彼此引用的物件，而不是可以任意排列的設定清單。頂層欄位決定監聽、解析與轉送行為；節點提供連線出口，策略組管理出口選擇，規則則將請求交給特定策略。閱讀不熟悉的設定檔時，先確認這四個層級是否完整，再檢查名稱是否相符。單看某一行格式正確，無法保證整份檔案會如預期運作；例如規則引用了不存在的策略組，即使縮排完全正確，設定仍無法正常生效。

頂層對應、清單與巢狀結構

YAML 以縮排表示從屬關係，建議統一使用兩個空格，不要使用定位字元。dns: 底下的 enable 是 DNS 子欄位，若將它對齊頂層的 mode，就不再具有原本的意義。以連字號開頭的是清單項目；同一個節點的 name、type、server 必須位於相同的對應層級。冒號後通常要加空格，也不能用中文標點取代半形冒號。程式碼編輯器的縮排參考線，比肉眼計算空格更可靠。

# 可獨立載入的直連結構範例，不包含遠端代理節點
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

rules:
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

這份範例用來說明結構，並不會憑空取得代理能力：PROXY 組裡只有 DIRECT，最後仍會直接連線。實際使用時，應將有效節點或節點提供器加入策略組。空清單 [] 表示欄位存在但暫時沒有項目，與刪除整個欄位並不相同。逐步擴充時，先保留可載入的基本架構，每次只新增一類物件，發生問題時才容易找出是哪次變更造成的。

字串、布林值與名稱引用

連接埠和間隔通常以數字表示，開關則使用 true 或 false，不要寫成中文的「開啟」。節點名稱、密碼，以及含冒號或井字號的字串，建議加上引號，避免被解析為對應或註解。單引號字串中的單引號要寫成兩個；雙引號內的反斜線可能會觸發跳脫。複製含 Windows 路徑的值時尤其要留意，使用單引號可減少意外跳脫。註解只供閱讀，不會影響欄位的生效順序。

同一個對應中不要重複定義兩個 dns 或兩個 rules。不同解析器對重複鍵的處理方式可能不同，有些會拒絕載入，有些則保留後者；不能把重複鍵當成合併機制。策略名稱也應保持唯一，大小寫、空格與符號都必須依原樣引用。重新命名節點後，需同步修改策略組中的名稱；重新命名組別後，則需同步更新規則目標及其他組別對它的引用。

檔案、Profile 與執行中的設定

用戶端中的 Profile 是設定來源及其管理記錄，可以指向本機檔案，也可以來自遠端訂閱。訂閱更新後儲存的內容，不一定就是核心最後讀取的內容，因為用戶端可能接著套用連接埠設定、合併規則或執行指令碼。排查時要分清楚「訂閱原始內容」、「本機編輯副本」與「執行中的設定」這三個物件。只修改下載快取中的檔案，可能在下次更新時遺失；只修改未選取的 Profile，也不會影響目前的連線。

儲存設定前，先保留可還原的副本，並記下目前選取的 Profile。一般文字編輯器應以 UTF-8 儲存，避免使用文書格式、全形空格或自動替換引號。副檔名有助於用戶端識別檔案，但改成 .yaml 並不會將網頁內容轉換為設定檔。若匯入後看到 HTML、登入提示或訂閱流量說明，應先處理來源問題，而不是繼續調整縮排。多組設定的切換與保存方式，請參閱Profile 與多組設定管理。

連接埠、監聽位址與流量入口

重點：監聽連接埠只會建立入口，不會讓所有應用程式自動經過代理。應用程式必須主動連線到這個入口，或透過系統代理、透明轉送等機制將流量送進核心。最常見的 mixed-port 可在同一個連接埠接受 HTTP 與 SOCKS 代理連線，適合桌面應用統一設定。port 與 socks-port 則分別建立獨立的 HTTP、SOCKS 入口，只有確實需要區分入口時才應分別啟用，避免增加難以追查的監聽項目。

選擇連接埠與檢查占用

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule

此範例只允許本機存取，適合作為單機使用的起點。連接埠號不是效能參數，也不是節點伺服器端的連接埠；修改本機監聽連接埠後，瀏覽器、終端機及其他手動設定代理的應用程式也要同步更新。不要將同一個連接埠指派給多個監聽欄位，也不要讓兩個代理用戶端爭用相同的位址與連接埠。核心提示位址已被占用時，應先關閉舊程序或調整監聽設定，再重新載入；反覆切換節點無法解決本機繫結失敗。

在 Windows 上可使用 Get-NetTCPConnection -LocalPort 7890 查看對應的 TCP 監聽；Linux 可使用 ss -lntp，macOS 可使用 lsof -nP -iTCP:7890 -sTCP:LISTEN。部分程序資訊需要較高權限才能顯示。檢查結果時要一併確認位址、連接埠與程序，不要只因為數字相同，就認定代理已啟動。繫結在回送位址的服務，無法從另一台裝置直接存取。

本機代理與區域網路分享

若要讓同一個區域網路中的其他裝置使用，應先了解存取範圍，再啟用 allow-lan，並確認繫結位址涵蓋相應介面。連線裝置要填入執行用戶端那台電腦的區域網路位址，而不是自己的 127.0.0.1。本機防火牆、無線基地台的裝置隔離，以及不同子網路之間的路由，都會影響連線是否可達。先確認本機能透過入口連線，再從區域網路裝置測試，就能區分核心故障與網路隔離問題。

代理認證與節點認證是兩回事：前者用來限制誰能使用本機入口，後者則用於連線至遠端服務。啟用入口認證後，連線應用程式也必須支援並填入對應的使用者名稱與密碼；部分系統代理設定介面無法完整設定這些參數，需改用應用程式本身的代理設定。分享失敗時，不要為了排錯而長期關閉所有防火牆規則，應針對所需介面、來源位址與連接埠逐一檢查。

系統代理、終端機與 TUN 的適用範圍

系統代理通常只是將入口位址提供給遵循系統設定的應用程式，無法保證所有程式都會讀取。命令列工具往往依賴環境變數或自身參數；可使用下方指令明確指定 HTTP 代理，避免把環境變數殘留問題誤判為核心問題。測試成功只能證明該請求是透過指定入口送出，不代表其他應用程式也已接入，更不能證明所有網域的分流都正確。

curl --proxy http://127.0.0.1:7890 https://example.com/

TUN 是虛擬網路介面入口，涉及系統權限、路由、DNS 接管及現有網路軟體，並非開啟一般監聽連接埠後就必然需要的步驟。只有在應用程式不支援代理或需要更全面接管流量時，才依照用戶端文件啟用。系統代理正常但終端機連線失敗時，可先閱讀分開檢查瀏覽器與命令列。挑選用戶端時，建議先從下載頁的 Clash Plus 開始，再依平台與所需功能比較其他用戶端。

代理模式、記錄檔與控制介面

重點：mode 決定如何選擇轉送策略，不會建立節點，也不會接管應用程式。規則模式會讀取規則清單，全域模式使用全域策略的目前選項，直連模式則直接連線到目標。切換模式前，應先確認流量已進入核心，且存在可用策略。將模式改成全域，無法修復監聽失敗、訂閱內容為空或遠端伺服器無法連線等問題；它只能協助判斷問題是否與規則選擇路徑有關。

rule、global 與 direct 模式

mode: rule
log-level: info
ipv6: false

rule 適合長期依網域、位址及應用程式需求進行分流。global 會略過一般規則選擇，改用全域策略目前選取的項目，因此也要檢查用戶端全域組選了什麼；若選到直連，全域模式也不會自動變成代理。direct 用於判斷不經代理出口的連線。這三種模式都不能取代系統入口設定；尚未進入核心的應用程式，不會因為切換模式而改變連線路徑。

測試時一次只改變一個變數。例如某網站原本無法連線，保持節點與 DNS 不變，只將規則模式切換為全域模式，再重新連線。如果全域模式可用、規則模式失敗，就檢查規則命中狀況與目標組；若兩者都失敗，則繼續檢查節點與解析。若同時更換節點、模式及 DNS，即使恢復連線，也很難判斷是哪項變更有效。持續連線也可能沿用舊出口，測試時應先關閉舊連線再觀察。

如何運用 log-level 排查問題

info 適合日常保留重要執行資訊；需要追蹤個別請求時，可短暫切換至 debug。warning 與 error 會逐步減少輸出，silent 則可能讓排查缺乏依據。記錄檔層級本身不會提升節點速度，詳細記錄也可能增加輸出負擔。觀察一段可重現的操作後，就應恢復日常層級，避免長期累積大量不必要的資料。

閱讀記錄檔時，先依階段分類：設定解析階段的錯誤指向檔案內容；監聽階段失敗則指向本機位址與權限；請求進入後發生解析錯誤，應檢查 DNS 路徑；撥號或交握失敗則要檢查目標出口及協定參數。同樣是逾時，若發生於 DNS 查詢、建立 TCP 連線或 TLS 交握，排查方向並不相同。不要只看一行英文錯誤訊息，就批次替換所有欄位。

有效的重現紀錄應包含目前的 Profile、模式、命中的規則、選取的策略，以及錯誤發生前後的記錄。分享記錄檔前，請刪除訂閱網址、認證資訊、個人存取網域及區域網路架構等敏感內容。執行記錄與常見錯誤對照提供了進一步的閱讀順序。若記錄中沒有目標請求，應先回頭檢查入口，而不是繼續研究根本沒有執行的規則。

控制介面不是代理入口

external-controller 供用戶端或面板管理核心，可查詢狀態、切換策略及修改部分執行設定；不能將它填入瀏覽器當作 HTTP 代理。桌面用戶端通常會自行管理此介面與存取憑證，不建議任意在訂閱中覆寫。手動執行核心時，應優先繫結至回送位址；確實需要遠端管理時，再配合認證與網路存取限制，不能把管理連接埠當成一般區域網路分享連接埠。

頂層的 ipv6 會影響核心使用 IPv6 的行為，DNS 底下的同名欄位則屬於解析設定；只修改其中一項，不能據此推斷整個網路堆疊的結果。是否啟用應由本機網路、代理服務及應用程式需求共同決定，不要把停用 IPv6 當成固定的最佳化方式。若只有特定類型的位址連線失敗，應分別觀察解析結果與實際連線路徑，再調整相應層級的欄位。

DNS、Fake-IP 與解析路徑

重點：DNS 設定同時涉及應用程式查詢、核心解析與節點網域解析，不能只看單一伺服器位址。應用程式可能使用系統 DNS，也可能自行傳送加密查詢；核心為了連線到目標或節點，也可能發起解析。因此，修改 nameserver 不代表所有查詢都會經過這份清單。先釐清請求在哪裡產生、由誰接收，以及查詢結果交給誰使用，再判斷應調整監聽、接管機制或上游選擇。

啟用與監聽的基本關係

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:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"

此片段會建立本機 DNS 監聽，但不會自動修改系統 DNS。傳統系統 DNS 設定通常無法直接指定非標準連接埠，因此不能只把系統位址改成回送位址，就期待系統查詢自動送往 1053。這需要用戶端的 DNS 接管、TUN 配套功能或其他明確的轉送機制。若裝置上已有 DNS 服務，應先確認監聽位址與連接埠是否衝突，避免將載入失敗誤認為上游解析服務無法使用。

default-nameserver 可用來解析 DNS 服務本身的網域，解決先有網域還是先有解析的問題；這裡通常使用可直接連線的 IP 位址。nameserver 是主要上游清單，能否連線取決於網路連通性及相應的出站設定。使用加密 DNS 可以改變查詢傳輸方式，但不能證明查詢一定經過代理，也不能保證遠端服務在目前網路中可連線。上游數量多不代表結果更準確，應先採用容易驗證的組合。

fake-ip 與 redir-host 的差異

fake-ip 會為查詢指派合成位址，並維護網域與位址的對應；連線至合成位址時，再還原網域進行處理。這有助於保留網域資訊，但要求 DNS 查詢與後續流量進入同一套處理流程。如果應用程式取得合成位址後繞過核心直接連線，通常無法建立連線。redir-host 則回傳實際解析結果，適用的相容路徑不同；兩者並非單純的速度開關。

fake-ip-filter 可讓指定網域略過合成位址流程，適合處理區域網路服務探索或必須綁定真實位址的應用程式。範例中的區域網路後綴只是起點，不是適用所有環境的完整清單。將網域加入篩選，不會自動為它新增直連規則，也不會自動指定正確的區域網路 DNS。印表機、內部網域或本機服務異常時，應一併核對網域解析來源、回傳位址及連線路由，不要擴大篩選範圍後就停止檢查。

依網域選擇上游並避免解析迴圈

nameserver-policy 可為特定網域選擇上游，例如將內部網域交由區域網路解析器處理。策略鍵的比對語法應符合核心支援範圍，它不是可以直接複製所有規則表示式的第二個 rules。proxy-server-nameserver 則用於解析代理節點網域，適合將建立出口所需的基礎解析獨立管理。節點伺服器本身解析失敗時，即使目標網站解析正確，也無法建立代理連線。

啟用 respect-rules 等依分流規則決定 DNS 出站路徑的選項前，應先規劃節點網域的獨立解析路徑。若 DNS 請求必須先經過代理，而代理又依賴同一個 DNS 請求才能建立，就可能形成迴圈。不要一次加入依規則出站、多個上游、複雜篩選及多層回退。先確認基本上游可連線，再逐項增加條件，並在記錄檔中觀察解析與撥號階段是否順利銜接。

fallback 與搭配的篩選設定並非永遠啟用的備用按鈕，結果選擇會受到篩選條件影響；照搬其他網路的位址範圍與地區設定，可能改變預期的解析結果。排查時應記錄查詢網域、回應位址、使用的上游及連線命中的策略。只有部分應用程式失敗時，也要檢查應用程式內建的 DNS 是否略過系統設定。特定症狀的簡短解答可參閱常見問題，不要同時開啟所有 DNS 選項。

代理節點欄位與節點提供器

重點：節點欄位必須與服務端提供的協定參數逐項相符，名稱相似不代表可以互換。proxies 是節點物件清單，常見的共用欄位包括名稱、類型、伺服器位址及連接埠；認證、加密、傳輸與 TLS 欄位則會隨協定不同。訂閱成功匯入，只能證明用戶端接受設定結構，不能證明伺服器位址可連線，也不能證明認證與交握參數正確。

共用欄位與協定專屬欄位

# 結構範例：example.com 與認證值僅供說明欄位
proxies:
  - name: 範例出口
    type: socks5
    server: proxy.example.com
    port: 1080
    username: "your-username"
    password: "your-password"
    udp: true

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - 範例出口
      - DIRECT

此範例展示 SOCKS5 節點如何被策略組引用，並不提供實際代理服務。name 是本機識別名稱，修改它不會改變伺服器，但會影響其他位置的引用。server 是遠端位址，port 是伺服器端的監聽連接埠，不能用本機的 mixed-port 取代。使用者名稱與密碼應依實際服務參數填寫；若服務端不使用這種認證方式，就不應為了補齊欄位而任意新增。

type 決定後續欄位的解讀方式。Shadowsocks 的加密方式與密碼、VMess 或 VLESS 的使用者識別碼、Trojan 的認證與 TLS，以及其他協定的傳輸參數各有不同限制；不能在同一個節點中混用不同協定的欄位來嘗試相容。遇到未知欄位提示時，先確認目前的核心是否支援相應協定與欄位，再檢查訂閱格式，不要直接刪除所有報錯欄位；刪掉必要的傳輸參數，可能讓設定順利載入卻無法連線。

TLS、傳輸層與 UDP

需要 TLS 的節點可能包含伺服器名稱、應用層協定協商及憑證相關選項。伺服器名稱通常用於交握與憑證驗證，不一定等於連線位址；位址、TLS 名稱及 WebSocket 請求標頭中的主機欄位，也可能各自扮演不同角色。應依照服務端提供的組合填寫。不要隨意將某個可連線的網站網域填入這些欄位；網域看起來正常，不代表對應的服務端會接受交握。

憑證驗證失敗時，應檢查系統時間、伺服器名稱、憑證有效性及服務端設定。略過驗證會削弱遠端身分確認，不應當成通用修復方式長期使用。WebSocket、gRPC 等傳輸方式也需要符合路徑、服務名稱或請求標頭設定；任何一層不相符，都可能導致連線中斷。排查時應保留服務端的原始參數作為對照，不要只比較用戶端介面上顯示的節點名稱。

udp: true 表示允許使用相應節點的 UDP 能力，無法讓不支援 UDP 的服務端因此取得該能力。還要確認應用程式入口、策略組、節點協定與遠端服務整條路徑都支援所需流量。網頁可開啟，但遊戲或語音失敗時，應先區分 TCP 與 UDP；單次 HTTP 測試成功不足以驗證所有應用程式。反過來說，UDP 無法使用，也不代表一般 HTTPS 請求必然失敗。

proxy-providers 與整份訂閱的差異

# 提供器片段：本機檔案須事先存在，且包含 proxies 清單
proxy-providers:
  local-nodes:
    type: file
    path: ./providers/local-nodes.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - local-nodes
    proxies:
      - DIRECT

proxy-providers 可將節點來源獨立管理，策略組透過 use 引用提供器，而不是把提供器名稱放入一般節點清單。檔案來源必須有實際存在且符合提供器格式的檔案；網路來源則需要正確的位址、儲存位置與更新設定。完整的 Profile 通常還包含 DNS、規則與策略組，不能預設整份訂閱原始內容可直接當成僅含節點的提供器檔案使用，實際情況仍取決於來源支援的輸出格式。

提供器取得成功與其中節點可以連線，也要分開判斷。前者取決於下載路徑與內容格式，後者則取決於協定及出口。服務回傳登入頁面、錯誤文字或空清單時，應先處理訂閱授權、有效期限及回應內容。訂閱連結可能含有存取憑證，不應貼到公開記錄或線上轉換工具。所有節點都無法連線時，可依照從訂閱到出口的逐層排查順序確認故障層級。

用戶端能否編輯某類節點，與核心是否支援相應欄位，是兩個不同問題。選擇 Clash Plus、Clash Verge Rev、FlClash 等用戶端時，應一併確認它們目前使用的核心與匯入能力；介面沒有顯示的欄位不一定無效，介面允許輸入也不代表服務端會接受。維護節點時，應優先保留可信來源提供的原始參數，將策略與規則自訂放在外層，減少手動改寫認證資訊。

策略組、自動選擇與引用關係

重點：策略組是出口選擇器；規則指向組別後，仍須由組內目前的策略決定最後使用的節點。proxy-groups 可將多個節點、其他組別或提供器組織起來。規劃時先釐清使用者需要哪些選擇，例如手動固定出口、自動選擇或故障切換，再決定組別類型。把各種組別類型全都堆進設定檔，不會自動提升可靠性，反而會讓實際出口更難判斷。

select 與巢狀策略組

# 直連組用來展示可載入的結構，請依需求加入實際節點
proxy-groups:
  - name: 手動選擇
    type: select
    proxies:
      - DIRECT

  - name: PROXY
    type: select
    proxies:
      - 手動選擇
      - DIRECT

rules:
  - MATCH,PROXY

select 由使用者或控制介面決定目前選項，適合需要固定出口的應用程式。範例中的規則先指向 PROXY，接著可能進入「手動選擇」，最後到達 DIRECT；實際連線時應沿著這條引用鏈追蹤。組名只是識別名稱，不代表其行為。名為「自動」的組別若類型仍是 select，也不會自動測試並選出節點。

巢狀組別應避免循環，例如甲組引用乙組，而乙組又引用甲組。命名也應區分用途與來源：用途組可命名為工作、媒體或預設出口，來源組則可對應特定提供器。如此一來，訂閱更新節點時就不必同步修改所有規則。組別層級不宜太深，通常只要透過少數幾層就能說明最後的出口即可；否則介面雖顯示已選取某個名稱，仍需逐層展開才能看出實際路徑。

url-test、fallback 與 load-balance

url-test 依據探測結果選擇候選出口，適合可接受自動切換的連線情境。fallback 著重候選順序與可用性，適合希望優先使用某個出口、失敗後再切換的情況。load-balance 會依策略將連線分配給不同候選節點，並不是把單一下載連線的頻寬加總。登入、付款或工作階段等需要穩定來源位址的服務，應謹慎使用可能變更出口的組別。

# 片段：local-nodes 提供器須已在 proxy-providers 中定義
proxy-groups:
  - name: 自動選擇
    type: url-test
    use:
      - local-nodes
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

範例中的 interval 是探測間隔，tolerance 用於減少因些微差異而頻繁切換；兩者都不是節點測速結果。探測位址應能在目前網路與出口下穩定連線，且回應適合用於連線測試。某個位址探測失敗，可能是測試目標受到限制，不代表節點無法連線至所有目標；應與實際應用程式請求交叉驗證，不要只憑單一測試結果決定所有服務的策略。

候選清單、篩選與測試範圍

proxies 用來填寫明確的節點或策略名稱，use 則引用節點提供器；這兩種來源可以搭配使用，但應避免候選重複或清單為空。使用 filter 等名稱篩選條件時，要確認正規表示式比對的是實際節點名稱，而不是提供器名稱。訂閱方更改名稱後，原本有效的篩選條件可能突然找不到任何項目。排查自動組別沒有節點時，先檢查提供器內容，再查看篩選結果，最後才檢查探測設定。

健康檢查回答的是指定探測目標能否依條件完成請求，不是節點在所有協定與目的地上的通用評分。頻繁並行探測會產生額外連線，對行動網路、低功耗裝置或流量有限的服務尤其要節制。若提供器層與策略組層都設定了檢查，也要留意是否造成重複探測。只保留足以判斷可用性的頻率即可，不要為了讓介面資料持續更新而縮短間隔。

規則所指向的用途組應盡量保持穩定，節點更換則在組內完成。發現同一個網站偶爾使用不同出口時，先檢查自動組是否切換、應用程式是否建立多條連線，以及網域是否對應多條規則路徑，再考慮服務端問題。需要長期固定出口的工作，可另外建立手動組，避免與日常自動選擇混用。不同用戶端的組別選擇介面，可在用戶端選擇指南中依平台需求比較。

規則語法、比對順序與規則集

重點：規則依清單順序由上而下處理，第一條符合的規則決定本次分流，不會依文字長短自動判斷優先順序。維護 rules 時，應將具體例外放在一般規則之前，兜底規則則放在最後。新增規則前，先確認它要比對哪些資訊：網域、目標位址、來源位址或程序。規則可使用的資訊取決於入口與系統環境，不能假設每條連線都帶有完整網域及程序名稱。

網域規則與目標策略

# 片段：PROXY 策略組須已定義
rules:
  - DOMAIN,login.example.com,PROXY
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,internal,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,PROXY

DOMAIN 比對完整網域，DOMAIN-SUFFIX 比對網域後綴及其子網域，DOMAIN-KEYWORD 則依網域是否包含指定關鍵字判斷。關鍵字規則的涵蓋範圍通常較廣，容易將不相關的網域一併納入；有精確需求時，優先使用完整網域或後綴。填寫時不要加上 https://、路徑或連接埠；這些是 URL 的其他部分，不是網域規則要比對的值。

規則最後一段是目標策略，可以是內建動作，也可以是已定義的節點或組別。為了方便維護，通常讓規則指向用途組，而不是可能隨訂閱更新而改名的節點。DIRECT 表示直接連線，REJECT 用於拒絕請求；策略名稱必須與定義完全相同。組名寫錯不是「沒有符合規則」，而是設定中的引用關係有誤，應在載入檢查階段處理。

位址比對與 no-resolve

IP-CIDR 用來比對 IPv4 網路，IPv6 網路則使用對應的 IP-CIDR6。當請求以網域形式進入，而規則需要真實位址才能判斷時，核心可能會觸發解析。結尾的 no-resolve 用來避免因這條位址規則而主動解析網域，但不會阻止已取得目標位址的連線參與比對，也不是全域停用 DNS。對所有位址規則一律加上這個選項，可能改變原本的分流結果。

GEOIP 依據位址資料庫分類，結果取決於資料庫內容與更新狀況；常見的網域分類 GEOSITE 則需要相應的資源與核心支援。範例中的特定地區直連只用來展示寫法，不應視為所有網路的預設政策。資料庫分類不等於服務實際所在地，也不能保證目標可連線。企業網路、跨區域服務及自建位址應依實際需求設定例外，不要依賴單一分類解決所有問題。

rule-providers 與 RULE-SET

# 檔案須事先存在，內容格式必須與 behavior 相符
rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,PROXY

規則提供器會將可更新的比對內容放在獨立檔案中，再由主設定透過 RULE-SET 引用。behavior 用來說明內容屬於網域、位址範圍或傳統規則表示式，不能只看副檔名判斷。YAML 格式的網域提供器通常會在 payload 下列出網域比對項目；傳統行為的規則集則使用對應的規則表示式，不必在每一行重複填寫主設定中的目標策略。

成功下載規則集檔案後，仍需確認內容格式與行為設定是否相符。將純文字網域清單當成 YAML，或將完整規則清單交給網域行為解析，都可能造成錯誤或非預期結果。網路型規則來源還涉及更新請求是否可連線、快取檔案是否可寫入。更新失敗時應保留仍可使用的快取並排查取得問題，不要立刻重設整份主設定，導致其他原本正常的部分也一併遺失。

從連線記錄回推規則

驗證新規則時，應發起新連線，並記錄請求網域、命中的規則及最終策略。瀏覽器頁面通常會同時存取主網域、登入、靜態資源及 API 網域；若頁面只載入一部分，就要分別觀察這些連線，不能只替網址列中的網域新增一條規則。若連線記錄中只剩 IP，應檢查應用程式是否自行解析、DNS 是否進入核心，以及目前的入口是否保留網域資訊。

程序規則也會受到平台、權限與入口影響；相同設定換到另一台裝置，可能無法取得相同的程序中繼資料。不要將程序規則當成跨平台的唯一依據。逐條排查時，先找出最早能符合的規則，再確認組內選項，最後驗證出口。若規則模式失敗而全域模式正常，沿著這條路徑排查，比直接批次新增寬泛關鍵字更容易控制；臨時例外驗證成功後，也應縮小範圍並註明用途。

訂閱覆寫、設定合併與載入檢查

重點：可持續使用的自訂設定應與可能被遠端更新取代的訂閱原始內容分開，並以最終執行中的設定作為驗收依據。用戶端通常提供覆寫、合併、擴充設定或指令碼入口，但這些都是用戶端產生設定的機制，並非所有用戶端共用的 YAML 標準。改用其他用戶端時，應重新確認套用順序與合併語意；不能只複製一份名為覆寫的檔案，就假設結果相同。

純量、對應與清單的合併差異

純量欄位例如 mode、mixed-port，通常會以後寫入的值覆蓋先前的值；對應欄位例如 dns，可能逐鍵合併，也可能整體取代；清單欄位例如 rules、proxies，則可能取代、置前或附加。實際行為必須以用戶端文件與產生結果為準。只知道某項功能叫做「合併」，不足以判斷原有節點或規則是否會保留。

# 概念範例：僅適用於支援規則置前的用戶端覆寫入口
# 不應直接串接為第二個頂層 rules
rules:
  - DOMAIN,work.example.com,DIRECT

若用戶端以這段內容整體取代原有規則，所有訂閱規則都可能被移除；若將它追加在原有 MATCH 之後，這條規則又可能永遠沒有機會比對。正確做法是使用用戶端支援的規則置前功能，或在指令碼中明確建立順序，再檢查最後產生的清單。DNS 合併也一樣：修改上游清單時，應確認其他子欄位是否保留，避免只想修改一個位址，卻清除了監聽與模式設定。

確認寫入順序與名稱穩定性

建立簡單的來源記錄：訂閱提供哪些節點與規則、用戶端全域設定控制哪些連接埠、覆寫補充哪些 DNS 與例外，以及指令碼是否會再修改策略組。若多個入口都會修改同一欄位，應盡量集中由一處管理。執行模式反覆還原、連接埠儲存後變更、規則每次更新後消失，通常是後續產生步驟覆蓋前一步，而不是編輯器沒有儲存。

自訂規則所依賴的策略組應使用穩定名稱，並確認訂閱更新後仍會產生。若自訂組別引用特定節點，而服務商定期更改名稱，更新後就可能失去候選節點。較穩妥的方式是透過固定用途組，銜接提供器或用戶端的節點集合。指令碼修改前也應確認目標欄位的型別，不能假設所有訂閱都使用相同的清單結構；遇到缺少物件時，應提供易懂的錯誤訊息，而不是產生不完整的設定檔。

語法檢查、載入檢查與實際連線

# 適用於已安裝 mihomo 命令列程式的環境
mihomo -t -f ./config.yaml

命令列測試可用來找出設定解析與初始化問題；執行目錄、資源路徑及執行權限應盡量與實際啟動環境一致。引用的提供器檔案、地區資料庫或其他資源不存在時，即使 YAML 語法正確，仍可能載入失敗。桌面用戶端可優先使用內建的設定檢查功能，避免以另一個核心程式的結果取代目前用戶端環境的檢查。檢查通過只代表具備載入條件，不保證遠端節點可連線。

完整驗證分為三個階段：先確認設定已選取並成功載入，再確認入口已開始監聽且應用程式請求確實進入，最後檢查 DNS、規則、組別選擇與遠端交握。每個階段都應保留一個可重現的請求作為對照。修改後若只有既有連線仍沿用舊路徑，應先重新建立連線；若所有新請求都沒有記錄，就回頭檢查入口；若記錄顯示策略正確但交握失敗，再檢查節點參數與服務端狀態。

常見故障的回退順序

設定立即報錯時，先還原最後一次修改，檢查縮排、重複鍵、缺少的引用及欄位型別。設定可以載入卻無法連線時，先比較直連與指定代理的請求，再觀察實際命中的策略，不要混為一談。只有自動更新後才出錯時，應比對更新前後的節點名稱、提供器格式與規則目標。若只在特定用戶端重現，則進一步確認它的覆寫順序、核心功能與系統權限。

恢復正常後，應將成功條件寫入註解或維護記錄，例如哪類流量需要例外、為何使用特定解析路徑，以及某條規則必須放在哪條規則之前。不要記錄實際認證值，也不要把臨時繞過方式當成長期預設。首次使用仍建議依照入門指南完成一整套連線流程；遇到介面操作問題可參閱常見問題，更換用戶端則從用戶端平台下載項目選擇。新環境驗證完成前，請保留原有設定。