Clash YAML 設定檔參考

SECTION 01 / DOCUMENT MODEL

YAML 結構與設定來源

映射、清單與縮排層級

Clash 設定不是逐行執行的指令碼，而是描述監聽入口、解析方式與轉送決策的結構化文件。頂層欄位決定全域行為，巢狀映射存放同一功能的參數，清單則用來表示有順序的項目。閱讀時先看縮排，再看欄位名稱。冒號後的純量值屬於目前欄位，下一行縮排的欄位則屬於上層映射；以連字號開頭的項目屬於清單，不能任意改成同層映射。

建議統一使用兩個半形空格縮排，不要使用定位字元。同層欄位必須對齊，但縮排深度本身不代表優先順序。例如，dns.enable 必須放在 dns 底下才有預期作用；若將 enable 移到頂層，檔案可能仍可解析，卻不再是設定 DNS。排錯不能只做語法檢查，也要確認欄位位於核心可辨識的位置。

mixed-port: 7890
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
proxies: []
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,PROXY

上例用來說明結構，策略群組只包含直連，沒有提供遠端代理連線。proxies: [] 是空清單，不是字串，也不代表欄位不存在。布林值使用 true 和 false，連接埠通常使用整數。包含井字號、冒號後接空格、星號或其他特殊字元的字串，建議加上引號；密碼即使看起來像數字，也應以字串儲存，避免解析器轉換型別。

Profile、訂閱與執行設定

在用戶端中，Profile 是一筆設定記錄，可連結本機檔案或遠端訂閱。從訂閱下載的 YAML 通常包含代理項目、策略群組與規則，但用戶端也可能加入監聽連接埠、系統整合選項或覆寫結果。核心實際讀取的檔案，是這些輸入經過處理後產生的執行設定。編輯訂閱快取、原始檔案與覆寫內容，影響範圍各不相同。

遠端訂閱更新時，直接修改快取的內容可能被覆蓋。因此，訂閱負責更新的內容與使用者需要長期保留的設定應分開管理。通用連接埠與記錄層級適合由用戶端統一管理，個人規則則適合放在可持續套用的覆寫層。實際合併方式由用戶端決定，不能只憑檔名判斷設定來源。比較差異時，應同時保留原始訂閱與最終輸出，不要只看編輯器目前開啟的分頁。

編輯檔案的基本原則

同一個映射中不要重複定義相同的鍵。兩段 dns 不會可靠地自動合併，不同解析路徑可能會報錯，也可能只保留其中一段。需要新增解析器時，應修改現有清單，而不是在檔案末尾再寫一個同名欄位。規則清單也應只有一個明確來源，避免訂閱與本機修改各自產生頂層 rules。

儲存檔案時請使用 UTF-8，並保留一般半形冒號與連字號。中文標點適合用於說明文字，不適合取代 YAML 結構符號。註解從井字號開始，不會成為執行欄位；但引號內的井字號屬於字串。複製範例後，先檢查空白字元，再確認引用內容；網頁上看起來對齊，不代表編輯器裡的實際空格正確。

設定檔路徑取決於作業系統、安裝方式與用戶端設定，本指南不會將特定使用者目錄當成通用路徑。請從用戶端提供的設定目錄入口或記錄中確認位置。若有多個設定並存，請替 Profile 設定能說明用途的名稱，並記下目前啟用的項目。想了解本機檔案、遠端訂閱與設定切換的關係，請接著閱讀Profile 基礎與多組設定管理。

SECTION 02 / LISTENERS AND MODE

監聽連接埠與執行模式

入口協定與監聽位址

代理連接埠用來接收應用程式交給核心的連線。port 提供 HTTP 代理入口，socks-port 提供 SOCKS 入口，mixed-port 則在同一個連接埠接受 HTTP 與 SOCKS 請求。一般桌面使用通常選擇混合連接埠即可，但要確認用戶端實際寫入的是哪個欄位。若將網站服務位址填入代理連接埠，或把控制介面當成代理入口，都會造成協定不符。

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

