Clash 自訂 Rule-Providers：用 GitHub 維護 YAML 分流規則

先理解 rule-providers 與主設定的關係

Clash 的分流規則通常直接寫在主設定的 rules 欄位中。規則數量少時，這種方式簡單直觀；但當設定需要同時處理開發工具、AI 平台、串流服務、廣告網域與區域網站時，主 YAML 會迅速變得冗長。每次增加或刪除一個網域，都要修改完整設定，再重新匯入或觸發訂閱更新，維護成本會逐漸升高。

rule-providers 可以將規則拆成獨立檔案。主設定只負責宣告規則集的名稱、下載網址、快取路徑、規則格式與更新間隔，再透過 RULE-SET 將這組規則接回 rules。這樣一來，主設定中的分流邏輯保持穩定，規則內容則可以在 GitHub 儲存庫中獨立編輯。

需要注意的是，rule-provider 不是代理節點，也不是策略組。它只提供一組可供比對的規則，最後要送往哪一個節點或策略組，仍由 rules 中的策略名稱決定。換句話說，完整的分流流程是「規則提供者提供條件、RULE-SET 呼叫條件、策略組決定出口」。

設定區塊	主要用途	常見內容
`rule-providers`	宣告外部或本機規則集	網址、格式、快取路徑、更新間隔
`RULE-SET`	在主規則中引用規則集	規則集名稱、目標策略
`proxy-groups`	管理可用的代理出口	節點選擇、自動測速、直連、拒絕
`rules`	依序決定流量處理方式	網域、IP、規則集與兜底規則

建立適合維護的 GitHub YAML 規則檔

GitHub 規則檔最重要的不是一次列出大量網域，而是讓內容容易閱讀、審查與回溯。建議依用途拆分檔案，例如 developer.yaml 放置程式碼託管、套件註冊表與文件服務；ai-services.yaml 放置 AI 平台與模型服務；streaming.yaml 則只處理影音平台。每個檔案只負責一種清楚的語意，日後才容易判斷某個網域應該新增到哪裡。

如果規則提供者設定為 behavior: domain，規則檔一般使用 payload 陣列，內容可放 DOMAIN、DOMAIN-SUFFIX 與 DOMAIN-KEYWORD。開發工具與 AI 平台通常優先使用 DOMAIN-SUFFIX，因為它能涵蓋同一服務的不同子網域，同時比關鍵字比對更不容易誤傷其他網站。

payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN-SUFFIX,githubassets.com
  - DOMAIN-SUFFIX,openai.com
  - DOMAIN-SUFFIX,chatgpt.com
  - DOMAIN-SUFFIX,anthropic.com
  - DOMAIN-SUFFIX,claude.ai

若希望檔案更接近傳統 Clash 規則集，也可以使用 behavior: classical，並在檔案中放入帶有完整動作的規則，例如 DOMAIN-SUFFIX,example.com,Proxy。不過在主設定中再透過 RULE-SET 指定策略時，容易讓出口策略分散在多個檔案中。對需要集中管理策略的設定而言，使用 domain 或 ipcidr 行為，通常更容易維護。

網域規則的選擇原則

精確網域：使用 DOMAIN,api.example.com，只匹配指定主機名稱，適合只想分流單一 API 的情境。
網域後綴：使用 DOMAIN-SUFFIX,example.com，可匹配主網域及其子網域，適合同一服務有多個入口的情況。
關鍵字比對：使用 DOMAIN-KEYWORD,example，匹配範圍較寬，容易誤判，應避免把常見字串當作關鍵字。
IP 網段：使用 IP-CIDR 或 IP-CIDR6，適合已知服務固定使用某些網段的情境，但需要額外維護 IP 變動。
排除條件：若某個服務有明確的本地化網域，應先用更具體的規則處理，再讓較寬泛的後綴規則接手。

GitHub 儲存庫中的檔案應保持純文字與有效 YAML。不要在檔案中加入 Tab 縮排，也不要把說明文字直接寫在 payload 陣列中。若需要標示來源或用途，可以使用 YAML 註解，但註解仍應放在合法的欄位位置。

# 開發工具與 AI 平台規則
payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,pypi.org
  - DOMAIN-SUFFIX,npmjs.com
  - DOMAIN-SUFFIX,openai.com

在主設定中宣告遠端 rule-provider

規則檔放到 GitHub 後，需要使用能直接回傳檔案內容的 Raw URL，而不是儲存庫檔案頁面網址。GitHub 的一般檔案頁面會回傳 HTML，mihomo 下載後無法將它解析為規則集。網址應指向 raw.githubusercontent.com，並包含帳號、儲存庫、分支或提交版本，以及檔案路徑。

以下範例使用 developer-tools 作為規則集名稱。path 是核心在本機儲存快取的相對路徑；它不是 GitHub 路徑，也不需要先手動建立。interval 的單位是秒，86400 代表每 24 小時檢查一次。

rule-providers:
  developer-tools:
    type: http
    behavior: domain
    format: yaml
    url: https://raw.githubusercontent.com/example-user/clash-rules/main/developer-tools.yaml
    path: ./ruleset/developer-tools.yaml
    interval: 86400

  ai-services:
    type: http
    behavior: domain
    format: yaml
    url: https://raw.githubusercontent.com/example-user/clash-rules/main/ai-services.yaml
    path: ./ruleset/ai-services.yaml
    interval: 43200

接著在主設定的 rules 中引用這兩個名稱。名稱必須完全一致，包括大小寫、連字號與底線；developer-tools 與 developer_tools 會被視為不同的規則集。規則由上而下比對，因此較具體的例外規則通常要放在較寬泛的 RULE-SET 之前。

rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - RULE-SET,developer-tools,開發工具
  - RULE-SET,ai-services,AI平台
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

