Clash 設定參考

YAML 結構與設定相依關係

從頂層映射辨識設定檔結構

Clash 設定不是依序執行的指令碼，而是一份描述執行狀態的映射。頂層的 mixed-port、mode 和 log-level 是純量；dns 是巢狀映射；proxies、proxy-groups 和 rules 則是清單。縮排決定父子關係，欄位的位置與內容同樣重要。例如，把 rules 縮排到 dns 底下，不會產生特殊的 DNS 分流規則，而是改變原有結構，可能導致錯誤或被忽略。

閱讀完整檔案時，先標出四條相依鏈：監聽入口將連線送進核心；規則將連線交給指定目標；策略群組把目標名稱對應至節點或其他群組；DNS 為網域連線提供解析結果。提供者負責補充節點或規則資料，但不會自動成為出口。只有策略群組引用節點提供者，或規則引用規則提供者，相關資源才會進入實際處理流程。了解這些關係後，排查問題就不必逐行猜測。

# 最小直連設定，可用來確認檔案結構與監聽入口
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: 出口選擇
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出口選擇

這份最小設定只使用內建目標 DIRECT，不會提供遠端代理服務。它適合先確認核心能讀取檔案、連接埠能正常啟動，以及用戶端能切換至規則模式。需要代理出口時，再加入實際節點，並將節點名稱加入策略群組。結構範例不等於可用訂閱：設定檔通過語法檢查，只能證明結構及部分引用有效，無法證明遠端伺服器存在或帳戶具備存取權限。

縮排、引號與清單的常見注意事項

建議一律使用兩個空格縮排，不要混用定位字元。短清單可以寫成 [DIRECT, 出口選擇]，較長的物件清單則建議每個項目各占一行，方便檢視層級。字串包含冒號後接空格、井字號，或看起來像布林值的內容時，請加上引號以明確指定型別。密碼、訂閱網址和純數字名稱也適合加引號，避免解析器將它們解讀成其他型別。註解只在字串之外生效，請勿用註解保存帳戶資訊。

同一個映射中不要重複定義相同欄位。例如在檔案開頭和結尾各寫一個 dns，不能當成可靠的增量合併方式；不同解析器可能會拒絕重複欄位，也可能只保留其中一段。需要補充 DNS 欄位時，應在同一個映射中修改。清單項目也不會依名稱自動合併：兩個同名策略群組通常代表衝突，而不是候選節點自動合併。設定檔越長，越應明確遵守「一處定義、其他位置引用」的原則。

區分來源設定、資源檔案與執行設定

用戶端通常會同時管理訂閱原文、提供者快取、覆寫片段，以及交由核心使用的執行設定。介面中看到的檔案不一定是最終檔案，編輯快取也可能在下次更新時被取代。開始修改前，請記下目前選取的設定名稱，匯出一份不含個人憑證的結構備份，並確認編輯入口是訂閱原文還是持久覆寫。安裝用戶端可先選擇 Clash Plus，再依實際平台確認設定編輯與執行記錄的入口。

拆分檔案主要是為了方便維護，不代表 YAML 本身支援任意匯入其他檔案。請勿自行加入 include 欄位，期待核心讀取目錄。節點與規則應使用受支援的提供者機制拆分；通用設定的重複使用則取決於用戶端是否明確提供合併功能。相對路徑通常以工作目錄為基準，不一定相對於目前編輯的檔案。移轉裝置時，除了主要設定檔，也要檢查資源路徑、寫入權限及用戶端產生的目錄。

監聽連接埠、模式與控制介面

入口協定與監聽位址

port 提供 HTTP 代理入口，socks-port 提供 SOCKS 入口，mixed-port 則在同一個連接埠接受 HTTP 與 SOCKS 請求。通常選擇一個混合連接埠即可，不必為每種入口都啟用監聽。應用程式必須主動使用代理位址，連線才會進入這些連接埠；僅啟動監聽不會自動接管系統流量。用戶端的系統代理開關屬於作業系統整合，TUN 則是另一種接入方式，不能只憑連接埠是否存在來判斷。

