Clash 訂閱更新失敗、設定解析錯誤：原因與排查步驟

先判斷問題階段：請求、解析或載入設定

「訂閱更新失敗」是用戶端顯示的總結結果，不代表訂閱網址已失效。更新通常會經過請求訂閱網址、接收回應、解析設定、套用覆寫，再交由核心載入等步驟。完整設定也可能引用遠端節點集合與規則集合，而這些資源各自有獨立的下載流程。

排查前先保留目前可正常運作的設定。不要刪除所有訂閱，也不要連續切換系統代理、TUN 模式和 DNS。每次只調整一個條件，並記下更新時間與對應日誌，才能判斷問題出在哪個步驟。

1. 備份：在「訂閱」或「設定」頁面匯出目前設定；另外保存本機覆寫、指令碼與規則。匯出的檔案可能包含節點憑證，請存放在存取受限的資料夾。
2. 重現問題：開啟「日誌」，暫時選擇 info 層級，手動更新一次，記下同一時間附近的錯誤。若資訊不足，再暫時改用 debug。
3. 分類：先確認是否有 HTTP 狀態碼或網路錯誤，再查看 YAML 行號，最後檢查代理群組、規則與欄位相關錯誤。
4. 記錄資訊：記下用戶端版本、實際核心名稱與核心版本。用戶端版本不等於 mihomo 版本；可在命令列執行 mihomo -v，查詢該執行檔的版本。

訂閱請求失敗：先檢查連結與 HTTP 回應

狀態碼與後續處理

請從服務提供者的帳戶頁面重新複製完整訂閱網址，不要手動拼接參數。網址中的權杖、查詢參數與路徑都可能影響結果。聊天軟體插入換行、複製時帶入空格，或將 & 誤寫成 &，都可能讓網址指向不同資源。

瀏覽器能開啟，不代表用戶端能更新

瀏覽器可能會帶上登入 Cookie、完成網頁驗證，或透過擴充功能使用另一條代理路徑；用戶端的訂閱請求通常不具備這些條件。因此，網頁能正常顯示並不能證明用戶端可存取訂閱介面。若遇到 301 或 302，請確認重新導向的目標仍是訂閱資源，而不是登入頁面。

若要檢查原始回應，可在 macOS 或 Linux 的 Bash 終端機使用以下指令。網址不會直接寫入命令歷程記錄，也不會自動跟隨重新導向；請先查看回應標頭，再決定是否繼續連線至重新導向的網址。此指令僅用於診斷直連路徑，不代表所有用戶端都以直連方式更新。

read -r -s -p '訂閱網址：' SUB_URL
printf '\n'
curl --noproxy '*' \
  --connect-timeout 10 \
  --max-time 30 \
  --dump-header response.headers \
  --output response.body \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

response.headers 和 response.body 都可能包含敏感資訊。請只在本機檢查，診斷完成後立即刪除。不要將訂閱網址貼到公開轉換網站，也不要把完整回應交給公用線上 YAML 檢查工具。

網路與 TLS 錯誤：分別測試直連和代理路徑

若沒有收到 HTTP 回應，應先排除網路連線問題。系統代理只會影響遵循系統代理設定的請求；用戶端下載訂閱時可能使用內建下載器。TUN 模式會改變部分流量的路由，但無法修復失效權杖、錯誤格式或 YAML 語法問題。

• no such host：網域名稱解析失敗。確認訂閱網域拼字正確，再檢查系統 DNS 與用戶端 DNS 日誌；不要將解析失敗誤判為節點通訊協定錯誤。
• connection refused：目標位址拒絕連線。若日誌指向 127.0.0.1:7890，請先確認本機代理正在監聽該連接埠，不要立刻更換訂閱。
• i/o timeout、context deadline exceeded：連線、TLS 交握或讀取回應逾時。分別嘗試用戶端提供的直連更新與代理更新，每條路徑只測試一次並記錄結果。
• x509、憑證過期或主機名稱不符：檢查系統日期、時間同步、訂閱網域，以及網路中的 HTTPS 檢查軟體。不要關閉憑證驗證來掩蓋問題。

若更新必須透過代理，而目前的訂閱恰好已無法載入，就可能形成啟動依賴：沒有可用節點，就無法下載替代設定。此時可切換回先前保存的可用設定，再透過代理更新；若服務允許，也可使用可連線的直連入口。保留舊設定比反覆清除用戶端資料更容易復原。

回應格式錯誤：分辨完整設定與節點集合

HTTP 200 只代表請求成功，無法證明回應內容適用於目前的匯入方式。請用本機文字編輯器查看回應開頭與頂層欄位，並核對服務提供者標示的格式名稱，不要只看副檔名。

若主要設定可以載入，但日誌中的失敗網址屬於 proxy-providers 或 rule-providers，問題出在被引用的資源，不一定是主訂閱。節點集合與規則集合的內容結構也不相同。請檢查相關 provider 的 url、format、behavior 與實際回應，避免將規則清單當成節點清單解析。

YAML 解析錯誤：依行號檢查縮排與資料型別