欄位	範例值	實際作用
`type`	`http`	從遠端網址下載規則檔
`behavior`	`domain`	指定規則檔內容的比對類型
`format`	`yaml`	告訴核心如何解析下載內容
`path`	`./ruleset/developer-tools.yaml`	指定本機快取位置
`interval`	`86400`	設定自動更新間隔，單位為秒

將開發工具與 AI 平台接入策略組

Rule-provider 只負責找出目標流量，還需要在 proxy-groups 中提供對應策略。建議不要直接把規則集指向某個會經常更換名稱的節點，而是指向固定的策略組名稱，例如「開發工具」與「AI平台」。這樣日後更換節點、加入自動測速或切換備用出口時，只需修改策略組，不必逐一修改每條規則。

proxy-groups:
  - name: 開發工具
    type: select
    proxies:
      - 節點選擇
      - 自動選擇
      - DIRECT

  - name: AI平台
    type: select
    proxies:
      - 節點選擇
      - 自動選擇

  - name: 自動選擇
    type: url-test
    include-all: true
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

如果核心或訂閱設定不支援 include-all，可以改為明確列出節點或使用既有的代理群組。不同版本對策略組欄位的支援不完全相同，匯入後應查看核心啟動日誌。如果看到未知欄位、策略不存在或規則集載入失敗，先回到目前核心的設定文件核對，而不要直接複製其他版本的完整配置。

控制規則順序與避免誤分流

假設 ai-services.yaml 中包含 DOMAIN-SUFFIX,example.com，而你希望其中的內部服務直連，就必須把 DOMAIN,internal.example.com,DIRECT 放在 RULE-SET 之前。若順序相反，流量在命中遠端規則集後就會停止繼續比對，後面的例外規則不會生效。

rules:
  - DOMAIN,internal.example.com,DIRECT
  - RULE-SET,ai-services,AI平台
  - RULE-SET,developer-tools,開發工具
  - MATCH,節點選擇

同時也要避免把所有大型平台網域不加區分地放進同一個規則集。例如開發工具規則可能包含套件下載、程式碼同步與文件網站，但這些服務的流量特性不同。套件下載可使用直連或固定出口，程式碼平台可能需要穩定的代理，AI API 則可能需要另一個地區的出口。按照用途拆分，才能在出現延遲、驗證或連線失敗時快速調整。

更新、驗證與故障排查流程

完成設定後，不要只看用戶端介面是否顯示規則集名稱。先確認主 YAML 通過語法檢查，再檢查核心是否成功下載遠端檔案，最後使用實際網域測試命中的策略。FlClash 或其他 mihomo 客戶端通常可以在設定頁重新載入配置，並在日誌或規則提供者頁面查看更新狀態。

現象	常見原因	處理方向
找不到規則提供者	RULE-SET 名稱拼寫不一致	逐字比對宣告名稱與引用名稱
下載成功但解析失敗	網址回傳 HTML、格式與 behavior 不匹配	檢查 Raw URL、format 與規則檔結構
規則集一直無法更新	DNS、代理路徑或 GitHub 存取受限	檢查核心日誌，測試直連與代理兩種路徑
網域沒有命中預期策略	規則順序、網域拼寫或快取內容不正確	清除規則快取後重新更新，再查看匹配結果
設定啟動即失敗	核心不支援某個欄位或 YAML 縮排錯誤	暫時移除新增區塊，逐段恢復並查看錯誤行號

GitHub 規則檔若修改後沒有立即生效，可能是 interval 尚未到期，也可能是核心仍使用本機快取。測試階段可以在客戶端手動更新規則提供者，確認內容正確後再恢復 6 小時或 24 小時的正常更新週期。不要把更新間隔長期設為幾分鐘，否則容易造成不必要的請求與 GitHub 端的頻率限制。

curl -L --connect-timeout 10 --max-time 30 \
  -o developer-tools.yaml \
  -w "HTTP=%{http_code} SIZE=%{size_download}\n" \
  "https://raw.githubusercontent.com/example-user/clash-rules/main/developer-tools.yaml"

若回傳 HTTP=200，仍應打開下載檔確認實際內容。狀態碼正常不代表 YAML 一定符合 behavior 的要求。測試完成後，再使用核心日誌確認規則提供者更新時間、快取路徑與下載錯誤。所有測試網址中的帳號、儲存庫名稱與分支，請替換成實際使用的公開規則位置。

GitHub 版本管理與安全注意事項

公開規則集適合使用 Git 的提交記錄追蹤變更。每次修改可在提交訊息中寫明新增或移除的服務，發現誤分流時便能快速回退。對穩定性要求較高的環境，可以將 URL 固定到特定提交，而不是永遠使用 main 分支；固定提交雖然降低意外變更風險，但也需要由使用者主動更新網址。

不要把訂閱權杖、代理密碼、私鑰或內部網域清單提交到公開儲存庫。
公開規則檔只放網域與網段，不要在 YAML 中寫入節點資訊或認證資料。
修改規則前先檢查縮排、逗號與大小寫，並保留可回退的提交。
不要把不確定用途的網域大量加入規則集，先從日誌確認實際請求來源。
若儲存庫屬於團隊使用，應限制可直接修改主分支的權限，避免錯誤設定立即推送給所有用戶端。

完成後，主設定只保留必要的 provider 宣告與規則引用，GitHub 則負責保存可重用的網域清單。這種分工能讓訂閱更新、節點更換與分流邏輯彼此獨立：節點變更時不必重寫規則，規則更新時也不必重新整理整份代理設定。對需要長期維護開發工具與 AI 平台分流的使用者而言，這比把所有網域堆在單一 YAML 中更容易排錯，也更適合多人協作。