這段設定會將代理入口與控制入口限制在本機。若要讓其他裝置使用，必須一併考量監聽位址、allow-lan、系統防火牆與存取控制，不能只修改一個開關。監聽所有網路介面，代表更多介面可以連到該服務。尤其不應將控制介面直接公開至公用網路；若確實需要遠端管理，請設定驗證並限制可存取的網路範圍。

規則、全域與直連模式的差異

mode: rule 依規則清單決定出口，適合希望依網域、位址或規則集合分流的情境。mode: global 會使用全域策略處理進入核心的連線，不代表系統中的所有應用程式都已被接管。mode: direct 會讓進入核心的連線直接連至目標，但仍會經過代理入口的處理流程，並不等於關閉用戶端程式。

模式與系統代理屬於不同層面。模式決定連線進入核心後如何轉送；系統代理則決定遵循系統設定的應用程式是否將請求交給該入口。有些程式使用自己的代理設定，有些則忽略系統代理。若特定應用程式的行為不同，請先檢查代理入口的涵蓋範圍，再檢查規則。瀏覽器能連線，不代表其他程式也走相同路徑。

修改連接埠與程式界線

修改混合連接埠後，應用程式端的代理位址也必須同步更新。用戶端可以管理系統代理設定，但瀏覽器擴充功能、終端機環境變數或開發工具中固定的連接埠不一定會跟著變更。常見情況是用戶端運作正常，但終端機仍連到舊連接埠。請分別檢查 HTTP_PROXY、HTTPS_PROXY 與 ALL_PROXY 的實際值，以及應用程式內個別儲存的代理選項。

連接埠衝突表示指定的本機位址與連接埠組合已被占用，也可能是舊核心程序尚未結束。請先停止重複執行的用戶端，再確認占用來源，不要直接將所有監聽連接埠改成隨機值。若記錄明確指出權限錯誤，請檢查執行權限或系統保留連接埠的狀況。連接埠號碼不代表連線品質好壞，選擇依據應是應用程式設定一致與本機資源可用。

日常使用建議將記錄層級設為 info，需要追蹤比對過程時再短暫切換為 debug。詳細記錄可能包含存取目標，分享前請移除訂閱位址、驗證資訊與個人存取記錄。初次安裝時的連接埠與系統代理檢查，可參考首次安裝與初始設定；不必為了解決本機入口問題而替換整份訂閱。

SECTION 03 / NAME RESOLUTION

DNS 解析與 Fake-IP

解析器欄位的用途

DNS 設定負責將網域轉換成可供連線與規則判斷使用的資訊。dns.enable 用來啟用核心的 DNS 功能，listen 指定接收查詢的本機位址，nameserver 則列出一般上游 DNS。啟用 DNS 不代表系統的所有查詢都會自動交給核心；系統 DNS、應用程式內建的加密解析器與 TUN 劫持設定，都會影響查詢是否經過這條路徑。

default-nameserver 常用來解析 DNS 上游本身的網域，確保依賴關係能夠啟動。例如上游使用 HTTPS 網域位址時，必須先取得該網域的 IP 位址。這不是強制所有查詢優先使用的萬用欄位。另一個容易混淆的欄位是 proxy-server-nameserver，用來解析代理伺服器網域，適合明確分開代理連線所需的解析路徑。

dns:
  enable: true
  listen: 127.0.0.1:1053
  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"
    - localhost

此片段是本機 DNS 服務範例，沒有設定系統流量接管。上游位址應依所在網路的可連線狀況選擇；不能因為位址使用加密傳輸，就認為任何網路都能連線。若修改本機監聽連接埠，作業系統或轉送程式也必須能將查詢送往該連接埠。一般系統 DNS 設定通常只能填寫位址，無法直接指定自訂連接埠。

Fake-IP 與真實位址解析

Fake-IP 模式會替網域配置一個供核心辨識的映射位址，並透過映射保留網域資訊。範例中的位址範圍只供內部映射使用，不是網站實際的出口位址，也不能填作遠端伺服器。這種模式的優點是請求進入核心時，較容易穩定地對應到網域；但應用程式與系統的查詢路徑必須確實經過同一個核心執行個體。