allow-lan: false 適合僅供本機使用。啟用區域網路存取後，還要確認 bind-address、作業系統防火牆和網路隔離設定是否允許其他裝置連線。監聽回送位址的服務無法從另一台裝置存取；監聽所有位址也不代表防火牆已放行。請勿為了排查單一應用程式，就直接擴大整台裝置的暴露範圍；先透過本機連線確認入口正常，再按需求逐步開放。

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

# 管理介面僅監聽本機；請另行在本機設定憑證
external-controller: "127.0.0.1:9090"

執行模式與記錄詳細程度

mode: rule 依規則清單選擇目標；global 將連線交由全域策略處理；direct 則使用直連路徑。即使規則檔案內容正確，若介面目前處於全域模式，規則也不會如預期參與選擇。部分用戶端會透過 API 還原上次使用的模式，因此磁碟上的初始值可能與介面目前狀態不同。遇到分流異常時，先確認執行模式，再檢查規則順序，不要立刻把所有規則都改成走代理。

log-level 用來控制記錄的詳細程度。日常使用可維持 info；需要追查解析、連線或資源載入問題時，再暫時切換至 debug。詳細記錄可能包含網域、目標位址及請求情境，分享前應移除訂閱網址、帳戶欄位及其他個人資訊。排查完成後請恢復原本的層級，避免長時間記錄不必要的瀏覽細節。記錄中出現連線資訊，只能證明流量到達某個處理階段，不能直接證明整個請求已成功。

管理 API 與執行環境限制

管理介面可切換策略、讀取連線並修改執行狀態，其權限與一般代理入口不同。建議維持回送位址監聽，由本機用戶端呼叫；確實需要跨裝置管理時，應設定獨立存取憑證、限制來源位址，並在可信任的網路邊界內使用。請勿將介面憑證寫入公開儲存庫，也不要公開包含完整管理網址的畫面截圖。介面無法開啟時，先確認控制位址是否與用戶端設定一致，再檢查連接埠衝突及核心是否已停止。

連接埠號碼本身沒有固定的特殊用途，範例中的數值可以調整，但應用程式、系統代理與用戶端必須同步更新。多個代理程式同時啟動時，最常見的問題是連接埠占用、系統代理設定互相覆蓋，以及虛擬路由互相競爭。排查時一次只保留一種接管機制，確認連線路徑後再恢復其他工具。Linux 服務也要檢查執行使用者、工作目錄與檔案權限；桌面用戶端運作正常，不代表相同檔案交由系統服務執行時，也能讀取相同資源。

ipv6 也不只是網路加速開關。是否啟用應視本機網路、節點出口與 DNS 回傳結果而定。停用核心的 IPv6 支援，無法取代作業系統的防火牆設定，也不能自動解釋所有 IPv6 直連現象。若應用程式繞過代理入口建立連線，應先處理接管範圍，再討論要使用哪種位址家族。常見的系統代理失效、連接埠衝突及區域網路連線問題，可參考 FAQ 故障排除進一步檢查。

代理節點欄位與協定限制

節點物件的基本組成

proxies 中的每個物件都描述一個出口。每個節點都需要可供引用的 name，協定由 type 決定；server 與 port 指定伺服器監聽位址。驗證方式、加密方法、傳輸層與 TLS 設定則依協定而異，不能在不同協定間照抄。名稱不是連線參數，卻是策略群組引用節點的識別名稱。修改節點名稱後，必須同步更新所有直接引用，尤其是手動維護的群組與規則目標。

以下以 Shadowsocks 示範設定結構。伺服器使用保留的範例網域，密碼則是教學用假值，必須替換成服務提供者給的對應參數才能連線。不要只憑連接埠或協定名稱推斷密碼、加密方法與傳輸方式。訂閱已包含完整節點設定時，建議保留上游欄位；確認欄位用途後，再進行局部調整。錯誤刪除傳輸設定，可能使原本可用的訂閱變成語法正確、但交握失敗的設定。

proxies:
  - name: 範例出口
    type: ss
    server: proxy.example.com
    port: 443
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    udp: true

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

傳輸層與 TLS 欄位不可任意拼湊

