Clash rule-providers 自訂規則集與 GitHub 管理實戰

rule-providers 是什麼：把規則從主設定檔拆出去

在 Clash 與 Mihomo 的 YAML 設定中，rule-providers 用來描述「規則檔要從哪裡取得、以什麼格式載入、多久更新一次」。它解決的不是單純把幾行 DOMAIN 貼到設定檔裡，而是把容易變動、數量龐大、需要多人維護的規則，拆成獨立檔案，再由核心定期下載並套用。對日常使用者來說，這代表主設定檔可以保持清楚；對進階使用者來說，則能把 AI 服務、串流平台、廣告過濾、公司網域或內網例外分別管理。

rule-providers 與 rules 是兩個不同層次。前者負責定義規則來源，後者負責決定規則的讀取順序與要套用的策略組。例如，AI-SERVICES 這個 provider 可以包含多個網域，rules 再以 RULE-SET,AI-SERVICES,AI 將命中的流量交給名為 AI 的策略組。若只建立 provider，卻沒有在 rules 中引用它，檔案即使下載成功也不會產生任何分流效果。

不同 Clash 客戶端的介面名稱可能不同，但只要底層使用 Mihomo 或相容核心，概念大致一致。Clash Verge Rev、Mihomo Party、部分 Clash for Android 衍生客戶端通常會在設定檔或覆寫功能中呈現這些欄位；舊版 Clash for Windows 的核心能力則要視實際內建版本而定。開始前請先確認目前啟用的核心支援 rule-providers、RULE-SET 與你打算使用的行為格式，避免設定檔看似保存成功，實際上核心忽略了未知欄位。

建立 provider：url、path、interval 與 behavior 的作用

一個可用的 provider 通常至少需要名稱、來源 URL、本機儲存路徑、更新間隔與行為類型。名稱是之後在 RULE-SET 中引用的識別字串；url 是遠端規則檔位置；path 是核心下載後保存的本機路徑；interval 以秒為單位，決定核心多久檢查一次更新；behavior 則告訴核心檔案內的內容屬於網域、IP 位址或經典 Clash 規則。

rule-providers:
  AI-SERVICES:
    type: http
    behavior: domain
    url: https://raw.githubusercontent.com/example/clash-rules/main/ai-services.yaml
    path: ./rule-providers/ai-services.yaml
    interval: 86400

  PRIVATE-NETWORK:
    type: http
    behavior: ipcidr
    url: https://raw.githubusercontent.com/example/clash-rules/main/private-network.yaml
    path: ./rule-providers/private-network.yaml
    interval: 172800

上例中的 behavior: domain 適合內容為網域或網域後綴的檔案，例如 DOMAIN-SUFFIX,openai.com 以外的純網域清單；behavior: ipcidr 則適合 IPv4 或 IPv6 網段。若遠端檔案實際使用的是完整 Clash 規則語法，例如每行包含 DOMAIN-SUFFIX、IP-CIDR 或 PROCESS-NAME，就應使用 behavior: classical。不要只看檔名猜格式，應直接檢查檔案內容。

path 的重點是讓核心有一個可寫入、可重複使用的位置。相對路徑通常以目前設定檔所在資料夾為基準，但不同客戶端的工作目錄可能不同，因此遇到「下載成功卻找不到檔案」時，應在客戶端的設定目錄搜尋 provider 檔案，而不是只看你手動建立的資料夾。若使用遠端訂閱搭配本地覆寫，還要確認訂閱更新不會刪除或覆蓋這個資料夾。

interval 不宜一律設定成很短。規則檔若一天只變更一次，設定每五分鐘檢查不會讓內容更即時，反而會增加 GitHub 或 CDN 請求，也可能觸發服務端的頻率限制。一般網域清單可從 86400 秒開始；高頻更新的安全規則或團隊測試檔案，再依實際需要縮短。更新間隔只負責重新抓取，並不代表遠端檔案內容一定正確，版本審查仍然不可省略。

在 GitHub 建立可維護的規則檔

將規則放到 GitHub 的價值，在於你能看到每次變更、回復錯誤提交，並讓多個裝置從同一個 URL 取得一致內容。建議使用專用 repository 或清楚命名的資料夾，例如 rules/ai-services.yaml、rules/streaming.yaml 與 rules/direct.yaml。不要把訂閱 URL、存取令牌、私人內網主機或任何敏感資訊寫進公開 repository；公開規則集只應包含可以公開分享的網域或網段。

檔案格式要先固定，再開始大量加入規則。以下是適合 behavior: domain 的簡單內容：

payload:
  - '+.api.example.com'
  - '+.cdn.example.com'
  - 'login.example.net'

這類檔案使用 payload 陣列承載網域項目，每行一項，縮排保持一致。若你需要以完整規則表達，則可採用經典格式：

payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,auth.example.net
  - PROCESS-NAME,example-client
  - IP-CIDR,10.0.0.0/8,no-resolve

實務上不要在同一個 provider 裡混合純網域與完整規則，除非你已確認目前核心的解析方式。最穩妥的做法是依格式拆檔，並讓檔名、provider 名稱與 README 說明保持一致。GitHub 的提交訊息也應寫得具體，例如「加入新的登入 API 網域」或「移除已停用 CDN」，不要只寫「update rules」，這樣日後排查錯誤優先序時才有追蹤線索。

