Clash 規則集進階實作:以 GitHub 管理自動更新分流

先理解規則集與 rule-providers 的分工

當 Clash 設定中的規則只有十幾條時,直接把內容寫在 rules 區段通常很容易閱讀。但隨著網域清單、廣告過濾項目、工作服務、串流平台與區域網路例外持續增加,單一 YAML 檔案會逐漸變得難以審查。規則過多不只影響閱讀,也會讓每次修改都需要重新檢查整份設定,難以知道某個網域是何時加入,以及哪一次更新造成路由結果改變。

rule-providers 的作用,是把可獨立更新的規則集放到設定檔之外,再由 Clash 或 Mihomo 按指定方式下載、儲存與載入。主設定只保留規則集名稱、來源 URL、本機快取路徑與資料格式;真正的網域或 IP 清單則維護在另一個檔案中。這種分工可以將「核心設定」與「規則資料」分開管理,也方便不同裝置共用相同規則集。

rule-providers:
  streaming:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/streaming.yaml
    url: "https://rules.example.com/streaming.yaml"
    interval: 86400

rules:
  - RULE-SET,streaming,串流策略
  - MATCH,一般代理

上例中的 streaming 是規則提供器名稱,必須與 RULE-SET,streaming,串流策略 中的名稱完全一致。behavior 說明資料內容屬於網域、IP 位址區段或經典規則格式;format 則描述下載檔案的格式。規則提供器名稱、檔案格式與規則內容彼此不匹配時,可能在更新階段報錯,也可能載入後完全沒有命中。

選擇正確的 behavior 與 format

behavior: domain 適合以網域或網域後綴為主的清單;behavior: ipcidr 適合 IPv4、IPv6 或 CIDR 網段;behavior: classical 則用於包含多種傳統 Clash 規則類型的檔案。若採用 YAML 格式,檔案通常需要包含 payload 陣列;純文字格式則應依核心支援的規則格式逐行保存。不要只依副檔名猜測格式,應讓檔案內容、behavior 與 format 三者一致。

payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,api.example.net
  - DOMAIN-KEYWORD,video

如果使用 domain 行為,通常可將網域項目放在 payload 中;但不同核心版本對規則集格式的支援細節可能有所差異。部署前應使用目前客戶端搭載的 Mihomo 版本實際驗證,而不是只在文字編輯器中確認 YAML 沒有語法錯誤。

規則順序決定自動更新後的實際路由

Clash 規則通常由上而下比對,連線命中第一條符合條件的規則後,就會交給對應策略處理。規則提供器雖然可以把資料拆出去,但不會改變這個基本原則。自動更新只是替換規則資料,並不會替使用者重新判斷不同規則集之間的優先級。

常見的排列方式,是先放置明確的本機與私人網路例外,再放置需要特殊出口的業務規則、服務規則或封鎖規則,最後才是較寬泛的網域分類與 MATCH 兜底項目。若把廣泛的 DOMAIN-SUFFIX 放在特定子網域前面,後面的精細規則可能永遠沒有機會命中。

rules:
  - DOMAIN,internal.example.com,DIRECT
  - RULE-SET,work,工作網路
  - RULE-SET,ads,REJECT
  - RULE-SET,streaming,串流策略
  - GEOSITE,cn,DIRECT
  - MATCH,一般代理

上述順序只是示意,實際排列要依使用情境調整。需要注意的是,GEOSITE,cn,DIRECT 這類較大範圍的規則若提前放置,可能會攔截原本想交給特定策略組的服務;MATCH 則必須放在最後附近,否則其後所有規則都會成為不可達分支。

確認策略組名稱與規則集名稱

RULE-SET 的第二個參數是提供器名稱,最後一個參數是策略組或動作名稱。前者來自 rule-providers,後者必須在 proxy-groups 中存在,或者是核心支援的 DIRECT、REJECT 等內建動作。兩者名稱拼錯時,可能造成設定解析錯誤,也可能使某些用戶端顯示空白策略。

建議為每一個規則集建立簡單的責任邊界。例如 work 只放公司服務與內部網域,streaming 只放串流服務,ads 只放明確需要拒絕的網域。不要把所有內容都塞進一個巨大清單,否則即使規則命中,也很難從連線記錄判斷是哪一類資料導致路由結果。