即使採用相同 TLS，不同協定也可能使用不同欄位名稱。部分節點使用 servername 指定交握名稱，另一些協定則使用 sni；是否需要 tls 開關、是否支援特定傳輸選項，都應查閱該協定的核心文件。伺服器位址可以是網域或 IP，但憑證通常對應網域。將網域換成 IP 後若未保留正確的交握名稱，可能造成憑證名稱不符，而不是伺服器離線。

WebSocket、HTTP/2 或 gRPC 等傳輸方式，也可能需要設定路徑、主機標頭或服務名稱。這些都是服務端約定的一部分，不是可以隨意刪減的備註。排查時應依序核對協定、位址、連接埠、驗證與傳輸，再檢查憑證及網路連通性。請勿把停用憑證驗證當成一般解法；這會降低確認服務端身分的能力，也無法修復錯誤密碼、錯誤路徑或服務端未啟用對應協定等問題。

UDP、解析與節點更新

udp: true 表示在相應協定支援的情況下允許 UDP 轉送，無法讓不支援 UDP 的服務端具備此能力。應用程式也必須透過支援 UDP 的入口進入核心，出口鏈路同樣要允許相應流量。網頁可瀏覽但遊戲或語音無法使用時，應分別檢查入口、策略群組選取的節點與遠端服務能力，不要只看 HTTP 測試結果。反過來說，節點測試正常但特定網站無法連線，也可能是規則選錯出口，而非節點本身無法連線。

當 server 使用網域時，連線至節點之前就必須先完成解析。這與透過代理瀏覽網站時解析目標網域，並非同一個階段。如果用來解析節點的 DNS 請求又依賴尚未建立的代理，就會形成啟動相依循環。為代理伺服器網域設定專用解析器，可以讓初始連線路徑更清楚；相關欄位請見後面的 DNS 章節。應先確認節點伺服器位址能正確解析，再分析目標網站的解析策略。

訂閱更新可能改變節點名稱與數量。若手動策略群組逐一列出節點，上游刪除或重新命名節點後，就可能出現失效引用；使用提供者的 use 匯入節點集合，更適合動態訂閱。對訂閱內容有疑問時，只匯出已遮蔽個人資訊的單一節點結構進行比較，不要公開完整訂閱 URL。節點清單、完整 YAML 與 URI 連結是不同類型的輸入；格式辨識可參閱訂閱格式差異與轉換，避免直接將編碼文字放進 proxies。

策略群組與出口選擇

穩定的群組名稱與可變動的節點集合

策略群組可將規則與具體節點分開。規則可以長期指向 出口選擇，更換節點時只需在群組內處理，不必逐一修改規則。群組名稱、節點名稱與內建目標都屬於可引用的目標，應避免重名，也不要使用容易與 DIRECT、REJECT 混淆的名稱。清單中的 proxies 是明確指定的目標，use 則是引用節點提供者，兩者用途不同，不能直接把提供者名稱當成節點名稱填入。

select 由使用者選擇出口；url-test 依探測結果選擇候選節點；fallback 按清單順序尋找可用出口；load-balance 則依指定策略分配連線。自動選擇不代表所有業務都會比較後選出最佳路徑，探測 URL 只反映某個目標在特定時間的連通性。存取目的地、協定類型或服務端限制不同，都可能使實際使用情況與探測結果有所差異。

# 搭配前一章的「範例出口」節點使用
proxy-groups:
  - name: 出口選擇
    type: select
    proxies:
      - 自動選擇
      - 範例出口
      - DIRECT

  - name: 自動選擇
    type: url-test
    proxies:
      - 範例出口
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - MATCH,出口選擇

探測間隔、容差與故障切換

interval 以秒為單位設定探測週期；適用於自動選擇群組的 tolerance 則以毫秒表示切換容差。設定容差可減少輕微波動造成的頻繁切換，但無法解決遠端壅塞。週期太短會增加請求數量，也會頻繁喚醒裝置；行動裝置尤其要考量電量與網路切換。探測網址應能穩定回傳預期結果，且不需要先登入；若探測目標本身無法連線，整個候選集合都可能被誤判為不可用。