redir-host 模式會回傳真實解析結果，處理流程與 Fake-IP 不同。有些依賴真實位址的本機服務可能較適合使用此模式，但切換模式不是解決 DNS 故障的通用方法。請先確認問題是查詢失敗、映射失效，還是應用程式繞過了核心。切換後也要考量系統與應用程式中既有的 DNS 快取，舊結果可能繼續影響新連線。

fake-ip-filter 可讓指定網域不使用虛擬映射，適合確實有相容性需求的本機網域或服務探索網域。篩選條件過於寬泛會降低網域映射效果，建議先從明確受影響的網域著手，不要一次加入所有常見後綴。篩選規則的實際比對方式應參照目前核心文件確認，避免將一般網域清單誤當成任意格式的規則集合。

解析路徑與分流閉環

若 DNS 請求本身也需要依規則分流，還要檢查上游連線如何送出。respect-rules 會讓 DNS 連線遵循路由規則，但必須明確設定代理伺服器網域的解析方式，否則可能形成「先有代理才能解析、先有解析才能連線代理」的循環依賴。新增這個欄位前，應先理清上游解析、代理交握與目標存取的先後關係。

nameserver-policy 可依網域條件指定解析器。它決定使用哪條解析路徑，不會自動為對應網站建立存取規則。DNS 分流與連線分流是兩個階段：前者選擇解析服務，後者選擇連線出口。網域使用特定解析器，不代表實際連線一定走相同出口。若需要一致的行為，兩處設定都要核對。

排錯時先保留一個可連線的上游，確認基本查詢正常後，再逐項加入策略與篩選條件。若區域網路名稱無法解析，請檢查路由器或本機 DNS 的用途，不要將所有查詢都交給公用上游。若瀏覽器與命令列的結果不同，請分別清除快取並檢查各自的解析選項。DNS 修改應與連接埠、模式調整分開進行，才能清楚對照記錄與行為差異。

SECTION 04 / OUTBOUND DEFINITIONS

代理欄位與遠端提供者

區分通用欄位與協定欄位

proxies 用來描述可供選擇的出口代理。完整項目通常需要名稱、協定類型、伺服器位址與連接埠，再依協定加入密碼、使用者識別資訊或傳輸設定。名稱供內部引用，必須與策略群組中的成員名稱一致；伺服器欄位描述實際連線目標，兩者不能互相取代。為避免教學資訊被誤認為可用服務，本節只展示協定欄位片段，不提供實際連線項目。

type 決定核心使用哪一種協定解析後續參數。不同協定即使共用 server 與 port，驗證欄位也不能混用。有些類型需要密碼，有些需要使用者識別資訊，有些還要求指定加密方式。保留其他協定的欄位，可能會讓欄位遭到忽略，也可能直接導致設定載入失敗。

# 僅展示 Shadowsocks 協定欄位，並非完整代理項目
type: ss
server: proxy.example.com
port: 443
cipher: aes-128-gcm
password: "your-password"
udp: true

範例網域與密碼僅供教學使用。實際使用時，必須採用服務提供者給出的完整且一致的協定參數，不能只依連接埠推測類型。443 只是常見的服務連接埠之一，不代表自動啟用了 TLS。udp: true 表示允許相關功能，實際可用性仍取決於協定、伺服器實作與完整網路路徑，無法保證所有應用程式的 UDP 通訊都能使用。

TLS 與傳輸層參數

對於支援 TLS 的協定，伺服器位址與憑證驗證名稱可以不同。servername 通常用來指定交握時使用的伺服器名稱，應與服務設定及憑證相符。skip-cert-verify 用來控制憑證驗證，不應當成連線失敗時的常規解法。憑證錯誤可能是網域填錯、系統時間異常或伺服器憑證鏈不完整所致；略過驗證只會掩蓋這些問題。

WebSocket、HTTP 等傳輸設定通常放在協定支援的巢狀欄位中。路徑、要求標頭與交握名稱屬於不同層級，不能因為它們看起來都像網域就互相替換。若服務提供者有提供原始 YAML，應優先保留該協定區塊的結構，再確認核心是否支援相關選項。訂閱轉換可能遺漏擴充欄位，因此原始連結可用、轉換後卻無法使用時，應比較兩者的結構差異。