用 GitHub 建立可審查的規則集結構

將規則檔案放進 Git 儲存庫的價值,不只是「有地方存檔」。每次修改都會留下提交紀錄,可以透過差異檢視確認新增與刪除的網域;規則集出現問題時,可以根據提交時間與用戶端更新時間建立關聯;多人維護時,也能在合併前檢查規則是否重複、格式是否正確。

一個適合小型專案的目錄可以保持簡潔,將原始資料、產物與自動化設定分開:

rules-repository/
├── sources/
│   ├── ads.txt
│   ├── work.txt
│   └── streaming.txt
├── generated/
│   ├── ads.yaml
│   ├── work.yaml
│   └── streaming.yaml
├── scripts/
│   └── build-rules.py
└── .github/
    └── workflows/
        └── publish-rules.yml

sources 可以保存較容易人工編輯的純文字來源,generated 則保存經過去重、排序與格式化後,供 Clash 讀取的檔案。若不需要轉換,也可以直接把穩定的 YAML 放在儲存庫根目錄,但仍建議使用固定目錄與固定檔名,避免主設定中的 URL 因檔案搬移而失效。

把規則品質檢查放在合併前

自動部署前至少應檢查空白行、註解、重複項目、非法網域、錯誤 CIDR 與 YAML 結構。網域清單可先轉成小寫並排序,再去除重複項目;但不要盲目刪除所有看似相近的項目,因為 DOMAIN、DOMAIN-SUFFIX 與 DOMAIN-KEYWORD 的匹配語義不同。

也要避免把完整訂閱網址、控制器密鑰、代理驗證資料或私人服務位址提交到公開儲存庫。規則集通常可以公開,但來源清單可能包含內部網域。若儲存庫需要私有化,下載 URL、快取權限與客戶端的更新能力也要一起評估;不能只把儲存庫設為私有,卻仍讓沒有授權的客戶端直接請求受保護檔案。

動手建立 GitHub Actions 自動部署流程

以下流程以「來源檔案提交後,自動產生規則集並發布」為例。實際發布位置可以是靜態檔案服務、物件儲存或其他能提供穩定 HTTPS URL 的服務。重點不是服務名稱,而是產物必須具有固定路徑、可快取、可追蹤版本,並能在新版本發生錯誤時迅速切回舊版本。

  1. 整理來源檔案。在 sources 中以一行一個項目的方式保存網域,使用清楚的檔名區分用途。先決定每個檔案對應的策略,例如廣告清單交給 REJECT,工作清單交給工作策略組。
  2. 產生標準格式。使用腳本去除重複資料、檢查網域語法,再輸出包含 payload 的 YAML。產物檔名固定,例如 ads.yaml,不要把提交雜湊直接寫入主設定 URL。
  3. 執行結構驗證。解析每個輸出的 YAML,確認根節點、payload 類型與規則項目都符合預期。若任一檔案失敗,工作流程應停止發布,避免把半套規則部署出去。
  4. 建立版本產物。以日期、提交短雜湊或遞增版本建立不可變的發布目錄,同時維持一份穩定的目前版本路徑,讓 Clash 持續使用固定 URL。
  5. 更新穩定指標。所有檔案驗證成功後,才將穩定路徑切換到新版本。切換動作應放在最後,避免客戶端取得同一批發布中的部分新檔案與部分舊檔案。
  6. 在客戶端手動刷新。首次部署時先不要等待週期更新,於 Clash 或 Mihomo 客戶端中手動更新規則提供器,觀察更新結果與連線命中情況。

工作流程的核心概念可以簡化如下。這段範例只展示驗證與產物流程,實際的發布命令要依採用的部署服務補充:

name: publish-rules

on:
  push:
    branches: [main]
    paths:
      - "sources/**"
      - "scripts/**"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build rule providers
        run: python scripts/build-rules.py

      - name: Validate generated files
        run: python scripts/validate-rules.py generated/

      - name: Publish immutable artifact
        run: ./scripts/publish.sh generated/ "$GITHUB_SHA"