故障切換群組的順序代表實際用途。排在前面的目標不代表永遠比較快，而是在符合可用條件時優先使用。負載平衡通常也以連線為單位分配，不會把單次下載拆成多個節點來加總頻寬。需要維持登入工作階段或來源位址穩定的服務，應謹慎使用跨出口分配，先確認目標服務是否允許位址變動。切換規則目標後，既有 TCP 連線通常不會自動改走新出口，驗證時應建立新連線。

巢狀引用與選擇狀態

策略群組可以引用其他群組，但必須形成具有出口的有向關係。如果甲群組引用乙群組，而乙群組又引用甲群組，就會形成循環相依；即使介面允許儲存，執行時也可能拒絕設定或無法選出有效出口。維護時從最終規則目標開始往下追蹤，直到具體節點或內建目標，確認每條分支都能終止。群組層級不宜太深，因為介面顯示的第一層選項往往不足以說明連線最終的去向。

用戶端可能會保存手動選擇，並在重新啟動或更新後還原，因此清單第一個項目不一定是目前的出口。profile.store-selected 等持久化功能也會影響還原行為；不同用戶端可能透過自己的狀態檔案保存選擇。判斷群組是否正常運作時，應同時查看群組目前選項與連線記錄中的完整路徑，不要只依據 YAML 順序。修改群組名稱後，舊選擇可能不再對應，務必重新確認。

節點集合為空時，自動群組無法憑空產生可用出口。使用篩選條件後，應確認仍有候選節點，尤其要留意上游變更命名慣例時的影響。手動群組是否保留直連選項，應依服務需求決定：必須固定使用代理出口的服務，不應把直連當成未經確認的備援路徑。測試規則、檢查策略與驗證服務應分開進行，才能釐清問題究竟是候選清單為空、探測失敗、選擇還原異常，還是遠端服務限制存取。

規則語法與比對順序

第一條符合條件的規則決定處理目標

rules 是有順序的清單。核心由上往下檢查規則，符合條件後就使用該規則指定的目標，不會繼續尋找更具體的條件。因此，特定網域與例外規則應放在寬泛條件之前，MATCH 則放在最後作為兜底。規則不會自動依照「最長前綴優先」排序，也不會讓「網域規則自然優先於位址規則」；實際優先順序就是檔案中的排列順序。若將寬泛規則提前，後面整段規則可能永遠不會被比對。

多數規則採用「類型、比對內容、目標」的格式。DOMAIN 精確比對網域，DOMAIN-SUFFIX 比對網域本身及其子網域，DOMAIN-KEYWORD 則檢查網域中是否包含指定關鍵字。IP-CIDR 和 IP-CIDR6 比對目標位址網段；GEOIP、GEOSITE 則依賴對應的地理或網站資料。PROCESS-NAME 需要核心具備程序識別能力，不能假設所有平台和入口都支援。

rules:
  - DOMAIN,login.example.com,出口選擇
  - DOMAIN-SUFFIX,example.com,DIRECT
  - DOMAIN-KEYWORD,example,出口選擇
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,::1/128,DIRECT,no-resolve
  - MATCH,出口選擇

此處的登入網域會先符合代理規則，該網域的其他後綴則直連；關鍵字規則只會處理前兩條規則未涵蓋的情況。範例網域僅用來說明規則順序，不代表實際服務的分流建議。網段規則附有 no-resolve，表示不會為了比對該位址規則而主動觸發網域解析；若連線已有目標 IP，仍可依此比對。它不是禁止所有 DNS 請求的開關，也不會讓後續依賴解析的規則失效。

網域、位址與程序資訊不一定同時可用

不同入口提供的資訊各有差異。HTTP 代理請求通常會提供目標主機名稱；有些應用程式只把解析後的 IP 傳給代理，核心便不一定知道原始網域。TUN、fake-ip 對應關係與流量嗅探可以補充情境資訊，但各自都有適用範圍。網域規則未命中時，先從連線資訊確認核心實際取得哪些內容，再決定是否調整解析或嗅探。盲目增加網域規則，無法解決網域資訊根本未進入比對流程的問題。

資料規則與拒絕目標