proxy-providers 的用途範圍

proxy-providers 將遠端代理項目作為獨立資源管理，策略群組則透過 use 引用提供者。它與完整 Profile 訂閱不屬於同一層級：完整設定可能還包含 DNS、規則與群組，而代理提供者的內容必須符合指定格式。直接將完整訂閱網址填入提供者欄位，不代表核心就能將其讀取為代理集合。

proxy-providers:
  REMOTE:
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/remote.yaml
    interval: 86400
proxy-groups:
  - name: PROXY
    type: select
    use:
      - REMOTE

此處的 REMOTE 是提供者識別名稱，不是單一代理項目。範例位址不含可用設定，請替換為自己有權存取且格式相容的資源。interval 的單位是秒，表示資源更新間隔，與策略群組的探測間隔用途不同。path 是快取位置，可存取範圍還會受到核心工作目錄與路徑安全限制影響；桌面用戶端也可能會另外管理這些檔案。

提供者下載失敗時，請先確認是 URL 無法連線、驗證失效、伺服器回傳網頁，還是 YAML 內容結構不符要求。若已有快取，可能會繼續保留舊內容，因此介面仍顯示成員不代表更新成功。遠端訂閱 URL 通常包含存取憑證，不要貼在截圖或公開記錄中。格式差異與完整操作流程請參閱訂閱連結匯入與格式說明。

SECTION 05 / POLICY GRAPH

策略群組欄位與引用關係

策略群組不是流量接管入口

proxy-groups 將可用出口整理成可供引用的決策單位。規則目標可以是策略群組，群組內再指向代理、內建動作或其他允許引用的群組。它的用途是決定連線送達後如何選擇下一個節點，不負責讓應用程式開始使用代理。若應用程式的請求沒有進入核心，再完整的群組結構也不會生效。

每個群組都需要唯一且穩定的 name，並以 type 指定選擇方式。select 提供手動選擇，適合需要明確控制目前出口的情境。url-test 依探測結果選擇成員，fallback 依成員順序維持可用出口，load-balance 則依其策略分配連線。不同類型的選擇邏輯，不能只看介面上的顯示順序判斷。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
      - REJECT
rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,DIRECT

這是用來理解引用關係的片段。DIRECT 代表直連，REJECT 代表拒絕；選擇後者會拒絕命中該群組的請求。它們是核心內建目標，不需要再於 proxies 中定義。實際設定可以將已有的有效出口加入群組，但不能將尚未定義的名稱列入清單，再期待核心自動建立。

成員來源與探測設定

proxies 表示明確列出的成員清單，use 則引用代理提供者。明確清單適合固定結構，提供者則適合獨立更新的資源集合。混合使用時，應確認目前核心如何處理群組成員組合，並檢查提供者是否已載入。介面上看得到群組，不代表群組內一定有可選成員；提供者清單為空、篩選條件過嚴或資源讀取失敗，都可能讓群組變成空群組。

自動選擇類型通常需要 url、interval 等探測參數。探測位址應選擇穩定、回應內容小且能透過目標路徑連線的 HTTP 服務；探測結果只反映前往該位址的請求狀況，不能證明所有網站、驗證流程或應用程式協定都可使用。若測試位址遭網路策略封鎖，也可能讓實際可用的成員被判定為無法使用。

tolerance 等參數可用來減少頻繁切換，是否適用取決於群組類型與目前核心。不要為了讓介面看起來變化更快，就把探測間隔設得過短。高頻探測會產生額外請求，也可能讓不穩定網路中的選擇持續波動。調整前先確認需求是自動選擇較佳出口、保留備援，還是分配連線；選對類型比微調參數更重要。

分層設計與循環引用

分層策略群組適合將使用者選擇與規則分類分開。例如，規則可以指向穩定的用途群組，再由該群組引用統一的手動選擇群組。如此一來，遠端資源變動時就不必逐條修改規則。不過層級越深，排錯也越複雜；每一層都應有明確用途，避免多層群組只是在重複轉送。