paths 可以避免文件說明或其他非規則內容變更時觸發發布。workflow_dispatch 則提供手動重建入口,適合在修正部署服務、更新轉換腳本或處理緊急回滾時使用。生產流程中不應只依賴「工作成功」這個狀態,還要在工作日誌中記錄產物版本、規則數量、檔案雜湊與發布路徑,方便日後比對。

設計快取、版本與回滾

interval 控制 Clash 多久嘗試更新一次規則提供器。它不是 GitHub Actions 的執行排程,也不代表檔案一定在該時間更新。若規則來源每天更新,可以使用較短的週期;若內容每週才變更,設定過短只會增加請求與日誌噪音。更新服務端也應正確處理 HTTP 快取標頭,讓沒有變化的檔案能回覆未修改結果,降低流量與不必要的重新解析。

穩定 URL 與不可變 URL 應同時存在。穩定 URL 例如 ads.yaml,供 rule-providers 長期引用;不可變 URL 則包含明確版本,供測試、稽核與回滾使用。當新版本造成誤封鎖或分流錯誤時,只要將穩定指標切回上一個已驗證版本,再讓客戶端重新整理提供器,就不必修改所有裝置的主設定。

項目 建議做法 主要用途
穩定路徑 固定檔名與固定 URL 供客戶端週期更新
版本路徑 以提交版本或發布編號區分 測試、稽核與回滾
本機快取 為每個提供器設定獨立 path 暫時離線時保留上次資料
發布驗證 先完整產生並檢查,再切換穩定指標 避免部分檔案更新

更新後如何確認規則真的生效

看到規則提供器顯示「更新成功」,只代表檔案可以下載並通過部分載入流程,不代表目標連線一定會走到預期策略。驗證時應選擇幾個具有代表性的網域,分別測試應該直連、應該代理與應該拒絕的項目,並在連線記錄中查看實際命中的規則與策略組。

如果新加入的網域沒有命中,先確認它是否真的存在於目前載入的提供器版本,再檢查規則提供器引用名稱、規則順序、DNS 嗅探結果與測試連線是否重用了舊連線。瀏覽器可能保留 DNS 快取、HTTP/3 連線或既有 TCP 連線,因此修改規則後應重新開啟頁面,必要時重啟相關應用程式。

若提供器更新失敗,查看的順序可以是:URL 是否可從目前網路取得、TLS 憑證是否正常、回應內容是否為預期檔案、檔案格式是否與 behavior 匹配,以及本機 path 是否可寫入。若更新後出現大量解析錯誤,先切回上一個已知正常版本,不要在客戶端快取上直接手動修改,否則後續很難重現問題。

日常維護清單

  • 每次修改前:確認規則目的、匹配類型與預期策略,不要只貼上未經檢查的網域清單。
  • 每次合併時:查看差異,注意大範圍後綴、重複項目與意外刪除。
  • 每次發布後:測試至少一個直連、一個代理與一個拒絕案例。
  • 定期整理:刪除失效網域,合併重複規則,並檢查提供器檔案大小是否異常增加。
  • 發生事故時:保留日誌與目前版本資訊,先回滾,再分析哪次提交造成行為改變。

常見問題

rule-providers 會取代 rules 區段嗎?

不會。rule-providers 只負責定義外部規則資料的來源與載入方式,仍然需要在 rules 中使用 RULE-SET 引用提供器,並指定命中後交給哪個策略或動作。

為什麼檔案下載成功,規則卻沒有命中?

常見原因包括 behavior 與實際內容不符、提供器名稱拼錯、規則排在較寬泛規則後面、測試網域不在清單中,以及應用程式仍使用舊連線。應先查看提供器內容與連線記錄,再檢查規則順序。

GitHub Actions 需要每次都修改 Clash 設定嗎?

不需要。只要主設定引用穩定的規則檔案 URL,後續由自動化流程更新該路徑即可。若使用不可變版本 URL,則需要在測試或正式切換時更新引用,這種方式更適合嚴格控管變更。

規則集更新後出錯,應該刪除本機快取嗎?

通常先回滾服務端版本並重新更新即可,不必立即刪除快取。本機快取在來源短暫不可用時可以提供上一份資料。只有確認快取檔案損壞、格式不正確或需要重新建立時,才應依照客戶端提供的管理方式清除並重新下載。

下載Clash