yaml: line …、did not find expected key、cannot unmarshal 通常表示文字結構或資料型別有問題。日誌提供的行號通常是解析器發現異常的位置，但真正的錯誤也可能出現在上一行，例如引號未閉合、清單層級錯誤，或冒號後缺少空格。

優先檢查四個項目

1. 縮排：統一使用空格，不要使用 Tab。每層 2 個空格是常見慣例，不是 YAML 唯一允許的寬度；同一層的欄位必須對齊。
2. 標點：欄位使用半形冒號，鍵和值之間要留空格。不要把全形冒號或彎引號複製到設定語法中。
3. 資料型別：連接埠通常填整數，例如 7890；布林值寫成 true 或 false；清單項目以 - 開頭。將整份清單寫成字串可能造成型別錯誤。
4. 名稱與特殊字元：名稱含有 : 、 # 等片段時，應正確加上引號。策略組引用名稱時，空格、大小寫與符號都必須一致。

以下是用於隔離問題的直連設定，不包含訂閱節點。此設定僅用來確認本機核心能讀取基本 YAML，不能用來測試代理連線。若連接埠 7890 已被占用，請先停止占用該連接埠的程式，或在測試副本中改用未占用的連接埠。

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

rules:
  - MATCH,DIRECT

將設定存成 UTF-8 文字檔 profile.yaml。mihomo 可使用以下指令測試設定。在 Windows PowerShell 中，若執行檔位於目前目錄，可使用 .\mihomo.exe -t -f .\profile.yaml。

mihomo -v
mihomo -t -f ./profile.yaml

測試時應盡量使用與用戶端實際執行時相同的核心與工作目錄。若設定包含遠端 provider 或相對路徑，測試結果也可能受網路、快取與檔案路徑影響。測試通過只代表這次設定檢查未發現阻斷問題，不等於所有節點、DNS 與規則下載都已驗證成功。

語法正確仍無法載入：檢查核心、覆寫與引用

不能只看用戶端名稱，還要確認核心相容性

傳統 Clash 與 Clash Meta（現稱 mihomo）支援的功能範圍不同；不同版本對通訊協定、傳輸參數與規則欄位的支援也會改變。看到 unsupported proxy type 時，應先確認具體節點類型與實際執行的核心；將檔名改成 .yaml 並不會增加通訊協定支援。

未知欄位如何處理，取決於核心版本與設定位置；有些欄位會被忽略，有些則會觸發錯誤。因此，「成功匯入」也不能證明新欄位已生效。請優先使用服務提供者標示為相容的輸出格式，再參考核心版本說明決定是否更新；不要任意刪除無法辨識的欄位。

依錯誤對象檢查相依項目

• proxy … not found：檢查策略組或規則引用的目標名稱。訂閱更新後節點名稱改變，而本機覆寫仍引用舊名稱，都可能導致引用失效。
• 找不到 provider：檢查 use: 的引用是否與 proxy-providers 中的鍵名一致，並確認合併過程沒有覆蓋整個 provider 定義。
• 規則目標不存在：檢查規則末尾的策略名稱與代理組名稱。例如規則引用某個群組時，必須有名稱完全相同的群組，不能只存在名稱相近的群組。
• address already in use：通常是執行時連接埠遭占用，與訂閱格式無關。請檢查混合連接埠、DNS 監聽連接埠或控制介面連接埠是否與其他處理程序衝突。

若下載的原始設定能通過測試，但在用戶端啟用後出現錯誤，請優先檢查「覆寫」、「合併」或「指令碼」功能。先匯出這些設定，再暫時停用，並以未經處理的設定測試一次；之後再逐項恢復。特別留意指令碼重新命名節點、覆蓋 proxy-groups，或加入不存在的規則目標等操作。

更新復原後的驗證與回報清單

錯誤提示消失後，請再做一次完整驗證。只看「更新成功」可能會漏掉 provider 下載失敗或代理組為空；只確認網頁能開啟，也可能只是流量套用了直連規則。

1. 確認訂閱更新時間已變更，並檢查節點數量、策略組與規則是否符合預期。
2. 啟用目標設定，查看同一時段的日誌，確認沒有新的設定載入錯誤或 provider 更新錯誤。
3. 在「連線」頁面發出一次目標存取請求，檢查比對到的規則、輸出策略與節點名稱，確認實際連線路徑。
4. 重新啟用暫時停用的覆寫或指令碼，每恢復一項就重新驗證；最後將日誌層級調回日常設定。

若要向用戶端維護者或訂閱服務提供者回報，請提供用戶端版本、核心版本、作業系統、更新時間、HTTP 狀態碼，以及已遮蔽敏感資訊的完整錯誤行。設定片段應保留相關縮排與引用關係，但請移除訂閱權杖、密碼、私鑰與節點伺服器位址。若問題只在某次版本升級後出現，也請註明升級前後的版本。

排查順序可整理為：先確認請求是否送達，再確認回應是否為目標格式，接著檢查 YAML 與核心相容性，最後檢查覆寫與執行環境。每次只處理目前階段的證據，通常比同時修改連接埠、DNS 和 TUN 更容易找出原因。若要重新整理安裝與設定流程，請參閱用戶端教學；若要查詢相關概念，請參閱常見問題。