群組不能形成循環引用。甲群組引用乙群組，乙群組又回頭引用甲群組，會使出口路徑無法終止。大型設定中，即使沒有直接互相引用，也可能透過第三層形成迴圈。檢查時從規則目標開始逐層展開，直到抵達實際代理或內建動作。每條路徑都必須有終點，不應再次遇到已經經過的群組。

對於需要維持登入狀態的服務，分散新連線可能造成出口變更，進而觸發額外驗證。請依應用程式需求選擇穩定路徑，不要把分配連線當成預設最佳化方式。群組選擇變更後，既有連線通常不會自動轉移；只有新連線會採用新的決策結果。驗證修改時，請關閉目標應用程式的舊連線後再測試，並搭配規則命中結果與最終出口路徑觀察，避免誤把舊工作階段判定為設定未生效。

SECTION 06 / FIRST MATCH

規則語法與比對順序

第一條命中規則與預設規則

在規則模式下，核心會由上而下檢查 rules，命中第一條符合條件的規則後，就使用該規則指定的目標，不會繼續比較後面的規則是否更精確。因此優先順序由位置決定，不會自動依規則名稱或網域長度計算。常見的排列方式是將明確例外放在前面、一般分類放在中間，最後才放預設規則。

大多數規則採用以逗號分隔的「類型、條件、目標」格式。MATCH 不需要比對條件，會直接指定其餘連線的處理目標。排在它之前的規則負責處理明確分類；排在它之後的規則通常不會有機會執行。排查某條規則為何無效時，先往前找是否有更早命中的項目，不要重複新增相同規則。

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,github.com,PROXY
  - 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

這段規則要求已有名為 PROXY 的策略群組。區域網路位址範例並未涵蓋所有私人網路範圍，實際部署時請依網路環境補充。GEOIP 需要能取得對應的地理資料，分類結果也不等同服務營運者的所在地。若有明確的業務需求，應優先使用容易理解的網域或位址規則，不要只依賴地理位置推測。

網域規則與位址規則的差異

DOMAIN 比對完整網域，適合單一主機的例外設定。DOMAIN-SUFFIX 比對指定網域及其子網域，適合涵蓋整個服務網域。DOMAIN-KEYWORD 依關鍵字比對，範圍容易超出預期，請謹慎使用。規則條件通常不填協定標頭、URL 路徑或連接埠；將完整網頁網址填入網域條件，無法建立路徑層級的比對。

IP-CIDR 與 IP-CIDR6 依目標位址範圍進行比對。對於原本透過網域發起的請求，部分位址規則可能會觸發 DNS 解析。no-resolve 用來避免該規則主動觸發解析，不代表整個存取流程完全不使用 DNS。若連線原本就有目標 IP，仍可進行位址比對；若只有網域而沒有位址，就可能無法依此命中規則。

同一個網站可能會連線到多個網域，靜態資源、登入與 API 請求不一定共用相同後綴。只替首頁網域設定規則，無法保證整個使用流程都走相同路徑。排錯時應觀察實際失敗的請求，不能只因網頁能開啟就結束驗證。對於直接連線至 IP 的應用程式，網域規則也未必有足夠資訊可用，需依實際連線目標決定策略。

規則提供者與資料格式

rule-providers 管理可獨立更新的規則集合，並透過 RULE-SET 在主要規則清單中引用。提供者負責儲存比對條件，主要規則則負責指定使用位置與目標。即使規則集合已成功下載，若沒有在主要規則中引用，就不會參與比對。若引用位置排在預設規則之後，也無法達到預期效果。

rule-providers:
  LOCAL-DOMAINS:
    type: inline
    behavior: domain
    payload:
      - "+.example.com"
rules:
  - RULE-SET,LOCAL-DOMAINS,DIRECT
  - MATCH,PROXY

範例使用內嵌網域集合，不需依賴外部檔案。behavior: domain 的資料內容表示網域條件，不應直接放入包含策略目標的完整規則列。ipcidr 與 classical 的資料格式語意不同，遠端資源必須與宣告類型相符。修改提供者類型或格式時，也要檢查內容，不能只改欄位名稱。