取得 URL 時，應使用可穩定存取的 Raw 內容網址，並確認分支名稱與檔案路徑不會頻繁改動。若專案從 main 改名為其他分支，所有客戶端都可能在下一次更新時收到 404。對生產環境而言，建議以固定分支維持可用版本，變更先在測試分支驗證，再透過 Pull Request 合併；這比直接編輯主分支更容易找出是哪一次提交造成規則失效。

在 rules 中引用 provider：順序比數量更重要

Provider 完成後，要在主設定檔的 rules 中引用。最常見的形式如下：

rules:
  - RULE-SET,PRIVATE-NETWORK,DIRECT
  - RULE-SET,AI-SERVICES,AI
  - RULE-SET,STREAMING,MEDIA
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,兜底策略

Clash 會由上而下比對規則，命中第一條符合的項目後就停止繼續搜尋。因此，規則數量多不代表精準度高，排列順序才是分流結果的核心。若 STREAMING provider 放在私人網路規則前面，而其中恰好包含某個內部服務網域，內部流量就可能被送到 MEDIA；若一條過寬的 DOMAIN-SUFFIX,example.com 放在更精準的 DOMAIN,auth.example.com 前面，後者也永遠不會被執行。

建議的排序思路是：先放本機與內網例外，再放安全性或工作用途的精準規則，接著放服務分類 provider，最後才放廣泛的後綴規則與 MATCH。如果規則集彼此有重疊，請在 README 中記錄預期優先序，並用測試網域逐一驗證。對於 GEOIP、IP-CIDR 與 RULE-SET 混合的配置，也要留意 DNS 解析結果與 no-resolve 是否符合預期。

策略組名稱必須與目前設定檔中真實存在的名稱完全一致，包括大小寫、空格與特殊符號。很多「provider 沒作用」其實是策略組寫成 AI，但訂閱實際產生的名稱是 🤖 AI。在客戶端的連線日誌中找到命中規則後，再回頭核對出站名稱，是比憑記憶修改 YAML 更可靠的方法。

更新、驗證與排查規則未生效

完成設定後，不要只看 YAML 是否能保存。先在客戶端手動觸發 provider 更新，觀察是否出現 HTTP 狀態碼、下載錯誤或解析錯誤。接著打開連線日誌，使用實際會連線的網域進行測試，確認日誌顯示的命中規則名稱、provider 名稱與最終策略組一致。若只測首頁，可能漏掉登入、API、圖片 CDN 或 WebSocket 主機，導致判斷過於樂觀。

常見的 404 通常與 GitHub 分支、檔案路徑或 repository 權限有關；403 可能表示服務端拒絕請求、存取限制或錯誤的認證設定；下載成功但解析失敗，則應檢查 YAML 縮排、payload 結構與 behavior。若 provider 顯示更新時間正常，卻完全沒有命中，請確認 rules 是否真的引用了同名 provider，並檢查該規則是否被前面的寬泛條目提前攔截。

• 先測 provider 更新，再測規則命中，不要同時修改多個變數。
• 先以一個明確測試網域驗證，再擴展到整個規則集。
• 每次修改只做一個主題，例如先調整 GitHub URL，再處理規則優先序。
• 保留上一版可用設定檔，更新失敗時可以快速回復。
• 定期清理已不存在的網域，避免規則集越堆越大而難以審查。

GitHub 管理也應配合版本化流程。可以在 README 記錄 provider 名稱、格式、用途、預期策略組與最近測試日期；透過 Pull Request 檢查 YAML 語法與重複規則；在合併前用一台測試裝置手動更新並觀察日誌。若需要更嚴格的流程，還可在 GitHub Actions 中加入 YAML 格式檢查、重複行掃描與網域格式驗證。自動化的目標不是保證每個域名永遠可用，而是盡早發現拼字錯誤、空檔案與意外刪除。

另一個容易忽略的問題是快取。GitHub Raw、代理快取與客戶端本地 provider 快取可能不會同時更新，因此提交後不一定立即在所有裝置看到新內容。排查時請記錄提交版本、遠端回應內容與客戶端顯示的更新時間；若多台裝置只有其中一台異常，優先清理該裝置的本地 provider 快取或重新載入設定，而不是立刻重寫整個規則集。

與把所有規則直接塞進主 YAML 的做法相比，rule-providers 更適合長期維護，因為分類、審查、回滾與跨裝置同步都更清楚；但它也比單檔配置多了 URL 可用性、格式一致性與更新失敗等依賴。部分圖形客戶端的覆寫介面較直觀，卻可能把進階欄位隱藏起來；單純使用線上規則訂閱則省去維護成本，卻不容易掌握內容變更。若你需要 GitHub 版本追蹤、自訂優先序與 Mihomo 核心的 provider 能力，Clash V.CORE 能把設定檔、規則更新與連線日誌集中在同一套工作流程中，較適合反覆驗證分流結果；確認上述規則後，可前往下載頁取得 Clash V.CORE，開始建立自己的模組化規則集。