地理資料規則需要檢查實際載入的資料格式與檔案路徑。GEOSITE 的分類名稱來自資料庫，不是任意標籤；GEOIP 的判斷也會受資料更新與位址歸屬變動影響。不要把位址所在地直接等同於服務擁有者所在地，更不能據此推斷內容一定由某個區域提供。資料庫載入失敗、分類不存在與規則順序錯誤是不同問題，排查方式請參閱GeoIP 與 GeoSite 資料庫更新方式。

REJECT 用來拒絕連線，適合用於明確需要封鎖的比對範圍。將過於寬泛的關鍵字規則指向拒絕目標，可能連帶影響登入、驗證碼或靜態資源；測試時應先縮小範圍並查看符合條件的記錄。規則目標也可以是節點或策略群組，但目標必須確實存在。拼字差異、尾端空格與群組重新命名都可能造成引用錯誤，因此不能只檢查規則前半段的比對條件。

驗證修改時，選定一個明確目標，記錄模式、請求網域、符合的規則及最終出口，然後只修改一處並重新建立連線。瀏覽器連線集區、HTTP/2 重複使用連線，以及應用程式的長連線，可能持續沿用舊連線；重新整理頁面不一定會重新判斷規則。必要時關閉相關連線再測試，但不要把「關閉所有連線」當成日常操作。規則只能處理已進入核心的流量；若連線清單中完全沒有相關請求，應先檢查入口與接管範圍。

DNS、fake-ip 與 TUN 接管

解析器職責與啟動相依關係

dns.enable 用來啟用核心的 DNS 模組，listen 則設定監聽位址。nameserver 是一般解析器清單，default-nameserver 用於引導解析 DNS 伺服器自身的網域，proxy-server-nameserver 則用來解析代理伺服器網域。三者處理的階段不同，不應只因某個位址回應較快就全部替換。尤其當加密 DNS 使用網域位址時，必須先有可用的引導解析路徑，否則啟動時可能形成相依循環。

enhanced-mode: fake-ip 會為網域配置對應位址，後續連線抵達核心時可據此還原網域情境資訊。這不是遠端伺服器的真實位址，也不代表網站架設在該網段。應用程式若繞過核心連線至對應位址，通常無法正常存取，因此 DNS 回應必須搭配流量接管。若遇到區域網路裝置探索、特定裝置協定或需要檢查真實位址的應用程式，可視需要設定 fake-ip-filter；但若排除所有網域，就不應期待仍保有相同的對應效果。

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"
    - "localhost"
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.cloudflare.com/dns-query
  proxy-server-nameserver:
    - https://dns.cloudflare.com/dns-query

解析策略不能取代出口規則

nameserver-policy 可為指定網域選擇解析器，負責決定從何處取得解析結果，不會直接決定服務連線走哪個出口。fallback 與 fallback-filter 用於備援解析及結果篩選，也不能簡單理解成「第一個解析器失敗後才依序詢問第二個」。實際行為取決於篩選條件，設定前應先確認預期取得的結果。解析路徑、DNS 連線出口與目標服務出口彼此相關，但仍是不同問題，不能只看一筆解析結果就下結論。

加密 DNS 保護的是用戶端與解析器之間的傳輸，不能只憑使用 HTTPS 位址就判定沒有 DNS 洩漏。作業系統、瀏覽器與應用程式可能各自使用不同解析器；瀏覽器內建的加密 DNS 請求也可能以一般 HTTPS 連線通過網路，而不經過核心的監聽連接埠。應確認請求由誰發出、是否進入核心，以及最終採用哪項策略。欄位用途可參閱nameserver、fallback 與 fake-ip 說明。

TUN 路由、權限與接管範圍

TUN 透過虛擬網路介面接收流量，適合用於不讀取系統代理設定的應用程式。它通常需要管理員權限或相應的系統能力，也仰賴路由設定、裝置介面與核心網路堆疊支援。啟用後不代表所有網路活動都會被接管；虛擬機器、容器、其他 VPN，以及綁定特定介面的應用程式，都可能使用不同路徑。不要同時啟動多套自動路由工具碰運氣；應先保留一套設定，確認介面與路由已成功建立。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

