Clash 設定完整指南

一、YAML 結構與設定依賴

設定檔首先是一份 YAML 文件，其次才是 Clash 能辨識的網路設定。剖析器必須先正確讀取階層、清單與資料型別，核心才能進一步檢查欄位。檔案能在編輯器中開啟，不代表結構正確；中文說明通常可以寫在註解中，但用來分隔鍵和值的冒號、引號，以及清單項目前的連字號，都應使用半形字元。建議將檔案儲存為 UTF-8，並讓編輯器顯示空白字元，避免看似對齊、實際卻混入定位字元。

根欄位、對應表與清單

同一層級的鍵應對齊在同一欄。dns 是對應表，子欄位需縮排在下方；proxies、proxy-groups 和 rules 通常是清單，每個項目以連字號開頭。以下設定可作為本機結構驗證的起點：只監聽回送位址，策略組只有直連選項，所有流量最後都會直連。此範例用來說明引用關係，不含可連線的遠端代理。

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

dns:
  enable: false

proxies: []

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

rules:
  - MATCH,Proxy

這裡的 Proxy 不是保留關鍵字，而是策略組名稱。最後一條規則會引用它，因此名稱必須完全一致，包含大小寫、空格與標點符號。DIRECT 則是內建策略，代表直接連線至目標。閱讀設定時，可以先沿著引用關係反向追查：規則指向哪個組、組內列出哪些節點，以及節點是否確實有定義；其中任何一環缺漏，都可能導致載入錯誤或實際連線路徑與預期不同。

縮排正確，還要檢查資料型別

統一使用兩個空格是方便閱讀的慣例；YAML 的關鍵要求是同一層級縮排一致，而不是每個位置都只能縮排兩格。連接埠應寫成整數，開關使用 true 或 false，名稱和密碼則視為字串。密碼含冒號、井字號或特殊字元時，請加上引號；雙引號中的反斜線具有跳脫作用，單引號適合保留大多數一般字元，而單引號本身則須重複書寫才能表示。

註解須從符合 YAML 語法的井字號位置開始，避免將密碼的一部分誤認為說明。同一個對應表中不要重複定義 dns 或 rules；即使某些剖析器接受重複鍵，也可能只保留後者。空清單 [] 和空對應表 {} 用途不同，前者表示沒有項目，後者表示沒有鍵值；欄位應使用哪種結構，請以其定義為準。

區分原始設定與執行設定

圖形介面用戶端經常會整合訂閱、全域設定與覆寫片段，產生一份執行設定。因此，訂閱檔中的 mixed-port 不一定是目前的監聽連接埠，直接編輯下載快取也未必能永久保留修改。開始修改前，先確認三個位置：訂閱原始內容、用戶端持久保存的自訂設定，以及核心目前讀取的檔案。路徑依用戶端而異，請從設定詳情、執行資訊或記錄確認，不要猜測其他用戶端的資料夾位置。

維護時建議一次只調整一個主題：先設定監聽欄位，再處理 DNS，最後修改規則。每完成一類修改就驗證一次，發生錯誤時才容易從有限的差異找出原因。若想進一步了解各區段的閱讀順序，可參閱config.yaml 逐段解析；本頁後續章節則分別說明各欄位的適用範圍，不必依固定順序一次啟用所有功能。

二、連接埠、模式與存取範圍

通用欄位決定用戶端在哪裡接收連線、如何處理連線，以及要向哪些裝置開放入口。排查時，應將「應用程式是否把請求送進核心」與「核心如何選擇出口」分開檢查。啟用規則模式只會影響已進入核心的請求，不會自動讓所有應用程式使用代理；系統代理、應用程式內的代理設定與 TUN 是不同的接入方式，不能只靠 mode 欄位互相取代。

各連接埠欄位的用途

一般桌面使用只設定一個 mixed-port 就夠清楚，不必為了「完整」而同時啟用所有監聽。不同入口不能在同一個位址上使用相同連接埠；若該連接埠已被其他程序占用，核心可能無法啟動監聽。修改連接埠後，也要同步更新系統代理、瀏覽器擴充功能、終端機環境變數與應用程式內的設定，否則應用程式仍會連到舊位址，看起來就像節點無法使用。

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"

