先判斷：請求失敗，還是設定檔解析失敗
Clash 訂閱更新通常分為三個步驟：客戶端向訂閱網址發出請求、讀取回傳內容，再交由設定檔處理流程與核心檢查。任何一步出錯，介面都可能顯示「更新失敗」。因此，第一步不是重新安裝，而是開啟客戶端的訂閱詳細資訊與記錄，記下完整錯誤訊息、發生時間，以及目前使用的核心。
同一個訂閱網址，在瀏覽器、客戶端和命令列中收到的內容可能不同。瀏覽器能開啟，只能證明該次請求有收到回應，不代表回傳的是 Clash 可用的設定檔。已匯入的節點仍可連線，也只代表舊設定檔還能使用，不代表訂閱介面正常。
| 記錄或回應內容 | 通常代表的狀況 | 優先檢查項目 |
|---|---|---|
timeout、connection refused | 請求未正常完成 | 網路路徑、代理連接埠與服務狀態 |
401、403 | 驗證或存取政策拒絕請求 | 訂閱權杖、帳戶狀態、請求標頭 |
404、410 | 網址不存在或資源已撤銷 | 目前的訂閱入口與連結是否已重設 |
429 | 請求頻率受到限制 | 自動更新週期與重試次數 |
yaml: line … | 回應本文無法依預期解析 | 回傳格式、縮排、特殊字元 |
unsupported proxy type | 核心不支援某種節點類型 | 核心版本與訂閱輸出目標 |
連結過期、帳戶異常與 HTTP 狀態碼
重新複製目前的訂閱網址
前往訂閱服務商的帳戶頁面，確認方案狀態、有效期限與剩餘流量，再從目前的入口複製適用於 Clash 或 mihomo 的網址。方案到期、權杖重設、介面遷移或流量用盡都可能影響回應；實際處理方式由服務商決定，不能只憑單一狀態碼判定帳戶已過期。
- 複製時檢查網址開頭與結尾，避免帶入換行、空格、引號或通訊軟體附加的標點符號。
- 完整保留查詢參數。不要為了「簡化網址」而刪除問號後的內容。
- 如果網址是從網頁原始碼複製而來，請注意
&是 HTML 表示法，實際網址中的參數分隔符號應為&。 - 如果剛重設帳戶的訂閱權杖，舊網址可能會立即失效。請先修改現有的訂閱項目，避免留下多個名稱相同的設定檔。
依狀態碼處理，不要連續點擊更新
401 常見於驗證資訊缺漏或失效；403 也可能是存取限制、風控或請求標頭政策所致；404 則可能代表介面路徑已變更。遇到 429 時，請依伺服器的 Retry-After 提示等待；若沒有提示，先暫停自動更新，再洽詢服務商。持續重試只會增加請求量，無法修復權杖問題。
遇到 500、502、503 時，應優先留意伺服器或閘道狀態。記下錯誤時間，間隔一段時間後再試。304 可能是正常的快取協商結果，並不一定代表失敗，還需確認客戶端是否正確保留舊內容。
請求逾時：確認訂閱下載使用的網路路徑
系統代理、TUN 與訂閱下載彼此相關，但不是同一個環節。有些客戶端會自行下載設定檔，有些提供「透過代理更新」選項；核心中的節點提供器也可能使用獨立的更新設定。介面顯示更新失敗時，不能直接假設它和瀏覽器走的是同一條網路路徑。
- 在同一個網路環境下記錄一次失敗記錄，分辨是 DNS 解析失敗、TCP 連線失敗、TLS 失敗，還是讀取逾時。
- 確認客戶端實際監聽的本機代理連接埠，不要直接照抄舊教學。本文命令使用
127.0.0.1:7890，僅適用於該連接埠確實是 HTTP 或混合代理入口的情況。 - 保留仍可用的舊設定檔，分別測試直接連線與透過舊設定檔代理請求。每次只變更一個條件。
- 如果切換網路後恢復正常，請繼續檢查原網路的 DNS、閘道限制與安全軟體，而不是修改節點密碼。
使用 curl 比對回應
以下命令適用於 Linux 或 macOS 的 Bash。網址會透過隱藏輸入讀取，避免直接寫入 shell 歷史紀錄；輸入時仍須留意裝置環境的安全性。範例將連線等待時間限制為 10 秒、整體請求時間限制為 30 秒，並將回應標頭與本文分別儲存為本機檔案。Windows 環境可使用 curl.exe，但變數輸入語法須依使用的終端機調整。
read -r -s -p '訂閱網址：' SUB_URL
printf '\n'
curl --noproxy '*' --connect-timeout 10 --max-time 30 \
-D subscription.headers -o subscription.body "$SUB_URL"
curl --noproxy '' --proxy http://127.0.0.1:7890 \
--connect-timeout 10 --max-time 30 \
-D subscription-proxy.headers -o subscription-proxy.body "$SUB_URL"
unset SUB_URL此處的「直接連線」是指不使用 curl 明確指定的代理；如果系統已啟用 TUN，連線仍可能由 TUN 接管。需要比對時，請先確認不會影響其他工作，再暫時關閉 TUN 並重複測試。遇到 301 或 302 時，先檢查 Location 指向的網域，確認可信後再考慮使用 -L 跟隨重新導向。
User-Agent：為什麼同一個網址會回傳不同格式？
User-Agent 是用來描述請求程式的 HTTP 標頭。有些訂閱服務會依此選擇輸出格式，例如對瀏覽器回傳說明頁、對特定客戶端回傳 YAML，或拒絕無法識別的請求。也有服務完全不使用這個欄位，而是透過專用網址或查詢參數辨識客戶端。
先確認服務要求，再修改請求標頭
- 查看訂閱服務商的格式說明，確認該網址適用於 Clash、Clash Meta（mihomo）或其他客戶端。
- 記下客戶端名稱、客戶端版本與核心版本。客戶端版本和核心版本是兩項不同資訊，更新介面不一定會同步更新核心。
- 比對客戶端記錄與命令列回應。不要把瀏覽器中的登入頁面誤認為訂閱內容。
- 只有在服務商明確要求特定 User-Agent 時，才在客戶端支援的訂閱請求設定中填入該值；選單名稱會因客戶端而異。
例如，若服務商明確要求使用 clash.meta，可以在前述 curl 請求中加入 -A 'clash.meta' 進行比對。這個字串只是特定服務可能接受的值，不是所有 mihomo 客戶端都固定使用的請求標頭，也不是通用的修復方式。偽裝請求標頭無法繞過帳戶實際到期或權限限制。
不要隨意將 User-Agent 加到設定檔最上層，期待它能改變客戶端的訂閱請求。客戶端下載整份設定檔，與核心更新 proxy-providers 是不同流程；只有對應元件支援的設定才會生效。更換請求標頭後若取得了 YAML，但客戶端仍更新失敗，請接著檢查格式與核心相容性。
HTTP 200 仍無法解析：檢查回應本文
200 OK 只代表 HTTP 請求成功，不代表內容適用於 Clash。回應本文可能是登入頁、驗證碼頁面、JSON 錯誤物件、以 Base64 編碼的節點清單，或適用於其他核心的設定檔。先查看回應標頭中的 Content-Type，再於本機檢查本文開頭；回應標頭也可能標示不準確，最終仍應以實際內容為準。
| 本文特徵 | 處理方式 |
|---|---|
以 <!DOCTYPE html> 或 <html 開頭 | 檢查是否為登入頁、攔截頁，或選錯入口 |
| JSON 中包含錯誤碼或錯誤訊息 | 先處理介面錯誤，不要當成 YAML 設定檔匯入 |
多行 ss://、vmess:// 等 URI | 確認客戶端是否支援轉換，或重新選擇 Clash 輸出格式 |
包含 proxies:、proxy-groups: 等結構 | 接著檢查 YAML 與欄位相容性 |
只有 proxies: 和節點清單 | 可能是節點提供器檔案，請確認匯入入口 |
完整設定檔與節點提供器不能混用
完整設定檔通常還會定義代理群組、規則與執行參數；proxy-providers 的遠端檔案主要提供節點集合。將完整設定檔填入只接受節點集合的提供器網址，或把節點集合當成完整設定檔使用，都可能造成解析失敗或缺少策略。rule-providers 是規則集來源，不是節點訂閱入口。
Clash Meta 後來更名為 mihomo，與原版 Clash 的協定和設定功能並不完全相同。例如 Hysteria2、VLESS 等節點需要相應核心支援。記錄中若出現不支援的類型或欄位，請先確認實際執行的是哪個核心，再依服務商要求選擇輸出格式。只修改 type 名稱，無法將一種協定轉換成另一種協定。
YAML 縮排與設定檔參照錯誤
看到 yaml: line 12、did not find expected key 或 cannot unmarshal 時，先查看指出的行數及其前後幾行。解析器指出的位置通常是發現問題之處，真正原因可能在上一行：少了引號、清單縮排不一致，或把應為清單的欄位寫成字串。
空格、清單與特殊字元
- 縮排使用空格，不要使用 Tab。同一層級的鍵請保持對齊；兩個空格是常見慣例，但不是唯一合法的縮排寬度。
rules應為清單，每條規則前都要有-。中文冒號不能取代 YAML 使用的半形冒號。- 名稱含有冒號後接空格、井字號等特殊內容時，建議加上引號，並確保前後引用完全一致。
- 檢查重複鍵與意外合併的段落，尤其是手動貼上節點、覆寫規則或合併訂閱之後。
以下是用於理解清單與縮排的直連設定檔，不包含遠端訂閱，也不能取代復原節點。其規則引用了已定義的代理群組，適合用來和錯誤結構逐段比對。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-groups:
- name: "預設策略"
type: select
proxies:
- DIRECT
rules:
- MATCH,預設策略使用目前的核心檢查，不要只確認 YAML 語法有效
通用 YAML 解析器只能檢查語法，無法保證核心接受其中的欄位、協定與策略參照。可先查看本機實際執行的 mihomo 二進位檔版本，再測試暫存設定檔：
mihomo -v
mihomo -t -f ./subscription.yaml此處的 subscription.yaml 必須是儲存在本機的設定檔；若客戶端內建核心不在命令搜尋路徑中，請改用該二進位檔的實際路徑。測試外部提供器設定時，也須考量路徑與網路依賴。若出現 proxy not found 之類的錯誤，請檢查代理群組參照的節點是否存在、名稱是否一致，以及節點提供器是否已成功載入。
最終檢查清單：依序恢復更新
- 保留現況：保存仍可用的舊設定檔，記下完整錯誤訊息、時間、客戶端版本與核心版本。
- 確認帳戶：檢查有效期限、流量與權杖狀態，並從帳戶頁面重新複製正確的訂閱網址。
- 驗證請求：查看 HTTP 狀態、重新導向與回應本文，分別比對直接連線和代理請求。
- 確認格式：分辨 HTML、JSON、URI 清單、完整 YAML 與節點提供器檔案。
- 核對請求標頭：依服務商說明檢查 User-Agent，不要憑猜測反覆更換。
- 檢查設定檔：排查 YAML 縮排、欄位型別、節點協定與代理群組參照。
- 恢復自動更新：手動更新成功一次後，再設定合適的更新週期，避免多個相同訂閱同時重試。
如果新建的訂閱項目可以更新，但原有項目持續失敗，請優先檢查原項目儲存的網址、請求選項、覆寫腳本與本機快取。不要立刻清除所有設定；先備份，再依客戶端文件處理單一訂閱項目。如果多部裝置同時收到相同的伺服器錯誤，聯絡服務商時附上已遮蔽敏感資訊的狀態碼、時間與本文錯誤訊息，比只說「無法更新」更容易找出問題。
確認更新成功時，應同時確認已取得訂閱內容、設定檔通過檢查，且代理群組已正常載入。接下來才測試節點連線；若訂閱已成功取得但節點無法連線，請改查線路、節點參數與本機代理設定。相關概念可參閱術語表，後續連線問題可依疑難排解頁面繼續診斷。