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 的服務。重點不是服務名稱,而是產物必須具有固定路徑、可快取、可追蹤版本,並能在新版本發生錯誤時迅速切回舊版本。
- 整理來源檔案。在
sources中以一行一個項目的方式保存網域,使用清楚的檔名區分用途。先決定每個檔案對應的策略,例如廣告清單交給REJECT,工作清單交給工作策略組。 - 產生標準格式。使用腳本去除重複資料、檢查網域語法,再輸出包含
payload的 YAML。產物檔名固定,例如ads.yaml,不要把提交雜湊直接寫入主設定 URL。 - 執行結構驗證。解析每個輸出的 YAML,確認根節點、
payload類型與規則項目都符合預期。若任一檔案失敗,工作流程應停止發布,避免把半套規則部署出去。 - 建立版本產物。以日期、提交短雜湊或遞增版本建立不可變的發布目錄,同時維持一份穩定的目前版本路徑,讓 Clash 持續使用固定 URL。
- 更新穩定指標。所有檔案驗證成功後,才將穩定路徑切換到新版本。切換動作應放在最後,避免客戶端取得同一批發布中的部分新檔案與部分舊檔案。
- 在客戶端手動刷新。首次部署時先不要等待週期更新,於 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,則需要在測試或正式切換時更新引用,這種方式更適合嚴格控管變更。
規則集更新後出錯,應該刪除本機快取嗎?
通常先回滾服務端版本並重新更新即可,不必立即刪除快取。本機快取在來源短暫不可用時可以提供上一份資料。只有確認快取檔案損壞、格式不正確或需要重新建立時,才應依照客戶端提供的管理方式清除並重新下載。