三種模式改變的是出口決策

rule 依規則清單順序決定目標；global 使用全域策略處理已接入的流量；direct 則讓已接入的流量直接連線。全域模式不等於系統層級接管，直連模式也不代表應用程式會繞過本機核心。用戶端可能會將模式保存在自己的設定中；切換後查看最終設定或管理介面，才能確認目前生效的值。如需對照實際使用情境，請參閱規則、全域與直連模式的差異。

log-level 常見值包括 debug、info、warning、error 和 silent。日常使用可維持資訊層級；重現問題時再短暫提高詳細程度，記錄完成後記得恢復。詳細記錄可能包含存取網域與連線資訊，分享截圖或文字前，請移除訂閱網址、驗證資訊，以及不希望公開的目標。

區域網路存取需要另外規劃

若要讓手機或另一台電腦透過本機代理上網，只將 allow-lan 設為 true 通常還不夠；也要確認監聽位址涵蓋區域網路介面、系統防火牆允許傳入連線，而且連線裝置填入的是代理主機的區域網路位址。行動裝置若填入自己的 127.0.0.1，只會連到自身，不會找到電腦。在公共或共用網路上應謹慎開放監聽；必要時為代理入口設定驗證並限制來源。

管理介面與代理入口應分開處理。控制器可以讀取狀態並修改部分執行設定，不應直接暴露於公網；確實需要遠端管理時，應搭配驗證、存取控制及受保護的傳輸通道。範例將其繫結至回送位址，僅供本機工具使用。不要將控制器連接埠填入瀏覽器代理設定，也不要因為管理介面能開啟，就認定代理監聽和遠端連線都正常。

也要區分頂層的 ipv6 與 DNS 區段中的同名欄位：前者影響核心使用 IPv6 的行為，後者控制內建 DNS 對 AAAA 查詢的回應方式，兩者不是同一個開關。若網路確實依賴 IPv6，就不能把停用它當成通用最佳化。先確認故障發生於解析、連線或路由階段，再決定是否調整；定位連接埠衝突的具體指令，請參閱排查 7890 衝突與修改 mixed-port 的方法。

三、DNS、Fake-IP 與解析路徑

DNS 設定負責將網域名稱解析為位址，也決定核心如何保留網域與連線之間的關聯。它不等同於代理規則，也不保證應用程式一定會將解析請求交給核心。啟用內建 DNS 後，系統或應用程式仍可能使用原有解析器；透過系統 DNS、TUN 的 DNS 劫持，或由應用程式代理協定傳遞網域名稱，才可能讓相應請求進入這條路徑。檢查前，應先釐清「應用程式、系統解析、核心、上游解析器」之間實際的連線關係。

基本欄位與引導解析

enable 用來啟用內建解析服務，listen 指定監聽位址，nameserver 提供一般上游解析器。使用網域形式的加密 DNS 位址時，可能還要先解析該上游本身的主機名稱；default-nameserver 用於這類引導情境，應選擇目前網路可連線且符合核心要求的位址。以下範例監聽本機非標準連接埠，方便測試，但不會自動變更作業系統的 DNS 設定。

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"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

範例中的上游只是一組易讀的設定示範，是否適合目前網路仍須實測。加密 DNS 可以保護相應解析路徑的傳輸，不代表後續的連線一定會經過代理。標準 DNS 查詢通常使用連接埠 53，範例則使用連接埠 1053；若一般系統設定只允許輸入位址，就不能直接貼上含連接埠的字串，應透過用戶端提供的接管方式或支援的轉發器銜接。

Fake-IP 與 Redir-Host 的差異

fake-ip 會為受處理的網域分配一個合成位址，再由核心將後續連線對應回網域。這能減少部分路徑對預先取得真實位址的依賴，並保留以網域規則判斷的條件。redir-host 則依據真實解析結果處理連線，適合需要真實位址的情境；但實際規則判斷仍會受到接入方式、快取與網域關聯資訊影響，不能簡單地說某種模式永遠比較快。