dns-hijack 會將接管範圍內符合條件的傳統 DNS 請求交給核心 DNS 模組，不會辨識並解密所有加密 DNS 流量。上述片段必須搭配已啟用的 dns 使用，實際支援情況也會受到平台、路由與防火牆影響。auto-detect-interface 會嘗試選擇對外介面，但在多網卡、網路切換或存在其他隧道時，仍須確認選擇結果。若預設出口不正確，節點連線也可能再次被送回虛擬介面，形成異常路徑。

變更 fake-ip 模式、對應範圍或 DNS 接管方式後，應用程式與系統快取可能仍保留舊結果。請重新建立測試連線，必要時清除相關快取，並確認核心對應資料沒有因重新啟動而遺失。若只有部分應用程式失敗、區域網路網域異常，或裝置從休眠恢復後斷網，應分別比較解析路徑與路由變化，而不是永久停用 DNS 模組。可依DNS 洩漏檢測與修復中的方式重新測試，並保留修改前後的設定以便還原。

節點訂閱與規則提供者

遠端資源的宣告與實際引用

proxy-providers 將節點集合從主要設定檔中分離，適合用於會定期更新的上游訂閱。提供者會宣告資源來自 HTTP 或本機檔案、儲存路徑及更新週期；策略群組再透過 use 引入這個集合。若只宣告提供者而沒有群組引用，規則就無法自動選取其中的節點。與訂閱完整設定檔相比，節點提供者更適合保留本機策略與規則，只讓上游更新節點內容，縮小每次更新的影響範圍。

以下 URL 使用範例網域，正式使用前請在本機替換成自己的資源網址。遠端節點檔案通常需要以 proxies 作為頂層欄位，內容則為節點清單，不能直接填入任意網頁、Base64 文字或未轉換的 URI 集合。部分用戶端提供格式轉換功能，但這是用戶端的能力，並非所有核心都能接受任意格式。請先確認回應內容的格式，再決定使用提供者或匯入完整設定檔。

proxy-providers:
  上游節點：
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/upstream.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: 出口選擇
    type: select
    use:
      - 上游節點
    proxies:
      - DIRECT

規則提供者的行為與格式

rule-providers 用來管理規則集合，並透過 RULE-SET 在主要規則清單中引用。behavior 描述如何解讀集合：domain 適用於網域集合，ipcidr 適用於位址網段，classical 則可包含不同類型的傳統規則條件。format 描述資源的編碼格式，例如 YAML 或文字。行為與格式是兩個不同面向，不能因為副檔名是 YAML，就推斷內容一定包含完整的傳統規則。

rule-providers:
  本機直連網域：
    type: file
    behavior: domain
    format: yaml
    path: ./rules/direct.yaml

rules:
  - RULE-SET,本機直連網域,DIRECT
  - MATCH,出口選擇

對應的 rules/direct.yaml 可以採用以下結構。網域集合中的 +.example.com 表示比對該網域及其子網域的集合，不應直接照抄成主要規則清單中的完整規則。傳統規則集合通常只寫比對條件，不附加目標；由引用它的 RULE-SET 決定出口。混用兩種語法可能導致載入失敗，或實際比對範圍與預期不符。

# rules/direct.yaml
payload:
  - "+.example.com"
  - "localhost"

更新週期、快取與存取路徑

資源更新週期與健康檢查週期彼此獨立。前者會下載新的節點或規則內容，後者則檢查現有候選項是否可用。修改週期不代表更新已立即完成，仍須查看資源時間、記錄與目前集合。下載請求也需要初始網路路徑；若資源只能透過代理取得，而代理節點又只存在於尚未下載的同一份資源中，就會形成啟動困境。應保留可用快取或明確設定初次取得資源的方法，不要只是不斷重新啟動。

path 應設在允許寫入的工作目錄中，並為不同提供者指定不同檔案。多個提供者共用快取路徑會互相覆寫；從桌面環境移轉至服務環境時，工作目錄改變也可能導致找不到檔案。資源失效後是否繼續使用舊快取，應以目前用戶端與核心的記錄為準，不能假設更新失敗時一定會安全保留上一份。重要規則應備有可還原的副本，避免遠端資源暫時無法使用就影響整體載入。