整理規則時，建議為每條新增的本機規則記錄原因，並定期移除已被上層規則涵蓋的重複項目。不要讓多個覆寫指令碼無序地追加主要規則，否則很難確認最終順序。更完整的類型說明、排序範例與命中分析，請參閱Clash 自訂規則語法與優先順序。本頁後續的覆寫章節會說明如何在訂閱更新後保留個人規則。

SECTION 07 / CONFIGURATION PIPELINE

覆寫、合併與更新界線

區分用戶端處理與核心欄位

覆寫是用戶端在原始設定之外套用修改的處理機制，並不是所有 YAML 檔案都通用的頂層欄位。Clash Nyanpasu 的設定產生流程可能包含用戶端管理項目、設定合併與指令碼處理。不同用戶端的覆寫入口、執行順序與支援語法各不相同，不能直接將某個用戶端的擴充設定當成 mihomo 設定交給核心。

理解覆寫時，應將輸入、轉換與輸出分開看。輸入包括訂閱或本機 Profile；轉換包括欄位覆蓋、清單操作或指令碼修改；輸出才是核心讀取的執行設定。排錯時要確認修改發生在哪一層，並查看最終輸出。覆寫編輯框中有目標欄位，無法證明它沒有在後續步驟被再次覆蓋。

# 僅適用於支援一般欄位合併的覆寫入口
mode: rule
log-level: info
dns:
  enable: true
  enhanced-mode: fake-ip

這段片段表達希望保留的欄位值，但不保證所有用戶端都採用相同的合併演算法。有些實作會遞迴合併映射，有些入口則會取代整個物件。若整個 dns 被取代，原訂閱中的上游清單、篩選項目與策略也可能一併消失。因此套用後必須檢查最終的 dns 物件，而不只是確認 enable 已設為 true。

清單的追加、前置與取代

映射合併與清單合併必須分開理解。監聽連接埠是單一純量，通常可以直接覆蓋；規則與策略群組則是有結構的清單，處理方式可能是整份取代、追加、前置，或由指令碼自行決定。不要假設只寫一份較短的 rules 清單，就會自動保留訂閱中的其他項目。若覆寫入口採用取代語意，原有分類規則可能會全部消失。

規則順序尤其重要。個人例外通常必須放在一般規則之前；若追加到 MATCH 後面，就不會得到預期的比對結果。修改策略群組時，應依唯一名稱定位後再調整成員，不要直接重複新增同名群組。自動更新的設定也應具備冪等性：相同輸入重複執行後，不應不斷新增重複規則或成員。

明確分配訂閱更新與個人設定

適合交由訂閱管理的內容，包括服務提供者維護的代理參數與資源集合；適合在本機管理的內容，則包括本機連接埠、記錄偏好與明確的個人存取規則。分工不代表所有本機值都要覆蓋訂閱：若用過時的覆寫固定服務提供者給的協定參數，更新後可能造成驗證或傳輸不相容。因此覆寫只應處理必要差異。

指令碼修改比一般欄位合併更有彈性，也更需要檢查界線。處理前先確認目標陣列存在，找到預期群組後再修改；若找不到群組，不要悄悄建立不完整的物件。遠端設定更新時，群組名稱變更是常見風險。指令碼應回報容易理解的錯誤或安全略過，而不是產生無法載入的執行設定。執行順序變更後，也要重新確認引用關係。

修改前請保留一份可正常使用的 Profile 與覆寫備份，也不要將包含訂閱憑證的檔案提交到公開程式碼儲存庫。備份應涵蓋設定來源、個人規則與必要的用戶端設定；只複製暫時產生的執行檔案，未必能還原原本的更新關係。記錄此次修改目標，例如只調整 DNS 或只將一條規則前置，有助於大幅縮小回復範圍。

套用覆寫後分三層驗證：先確認 YAML 可解析，再確認群組與提供者引用完整，最後使用新連線驗證實際行為。若更新後突然失效，先比較資源變化與覆寫目標是否仍存在，不要立即刪除所有個人設定。逐一停用處理步驟來定位衝突，比同時替換訂閱、核心與用戶端更容易保留有效資訊。設定來源的基本概念可回顧Profile 管理說明。