fake-ip-filter 用來指定不使用合成位址的網域，常見用途包括區域網路名稱或需要取得真實位址的應用程式。新增例外時，應只處理確實發生相容性問題的網域，不要把整份常用網站清單都排除。停用 DNS 合成位址不會自動新增直連規則；即使網域取得真實位址，連線仍可能被規則送往代理組。DNS 例外與出口策略是兩個需要分別檢查的層級。

切換增強模式後，系統、瀏覽器和應用程式可能仍保留舊快取，既有連線也可能繼續沿用先前路徑。驗證時，先結束測試應用程式的相關連線，必要時清除其 DNS 快取，再發出新請求。看到合成位址不代表解析一定出錯；但若用戶端已結束，系統仍快取合成位址，就可能暫時無法連線。此時應恢復正常解析路徑並清除快取。

分域解析與代理端點解析

較複雜的設定可用 nameserver-policy 為指定網域選擇不同上游，也可用 proxy-server-nameserver 單獨解析代理伺服器網域。後者有助於避免啟動時的循環依賴：代理端點尚未解析完成，卻要求先透過該代理連線至解析器。是否需要這些欄位，取決於網路環境與核心支援情況。先讓基本解析正常運作，再逐項加入策略，比一次貼上完整 DNS 範例更容易找出問題。

啟用 respect-rules 後，DNS 上游連線的路由會遵循相應規則；設定時也必須考慮代理端點的獨立解析方式與啟動順序。不要讓遠端解析器、代理組與代理主機名稱彼此依賴，形成必須先完成自身才能啟動的循環。若使用規則集比對 DNS 策略，也要確認相關規則集已成功載入；解析器選擇失敗，可能發生在業務分流之前。

四、代理節點欄位與協定範圍

proxies 用來描述遠端代理端點，每個項目都必須符合相應協定所需欄位。節點名稱是本機引用識別名稱，伺服器位址才是連線目標，連接埠則是遠端服務的監聽連接埠；這些都不能取代本機的 mixed-port。手動設定前，請先向服務提供者取得完整參數；只有伺服器位址和密碼，並不足以確認加密方式、傳輸層及憑證驗證所需資訊。

名稱、類型、位址與驗證資訊

name 應保持唯一且容易辨識，策略組會透過名稱引用節點。type 決定後續欄位的解讀方式，不能直接將一種協定的密碼填入另一種協定的範例。server 可以是網域或位址，port 則應為有效的整數連接埠。以下以 Shadowsocks 示範節點對應表結構，位址和密碼均為教學用值；實際使用時，必須一併換成服務端提供的參數。

proxies:
  - name: "範例 SS"
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

cipher 必須與服務端設定一致，不要因為某個名稱看起來較新就自行替換。密碼含空格、井字號或冒號時，應妥善加上引號，避免解析後字串內容改變。udp: true 表示允許該節點使用 UDP 功能，但不保證每個應用程式的 UDP 流量都會接入，也無法讓不支援此功能的遠端服務自動取得支援。實際效果仍取決於接入方式、協定與服務端設定。

TLS 身分與傳輸欄位

使用 TLS 的節點，還須區分實際連線位址與用於憑證驗證的伺服器名稱。部分協定使用 sni，部分則使用 servername，欄位名稱並非適用於所有協定。以下以 Trojan 說明兩者的關係：server 決定連線目標，sni 則提供 TLS 交握時預期的主機名稱；兩者是否相同，應依服務端的部署方式判斷，而非從瀏覽器網址推測。

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

skip-cert-verify: false 表示維持憑證驗證。遇到憑證錯誤時，請先檢查系統時間、預期主機名稱、服務端憑證鏈，以及連線是否遭到重新導向，再判斷設定是否有誤。關閉驗證可能掩蓋身分錯誤，不應作為所有 TLS 問題的預設修正方式。使用 WebSocket、gRPC 等傳輸方式時，也要依協定檢查路徑、服務名稱或要求標頭；連接埠能建立連線，不代表這些上層參數也已設定正確。