訂閱 URL 通常包含帳戶識別資訊，完整網址應視同個人存取憑證處理。分享設定時，請一併遮蔽 URL、驗證標頭與節點驗證欄位；不要將含參數的網址放進公開截圖或支援案件。若更新結果是 HTML 頁面，先檢查是否轉向登入頁、網址是否過期及回應狀態，不要把頁面內容當成 YAML 錯誤逐字修改。確認上游格式正確後，再檢查本機提供者欄位、引用名稱與快取路徑，才不會在錯誤的層級反覆修改。

覆寫合併與生效驗證

確認由誰產生最終檔案

覆寫是用戶端在來源設定與執行設定之間進行的處理，不是所有用戶端都通用的核心語法。常見流程是讀取訂閱、套用通用設定、執行覆寫或指令碼，再產生執行檔案；實際處理順序須在目前使用的用戶端中確認。override.yaml 不會因為放在目錄中就自動生效，必須由用戶端明確載入。更新後修改內容消失時，請先檢查編輯入口與處理順序，不要反覆修改自動產生的檔案。

純量覆蓋、映射遞迴合併與清單拼接是三種不同操作。將 mode 從全域改為規則，通常屬於純量替換；只修改 dns.nameserver 時是否保留其他 DNS 欄位，取決於是否採用深層合併；修改 rules 則可能替換整份清單，也可能在前後追加。用戶端將功能稱為「合併」，不代表這三類資料都採用相同演算法。應先用小片段測試結果，再擴大修改範圍。

# 僅供用戶端覆寫輸入；請在用戶端確認合併行為
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip

profile:
  store-selected: true

清單操作必須保留完整語意

將規則插入前方與追加到末尾，效果並不相同。例外規則若加在 MATCH 後面就不會命中；將新的兜底規則插到前方，又會遮蔽原有清單。策略群組也不能只憑名稱推斷合併方式：新增同名物件可能造成衝突，取代物件則可能遺失原有的提供者引用。設計覆寫時，應先明確寫出預期變更，例如「只在最後的兜底規則前插入區域網路例外」，再確認用戶端是否支援該操作，而不是先拼出一份看似相似的 YAML。

若用戶端提供指令碼覆寫功能，應在本機保存指令碼與修改說明，避免直接執行來源不明的處理邏輯。指令碼可能讀取或變更整份設定，影響範圍比一般欄位覆蓋更大。較穩妥的做法是只處理必要欄位，妥善處理物件不存在或清單為空等情況，並在修改後保留其他欄位。移轉至其他用戶端時，優先移轉預期結果與資料檔案，不要假設原用戶端的指令碼介面、變數名稱與合併順序都能原樣沿用。

從靜態檢查到執行路徑驗證

獨立核心可使用設定測試指令檢查結構與引用。以下指令會以目前目錄為工作目錄，讀取 config.yaml；執行檔名稱與目錄應依實際安裝位置調整。桌面用戶端通常內建檢查或記錄入口，不必另外啟動第二個核心，以免占用監聽連接埠。測試成功只代表檢查階段通過，無法驗證帳戶是否有效、遠端服務狀態、系統代理、TUN 權限，或所有應用程式的實際流量路徑。

mihomo -t -d . -f ./config.yaml

修改前先保存可用設定，套用後檢查執行檔案中的重要欄位，不要只確認來源檔案已儲存。接著建立新的測試連線，依序確認入口、模式、符合的規則、策略群組路徑與出口。DNS 相關修改也應核對解析結果及是否使用快取。分別記錄這些檢查點，才能判斷錯誤出在載入、資源或服務存取階段；即使最後都顯示「無法上網」，修正方向也可能完全不同。

還原設定時也要考量目前的執行狀態。恢復舊檔案後，還須確認目前模式、手動群組選擇、DNS 快取與 TUN 路由沒有保留新狀態。一次只調整一類行為，並留下簡短的變更記錄，比同時替換節點、DNS 與規則更容易找出問題。初次部署可返回快速入門教學，依照主要流程逐步驗證；特定問題則可查閱常見問題。本手冊旨在說明欄位之間的關係，不是提供適用於所有網路環境的固定參數組合。