SECTION 08 / VALIDATE AND ISOLATE

設定驗證與故障排查

先驗證輸出，再檢查流量

設定需要通過語法、語意與執行行為三個層面的檢查。語法檢查會處理縮排、引號與清單結構；語意檢查會處理欄位支援、策略引用與資源格式；執行檢查則會確認連接埠、網路可達性與實際比對結果。通過其中一層，不代表下一層也沒問題。尤其是遠端資源尚未載入、系統代理尚未接管時，檔案成功讀取不代表應用程式已能正常使用。

可直接使用 mihomo 的使用者，可以用測試參數檢查指定檔案。請使用用戶端實際執行的核心，並在相同工作目錄或明確指定的資料目錄下測試，才能正確找到相對路徑資源。若桌面用戶端已提供測試或查看執行設定的入口，請優先使用，避免另行啟動程序並與現有監聽服務衝突。

# 請在設定檔所在目錄執行，並依實際執行檔位置調整命令
mihomo -t -f ./config.yaml

# Windows PowerShell，且目前目錄中已有對應的執行檔時
.\mihomo.exe -t -f .\config.yaml

測試輸出中的行號通常指出解析失敗的位置，但實際原因可能在前一行，例如引號未關閉或縮排錯誤。先處理第一個明確錯誤再重新測試，避免在多個由同一問題引起的提示之間反覆修改。若提示不支援某欄位，請確認核心類型與目前選項的支援狀況，不要把欄位移到其他層級碰運氣。

沿著連線路徑逐步縮小問題範圍

第一步，確認用戶端與核心已正常啟動，記錄中沒有監聽失敗。第二步，確認應用程式連線到正確的代理位址，必要時使用明確指定的代理進行測試。第三步，檢查 DNS 是否依預期路徑解析目標。第四步，查看規則與策略群組的最終決策。第五步，再檢查遠端協定交握與伺服器回應。依照這個順序排查，可以區分本機設定問題與遠端連線問題。

# 僅驗證本機 HTTP 代理入口及後續請求路徑
curl --proxy http://127.0.0.1:7890 --head https://example.com

# SOCKS 測試由代理端解析目標網域
curl --proxy socks5h://127.0.0.1:7890 --head https://example.com

執行命令需要先安裝 curl，且連接埠必須與執行設定一致。測試網站只用來觀察請求路徑；命令失敗時應根據具體錯誤判斷，不能直接認定整份設定無效。連線遭拒時，通常先檢查本機監聽；名稱解析失敗時，先檢查 DNS；代理交握錯誤則接著檢查協定入口與驗證資訊。不同錯誤發生在不同階段，處理方式也不應相同。

作業系統差異與最小化回復

Windows 的系統代理與防火牆設定、macOS 的服務權限，以及 Linux 桌面環境的代理設定，都會影響流量接管範圍，但不會改變 YAML 的基本層級。遇到系統提示時，應依提示檢查安裝與權限，不要到規則清單中尋找解法。macOS 相關設定路徑可參考安裝授權與鑰匙圈提示處理；是否需要特定權限，請以目前的安裝方式為準。

最小化回復不是刪除所有設定，而是撤銷最近一項修改並保留故障線索。先停用新加入的覆寫，再還原單一欄位，最後才考慮切換至備份 Profile。每次只變更一個條件，並以新建連線重複相同測試。若同時更新用戶端、核心與訂閱，就很難判斷哪個步驟改變了結果，也不容易重現問題。

分享排錯資訊時，請保留錯誤文字、欄位層級與操作順序，並移除訂閱 URL、密碼、驗證參數及個人存取目標。截圖不能取代可讀的錯誤資訊，但也不應直接公開完整設定。完成排錯後，請恢復一般記錄層級、刪除臨時測試規則，並記下最後有效的修改。日常查閱可透過術語指南確認欄位概念；需要重新完成匯入與驗證時，請返回快速入門教學，避免將系統參考步驟與初次使用流程混為一談。