訂閱節點與外部節點提供器

訂閱可能直接產生 proxies，也可能透過 proxy-providers 提供節點集合。後者是具名資源，通常由策略組的 use 欄位引用，不等同於在 proxies 清單中填入節點名稱。提供器的遠端位址、快取路徑、更新間隔與健康檢查各有用途；成功下載資源不代表節點可連線，前者只表示設定資源取得成功。

使用外部節點時，先確認資源本身是否符合核心接受的結構，再檢查策略組引用的提供器名稱是否正確。有些服務回傳的是供用戶端匯入的完整設定，不能直接當成只含節點的提供器檔案。若用戶端提供訂閱轉換功能，請確認轉換結果沒有遺漏協定或欄位，尤其留意傳輸參數、憑證名稱與專屬選項；不能只因節點數量相近，就認定內容一致。

手動更改名稱會影響所有引用該名稱的策略組。刪除節點前，先在設定中搜尋其名稱；批次取代時，留意相同字串可能也出現在規則或說明文字中。訂閱更新後，節點名稱可能改變，因此固定引用少數節點的自訂組需要定期檢查。發布設定或尋求協助時，請一併遮蔽伺服器資訊、密碼、訂閱網址和可識別帳戶的資料；保留欄位結構與錯誤類型，通常就足以進行初步判斷。

五、策略組類型與引用關係

策略組將出口選擇與規則比對分開處理。規則只需指向一個穩定名稱；更換節點或調整選擇方式時，可在組內處理。proxy-groups 的每個項目都包含名稱、類型與候選來源；候選來源可以是節點、內建策略或其他策略組。名稱是引用契約，不只是介面標籤；更改名稱時必須同步修改規則與上層組，否則原本正確的連線路徑就會中斷。

手動選擇與自動測試

select 由使用者在用戶端介面選擇候選項，適合需要明確控制出口的情境。url-test 依測試結果挑選候選項，fallback 著重依候選順序維持可用出口，load-balance 則依其策略分配連線。這四種不是不同名稱的同義欄位；選用前，先決定要手動固定、比較測試結果、優先切換備援，還是分散連線，再填入相應參數。

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - Auto
      - DIRECT

  - name: Auto
    type: url-test
    proxies:
      - "範例 SS"
      - "範例 Trojan"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

這段設定引用上一章的兩個教學節點，必須搭配實際存在的節點定義使用。此處的 interval 表示測試間隔秒數，tolerance 用來減少候選節點間的小幅差異造成切換；兩者都不是介面顯示的即時測量結果。測試位址應選擇目前環境可連線且回應穩定的目標；測試失敗也可能是該位址受到限制，不代表所有業務連線都無法使用。

測試結果不等於完整的實際使用體驗

健康檢查通常衡量連線至特定 URL 的結果，不能直接代表下載速度、影片播放品質，或所有目標網站都能正常連線。某個出口通過測試，但特定服務仍無法使用，可能與目標限制、協定、地區或遠端網路路徑有關。此時應讓實際業務建立新連線，並查看連線詳情，而不是一再調整測試間隔，也不要把單次測試成功當成所有網路層都正常的證明。

候選項中包含 DIRECT，代表使用者可能手動選擇直連，或因組的運作方式而走直連。如果某項服務必須固定經過代理，就不應在相應組中加入直連作為看似方便的候選。相對地，供本機服務使用的組，則應明確決定是否允許遠端代理。策略組名稱也應反映用途或選擇方式，避免將「自動」、「備援」與「直連」混用相似名稱，造成介面選錯後難以察覺。

提供器引用、組巢狀與循環依賴

透過 use 引用提供器時，填入的是 proxy-providers 下定義的鍵，而非訂閱顯示名稱。若使用篩選條件挑選節點，還要確認結果至少包含一個有效候選；名稱規則改變可能導致篩選結果為空。編輯後先確認組內實際顯示的選項，再判斷規則是否正確，避免規則已命中目標組，組內卻沒有可用節點。

