Clash Meta 設定檔怎麼寫？從最小 YAML 到匯入排錯
簡答：Clash Meta 設定檔是供 mihomo 用戶端讀取的 YAML。先用最小範本校驗，再按節點、策略組、規則逐段加入；匯入失敗時優先檢查縮排、端口、引用名稱與回應格式。
定義：Clash Meta 設定檔是由 mihomo 相容用戶端讀取的 YAML 檔案，用來定義代理端口、節點、策略組、DNS 與分流規則。
先試這一步：用最小 YAML 確認設定檔能否解析
如果你剛拿到一份 YAML，先不要立即加入 DNS、TUN 或大量規則。將以下內容另存為 config.yaml，使用 UTF-8 編碼並以空格縮排，不要使用 Tab。這份範本只用來驗證基本結構，不含真實節點，也不能提供實際代理連線。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- MATCH,PROXY
這裡直接引用 mihomo 的內建 DIRECT，沒有把它另寫成自訂的 direct 節點，可避免不同用戶端對保留名稱或自訂節點的相容性差異。mixed-port可同時接收 HTTP(S) 與 SOCKS5 請求；mode: rule代表按規則匹配；rules由上至下處理，最後的 MATCH作為兜底規則。欄位定義可參考 mihomo 代理端口文件、一般設定文件和 路由規則文件。
| 步驟 | 先做什麼 | 可觀察結果 |
|---|---|---|
| 1. 建檔 | 儲存為 UTF-8 的 config.yaml，只用空格縮排 | 檔案副檔名和層級正確 |
| 2. 校驗 | 用用戶端的檢查功能，或用目前 mihomo 執行檔的幫助資訊核對命令 | 沒有 YAML 解析錯誤 |
| 3. 匯入 | 加入本機 Profile 或遠端 URL | Profile 出現在清單中 |
| 4. 啟用 | 選中 Profile，再啟動服務或系統代理 | 日誌開始出現啟動與連線訊息 |
先分清：Clash Meta、mihomo、設定檔、訂閱與用戶端
「Clash Meta 設定檔」常被用來泛指 mihomo 可讀取的 YAML，但實際上涉及不同層次：用戶端提供介面，mihomo 負責解析和執行，設定檔定義運行參數，訂閱則通常是遠端網址或節點集合。設定檔不是安裝包，也不等於單獨的一條節點資訊。欄位和支援範圍應以 mihomo 設定文件總覽為準。
| 對象 | 主要作用 | 常見形式 | 能否單獨使用 |
|---|---|---|---|
| 用戶端 | 提供匯入、啟用、日誌和代理選擇介面 | 桌面或 Android 應用程式 | 通常需要一份設定 |
| mihomo | 解析 YAML，執行代理、DNS、規則和 TUN | 核心或核心程式 | 需要設定檔或啟動參數 |
| 設定檔 | 定義端口、節點、策略組與規則 | YAML 檔案 | 可本機匯入，但可能沒有節點 |
| 訂閱 | 遠端提供節點或完整設定內容 | HTTPS 網址 | 需要用戶端或 provider 更新 |
設定檔的依賴關係可以簡化為：proxies提供節點，proxy-groups引用節點或其他策略組，rules再把要求導向策略組或 DIRECT。如果策略組引用了不存在的名稱，規則即使語法正確，也可能在啟用時失敗。mihomo 對節點名稱要求唯一，相關欄位可核對 代理節點文件和 策略組文件。
本機 YAML、遠端訂閱與 proxy-providers 怎麼選
| 方式 | 適合情況 | 更新風險 | 建議做法 |
|---|---|---|---|
| 本機 YAML | 測試端口、規則、DNS 或手動維護節點 | 不會自動被遠端內容覆蓋 | 修改前備份，先從最小設定開始 |
| 遠端訂閱 | 節點由服務端維護 | 更新可能覆蓋本機直接修改 | 匯入前確認來源、格式和權限 |
| proxy-providers | 想把節點來源與主設定分開 | provider 內容會按間隔更新 | 主設定保留策略組與規則 |
| 設定覆寫 | 想統一修改載入節點的部分欄位 | 不同欄位支援範圍可能隨版本變化 | 以目前 mihomo 文件的 override 欄位為準 |
HTTP provider 的最小結構如下，example.invalid只是佔位地址，不代表可用服務：
proxy-providers:
my-provider:
type: http
url: https://example.invalid/subscription
path: ./proxy-providers/my-provider.yaml
interval: 3600
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 300
type: http需要搭配 url；path指定本機儲存位置；interval以秒為單位；健康檢查則由 health-check區塊控制。provider 的欄位、路徑限制與 override 支援範圍，請以 mihomo proxy-providers 文件為準。
如果你希望加入一個可直接修改的節點，完整結構至少要包含唯一的名稱、類型、伺服器和端口。不同節點協議需要不同欄位，不能把下例中的協議和參數當成通用格式：
proxies:
- name: "example-node"
type: ss
server: server.example
port: 443
cipher: chacha20-ietf-poly1305
password: "replace-with-your-password"
proxy-groups:
- name: PROXY
type: select
proxies:
- "example-node"
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- MATCH,PROXY
上例中的伺服器、端口、密碼和協議參數都需要替換成你已核實的節點資料；它不是可直接連線的服務。節點名稱必須唯一，策略組中的名稱也要逐字一致，包括大小寫、空格和標點。
Windows、Android 與其他用戶端的匯入步驟
Windows 桌面端：以 Clash Verge Rev 的 Profile 介面為例
- 開啟用戶端的 Profiles 或設定檔頁面。
- 選擇 Import；遠端設定貼入 Profile URL，本機設定選擇 Local，再讀取 YAML 檔案。
- 匯入後先查看內容或執行校驗，再選擇該 Profile 作為目前設定。
- 若啟用後無法連線，先檢查
mixed-port是否被其他軟體佔用，再查看日誌。
Clash Verge Rev 的介面資源包含 Profiles、Import、Profile URL、Remote、Local 和「只支援 YAML 檔案」等文字；中文介面、選單位置和實際名稱可能隨版本變化，應以目前安裝版本畫面為準。可參考其 Profile 介面資源。
Android：從檔案或 URL 加入 Profile
- 開啟 Android 用戶端的設定或 Profile 管理頁面。
- 本機方式選擇 YAML；遠端方式貼上訂閱 URL，確認網址沒有被截斷。
- 匯入後先選中該 Profile，再啟動服務；下載完成不代表它已成為目前設定。
- 如需使用系統 URI 匯入，官方 Android 專案記錄了
clash://install-config?url=和clashmeta://install-config?url=，其中 URL 參數需要編碼。對應的 scheme 和 host 也可在 AndroidManifest核對。
ClashX 或其他用戶端：不要照抄固定菜單名稱
不同用戶端可能使用 Profile、設定檔、配置、Import、Add 或 URL 等不同名稱；目前無法僅依據 mihomo 文件核實每一個用戶端的固定選單路徑。可按照「新增設定檔→選本機 YAML 或遠端 URL→選中→啟用→看日誌」的順序操作，若介面沒有這些入口，應以該用戶端目前的說明和提示為準。
命令列 mihomo：先用目前執行檔的幫助資訊核對參數
命令列參數可能隨版本變化。官方服務文件示例使用 mihomo -d /etc/mihomo指定工作目錄；配置校驗常見做法是使用目前執行檔支援的測試選項，例如：
mihomo -t -f config.yaml
如果目前版本的 mihomo --help沒有列出 -t或 -f，不要直接套用這行，應按執行檔幫助資訊改用對應參數。校驗只表示設定可被核心解析，不代表節點可連線或所有應用程式都能通過。官方服務啟動方式可參考 mihomo 服務文件。
看到這些錯誤時：定位欄位、最小化，再回滾
| 錯誤或現象 | 先定位哪裡 | 最小化處理 | 恢復方式 |
|---|---|---|---|
| YAML 解析失敗、found a tab character | 報錯行附近的縮排、Tab、冒號與引號 | 將該區塊改回空格，暫時刪除最近加入的區段 | 先恢復上一份備份，再逐段加入 |
| proxy group 或 proxy not found | proxy-groups.proxies和 rules最後的策略名稱 | 只保留 DIRECT和一個已存在的策略組 | 確認名稱逐字一致後再加入其他節點 |
| address already in use、端口被佔用 | mixed-port、port或其他入站端口 | 關閉佔用程式或改用未佔用端口 | 同步修改用戶端代理端口和系統代理設定 |
| 匯入成功但沒有節點 | 回應內容、provider 類型、權限與更新日誌 | 先用無節點範本確認用戶端正常，再單獨檢查訂閱回應 | 恢復到最近可用 Profile，避免覆蓋原檔 |
| 啟用後無法連線 | 目前 Profile、代理組選擇、系統代理和日誌 | 暫時選擇 DIRECT或 mode: direct測試 | 分別恢復規則、DNS、TUN，每次只改一項 |
| TUN 啟動失敗 | 權限、系統路由、DNS 劫持和防火牆 | 先關閉 TUN，確認普通 mixed-port 是否正常 | 按目前系統權限和 mihomo TUN 文件逐項恢復 |
排錯時建議遵循「備份目前可用設定→只保留最小設定→確認核心能解析→加入一個區段→重新校驗→再啟用」的順序。不要同時改端口、DNS、規則和 TUN，否則難以判斷是哪一項造成問題。
若遠端訂閱匯入失敗，先檢查 HTTP 回應狀態、Content-Type、回應首行和實際內容。若首行是 HTML，例如 <!DOCTYPE html>，通常不是可直接匯入的 YAML；若內容是編碼文字或節點 URI，也不能只依檔名判斷為 YAML。不要在終端機、日誌或截圖中公開包含 token 的完整 URL。
規則必須由上至下匹配；如果先放 MATCH，後面的規則就不會生效。先保留一條明確的 DOMAIN-SUFFIX規則和最後的 MATCH，確認規則命中後再逐步增加其他條件。相關優先順序可參考 mihomo 路由規則文件。
匯入前後的安全與回滾清單
- 來源：只使用你能確認來源的本機 YAML 或訂閱地址。
- 格式：確認檔案副檔名、UTF-8 編碼、空格縮排和欄位層級。
- 引用：節點、策略組、規則目標和 provider 名稱逐字一致。
- 敏感資料：不要公開訂閱 URL、密碼、UUID、
external-controller或secret。 - 順序：先用普通 mixed-port，再加入 DNS、規則和 TUN。
- 備份：修改前複製目前設定；更新訂閱後比較差異。
- 回滾：新設定無法啟用時，切回上一份可用 Profile，不要覆蓋唯一備份。
本站是技術教學站，與文中用戶端專案並非同一主體。更新於 2026 年 11 月 1 日；設定欄位、命令參數與用戶端入口可能隨版本變化，使用前應再次核對目前 mihomo 文件和用戶端提示。
常見問題
Clash Meta 設定檔和 mihomo 設定檔有什麼區別？
在本文語境中，兩者都是指供 mihomo 相容用戶端讀取的 YAML 設定。Clash Meta 是常見搜尋說法，實際欄位和支援範圍應以目前 mihomo 文件為準。
Clash Meta 設定檔可以直接下載使用嗎？
可以匯入本機 YAML，但能否實際運作取決於檔案是否包含有效節點、策略組和規則。只有端口與 DIRECT 的最小範本只能用來驗證結構，不能提供實際代理連線。
為什麼設定檔匯入成功，但策略組裡沒有節點？
先檢查節點是否真的存在於 <code>proxies</code>或 provider，再核對策略組的 <code>proxies</code>或 <code>use</code>引用名稱。名稱大小寫、空格或標點不一致，都可能導致策略組找不到節點。
訂閱更新後，為什麼自己改的規則不見了？
如果你直接修改遠端 Profile，更新時可能被遠端內容覆蓋。較穩妥的方式是把節點放入 <code>proxy-providers</code>，把自訂策略組和 <code>rules</code>保留在主設定，再按 mihomo 文件使用支援的 override 欄位。
遠端訂閱回傳的是 YAML、URI 還是 Base64，怎麼判斷？
先查看 HTTP 回應狀態、Content-Type 和回應首行，再檢查內容是否具有 YAML 鍵值結構、節點 URI 前綴或編碼文字特徵。若回傳 HTML、登入頁或錯誤頁，就不能直接當作設定檔匯入；含 token 的完整 URL 不要公開。
YAML 設定檔可以同時寫節點 URI、Base64 和 proxies 嗎？
不要把不同格式直接混在同一檔案中。先確認訂閱實際回應格式，再選擇對應的用戶端匯入方式或轉換流程；不同格式的欄位結構並不相同。
用命令列 mihomo 校驗通過，就代表已經可以連線嗎？
不代表。校驗主要確認核心能解析設定；節點權限、遠端可達性、端口是否被佔用、系統代理、DNS 和 TUN 仍需另外測試。