組可以引用另一個組，建立「業務組選擇手動組或自動組」的分層架構，但依賴關係最終必須指向節點或內建策略。甲組引用乙組、乙組再引用甲組，就形成循環；更改組名無法解決問題。複雜設定可簡單整理成一條路徑：業務規則、業務組、出口組、節點。層級越多，就越需要檢查每一層目前的選項；介面上看到的第一層選擇，不一定等於實際出口。

用戶端通常會記住手動選擇，但記憶狀態可能來自執行資料，而非 YAML 的預設排序。重新載入設定後是否保留選擇，取決於用戶端與核心的儲存機制；單純將節點移到清單第一項，不一定會改變已儲存的選項。除錯時請明確查看目前選取值，必要時手動重新選擇，再以新連線驗證，不要只根據檔案順序推測執行狀態。

六、規則語法、順序與兜底

rules 是有順序的決策清單，不是沒有先後的標籤集合。核心會由上而下檢查目前連線可用的資訊，符合一條規則後就採用其策略，不會繼續尋找「更精確」的後續規則。因此，優先順序首先取決於規則的位置。排查分流結果時，除了查看規則內容，也要留意前面是否已有範圍更廣的網域、位址或兜底規則，尤其要檢查訂閱產生的規則與自訂規則合併後的順序。

常見規則類型與比對範圍

網域規則應填寫主機名稱，不要加上 https://、路徑或查詢參數。想讓特定網站走代理時，不能直接將瀏覽器網址列中的完整 URL 貼入 DOMAIN。同一個頁面也可能向多個網域發出請求，只涵蓋首頁主機，未必能處理靜態資源、驗證與 API；請根據連線記錄確認真正需要處理的主機，再選擇精確比對或網域後綴比對。

rules:
  - DOMAIN,router.home.arpa,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN-KEYWORD,github,Proxy
  - DOMAIN-SUFFIX,googleapis.com,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

位址規則與 no-resolve

no-resolve 用於相應的位址類規則，表示不為了判斷該規則而額外進行網域解析，並非關閉整套 DNS。若連線目標本身就是位址，核心仍可進行位址比對；若只有網域名稱，且沒有可用於判斷的位址，規則就可能無法命中。是否加入此參數，應依照是否希望該規則觸發解析來決定，不能將它當成每條規則都該加上的效能開關。

GEOIP 依據位址歸屬資料庫判斷，並非根據公司所屬地或使用者所在區域。網域使用境外服務商的位址，或本地服務採用公用網路，都可能讓直覺與實際比對結果不同。資料庫更新也可能改變結果；因此，對必須固定處理的服務，應在範圍較廣的地區規則之前加入更明確的網域例外。資料檔是否可用，也須從核心記錄確認。

規則集、程序比對與適用範圍

RULE-SET 可將一組規則抽出，存放在 rule-providers 管理的資源中，方便更新與重複使用。提供器的行為類型必須與檔案內容一致：網域集合、位址集合與傳統規則集合不能任意混用。宣告遠端規則集不代表已成功下載；初次啟動、網路受限或快取路徑錯誤時，都應先檢查載入記錄，再分析引用該規則集的規則是否能執行。

程序規則是否可用，取決於作業系統與接入方式能否提供程序資訊。在路由器上接收其他終端的連線，通常無法因此得知遠端終端內部的應用程式名稱；程序名稱比對也不是所有平台都具備的固定功能。使用這類規則前，請先確認目前用戶端的支援範圍。若是一般網站分流，明確的網域規則通常較容易重現，也方便在不同裝置間共用設定。

最後的 MATCH,Proxy 表示其餘流量交由代理組處理；改為 MATCH,DIRECT 則表示其餘流量直接連線，兩者代表不同的預設策略。請依實際需求選擇，不要照抄範例。若將這條規則放在清單開頭，後續規則便不會生效。修改後，請關閉測試應用程式的舊連線，或另發新請求；既有連線通常不會因重新載入規則而自動切換出口。

規則命中只代表已決定目標策略，不代表出口連線成功。若記錄顯示命中 Proxy 後仍發生交握錯誤，請接著檢查策略組的實際選擇與節點參數，而不是重複新增相同規則。反過來說，若完全看不到請求記錄，就應回到接入層檢查系統代理或 TUN，避免在尚未進入核心的流量上反覆修改規則。

七、訂閱覆寫與設定合併

訂閱檔負責遠端更新，自訂設定則保存本機偏好；兩者直接混在一起，容易在下次更新時發生衝突。覆寫的目的，是將連接埠、DNS、業務規則或自訂組保存在穩定的位置，再由用戶端產生最終設定。請先確認目前用戶端提供的是完整取代、欄位合併、規則前置，還是指令碼處理。不同功能名稱可能相似，實際合併方式卻不相同，不能直接套用其他用戶端的操作步驟。

分別處理純量、對應表與清單

連接埠和模式這類純量通常只有一個最終值，後執行的覆寫可能取代原值。DNS 是巢狀對應表，有些工具會遞迴合併，有些則會整段取代；規則和策略組屬於清單，常見處理方式包括全部取代、移至前方或附加在後。YAML 只描述資料本身，不會替用戶端決定這些語意。因此，以下範例只是預計寫入的欄位片段，不保證能在每個用戶端達成相同效果。

mixed-port: 7890
mode: rule

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

rules:
  - DOMAIN,router.home.arpa,DIRECT

若工具將 rules 視為整體取代，上例會讓訂閱中的原有規則全部消失；若工具將規則附加在既有 MATCH 後方，新規則也可能永遠無法命中。正確做法是使用該用戶端明確支援的規則前置功能，或透過可控指令碼調整清單順序，並檢查產生的結果。不要只因覆寫編輯器顯示「儲存成功」，就認定規則已在正確位置生效。

合併後仍須確保引用完整

新增業務組時，必須確認它引用的節點或提供器在訂閱更新後仍然存在；新增規則時，也要確認目標策略名稱沒有在合併過程中遭到刪除或改名。若訂閱本身已有名為 Proxy 的組，自訂同名組可能產生衝突或遭到覆蓋。使用能區分本機用途的名稱，並在每次產生設定後檢查名稱是否唯一，比依賴合併工具自動去除重複更可靠。

DNS 覆寫尤其要檢查巢狀欄位。若只想修改 enhanced-mode，卻整段取代 dns，可能同時遺失原有上游、分域策略與代理端點解析設定。反過來說，遞迴合併也可能保留已不再需要的舊欄位。建議先查看合併後完整的 DNS 區段，再確認新舊設定是否構成一致的解析路徑，不要只搜尋剛修改的那一行。

節點提供器與規則提供器也有相同風險。快取路徑衝突可能導致兩個資源互相覆蓋；名稱改變可能讓引用失效；檔案內容格式變更，也可能使原有行為類型不再適用。更新訂閱前請保留一份可用設定，更新後查看載入記錄與組內內容；發生異常時先還原至已知可用狀態，再比對具體差異，避免在失敗的結果上持續疊加修正。

本機維護流程與分享注意事項

建議保留三份資料：遠端訂閱來源、本機自訂片段，以及最終執行設定。前兩者說明設定來源，第三份則顯示實際執行內容。比對時先查看頂層鍵與清單長度，再檢查重要規則的位置、組名與 DNS 路徑。不要把每個遠端節點都複製到自訂檔案，否則訂閱更新時的位址變更與節點增刪就無法生效，維護工作也會轉為手動修改。

覆寫指令碼若能執行程式碼，就應視為具有權限處理設定的程式。只加入自己理解用途的邏輯，不要為了插入一條規則，就接受整段來源不明的處理程式碼。分享範例時，請移除真實訂閱 URL、驗證欄位與個人路徑；即使只是截圖，完整查詢字串也可能包含帳戶資訊。保留教學用值與欄位位置，便於他人重現結構問題，同時避免暴露實際帳戶資料。

八、設定驗證與分層疑難排解

驗證流程應依序涵蓋語法、引用、監聽、解析、規則與遠端連線。依照此順序檢查，能減少無關修改：檔案尚未成功載入時，調整節點選擇沒有意義；請求還沒進入核心時，修改分流規則也不會有作用。開始前記下用戶端名稱、使用的核心、接入方式與剛修改的欄位，不必公開真實訂閱內容。保留最先出現的錯誤；之後大量連線失敗，可能只是同一個基礎問題引發的連鎖反應。

先進行靜態檢查，再查看啟動記錄

獨立執行 mihomo 時，可使用測試參數檢查設定。以下指令假設執行檔位於目前目錄，設定檔則儲存在指定目錄；測試時也可能需要讀取設定引用的外部資源，因此錯誤不一定只是縮排問題。使用圖形介面的用戶端，請優先使用其檢查與重新載入功能，避免同時啟動第二個執行個體而占用連接埠。無論採用哪種方式，都要確認驗證的是準備啟用的同一份檔案。

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

解析錯誤通常會指出行號或附近欄位，但真正原因可能在上一行，例如引號未關閉、清單縮排變更或根欄位重複。引用錯誤則沿著名稱逐一檢查：規則目標是否存在、組的候選項是否存在、提供器名稱是否一致。遇到不支援的欄位時，先確認目前核心是否實作該功能；即使是相同名稱的用戶端，不同平台與安裝來源使用的核心功能也未必完全相同。

確認連接埠與請求是否接入

設定載入後，請確認監聽是否成功。桌面環境中若安裝了多個代理用戶端，即使介面只開啟一個，也可能仍有背景服務占用原連接埠。先找出占用連接埠的程序，再決定關閉舊執行個體或修改新設定；不要直接結束不熟悉的系統程序。接著使用明確指定代理的請求驗證 HTTP 接入路徑，暫時排除系統代理設定是否正確這個變數。

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 -I https://example.com

此指令使用本機混合連接埠，目標只是用來檢查連線路徑的範例網站。若收到 HTTP 回應，代表這次請求經過指定入口，但不表示所有應用程式都已接入。若顯示連線遭拒，優先檢查監聽狀態與連接埠；若代理已收到請求後逾時，再檢查規則、組的選擇與遠端錯誤。目標網站的存取限制也與本機入口無法連線不同，不要將所有非成功狀態都解讀為代理失效。

沿著記錄排查解析與出口問題

判斷解析錯誤時，應確認失敗的是業務目標、代理伺服器，還是 DNS 上游本身的網域。若代理端點無法解析，先檢查引導解析與循環依賴；若只有區域網路名稱解析失敗，再檢查本機解析器、Fake-IP 篩選與接入方式。業務請求已完成解析並命中規則後，應查看實際策略與最終節點，確認流量沒有因多層組選擇而被送往其他出口。

遇到 TLS 錯誤，先檢查時間、主機名稱與憑證鏈；驗證錯誤則先核對密碼與協定欄位；連線逾時時，再檢查位址、連接埠、傳輸參數及網路路徑。不要同時停用憑證驗證、替換 DNS 和切換模式，否則新變數可能掩蓋原本問題。每次只修改一類欄位，並以相同目標的新連線重新測試，結果才有比較意義。舊連線重用、快取與背景重試都可能影響觀察。

還原、記錄與後續維護

確認修正有效後，請記錄最小變更內容：修改了哪些欄位、解決哪類錯誤，以及是否依賴特定網路環境。用戶端或訂閱更新後，優先檢查這些容易遭到覆寫的位置。除錯期間提高的記錄層級、暫時開放的監聽位址與額外測試入口，也應恢復為日常所需設定。設定越複雜，越應保留一份已知可正常使用的基礎版本，方便區分環境變化與新功能引發的問題。

命令列部署與圖形介面的服務管理方式不同，尤其要避免系統服務與桌面程式同時啟動同一個核心；Linux 環境可接著閱讀mihomo 桌面版與 systemd 部署流程。常見情況可從常見問題快速查找；需要更換用戶端時，請前往下載頁面依平台選擇。完成驗證的標準是設定已正確載入、測試請求的路徑清楚可解釋，且日常應用程式行為符合預期，而不只是介面顯示已啟動。