Clash 自訂規則集放上 GitHub:rule-providers 部署與維護實戰

為什麼把 Clash 自訂規則集放上 GitHub?

當自訂分流規則只有幾條時,直接寫在設定檔的 rules 裡最省事;但網域清單一旦持續增加,主設定就容易變得難讀、難共用,也不容易確認某次修改究竟改了什麼。這時可以把規則獨立成一份檔案,放在 GitHub 儲存庫,再透過 Clash rule-providers 載入。主設定只保留規則集來源、更新週期與套用策略,規則內容則在 GitHub 上集中維護。

這種做法適合需要在多台裝置共用分流清單、想把工作與個人規則分開,或經常增修網域的使用者。Git 會保留每次提交的差異,修改後可以檢視、回復,也能透過分支先測試再合併。無論你使用 Clash Verge Rev、其他支援 Mihomo 的桌面客戶端,或自行維護 Mihomo 設定檔,概念都相同:規則集放在可讀取的位置,客戶端負責定期取得並套用。

本文以公開 GitHub 儲存庫與 Mihomo 常見設定格式為例。不同客戶端內建的核心版本可能有差異,實際支援欄位請以所使用的 Mihomo 文件與核心版本為準。請勿把訂閱連結、帳密、私人網域清單或其他敏感資訊放進公開儲存庫;GitHub 公開內容可被任何人讀取及複製。

先準備 GitHub 儲存庫與規則檔

建議先建立一個專門存放規則的儲存庫,並以用途分資料夾,不要把所有內容塞進單一檔案。例如可以使用 rules/ 放規則集、README.md 記錄用途與維護方式。規則檔名稱應讓人一眼看懂,例如 work.yaml、media.yaml 或 custom-domains.yaml;名稱一旦被主設定引用,就應避免任意更名。

GitHub 上的儲存庫若要讓一般客戶端直接取得內容,通常需設為公開,並使用檔案的 raw URL,而不是儲存庫首頁、檔案瀏覽頁或「Download ZIP」連結。可以在 GitHub 的檔案頁點選檢視原始檔,再複製網址;常見網址形式如下,請將擁有者、儲存庫、分支與路徑換成自己的資料:

https://raw.githubusercontent.com/OWNER/REPOSITORY/main/rules/custom-domains.yaml

分支名稱也要核對。有些舊儲存庫仍使用 master,新儲存庫常見的是 main;網址中的分支若與實際名稱不同,客戶端就可能收到 404。開始維護前,可以先在瀏覽器開啟 raw URL,確認顯示的是規則檔原始內容,而不是 GitHub 的 HTML 頁面。

建立規則時先選擇適合的 behavior。只維護網域時,可用 domain;維護完整 Clash 規則行時用 classical;集中存放 IP 網段時用 ipcidr。不要只因為一份範例能載入,就把不同類型的內容混在同一個 provider;按用途拆分能讓格式驗證、更新和故障排查更直接。

payload:
  - '+.example.com'
  - 'example.net'

上面的內容是 domain 類型的 YAML 範例,表示網域及其子網域。請以實際需要的網域取代示例值。若使用 classical,清單則應放入完整規則,例如 DOMAIN-SUFFIX,example.com;若選用 ipcidr,內容應是有效的網段表示法。行為類型與檔案內容不相符,是規則集載入成功但規則無法如預期命中的常見原因。

在 Mihomo 設定 rule-providers

規則檔準備好後,在主設定檔的頂層加入 rule-providers。每個 provider 都要有唯一名稱,並指定取得方式、規則行為、遠端網址、本機快取路徑與更新間隔。以下設定示範從 GitHub raw URL 載入 YAML 網域清單;請依自己的儲存庫與策略組名稱修改。

rule-providers:
  custom-domains:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/OWNER/REPOSITORY/main/rules/custom-domains.yaml"
    path: ./ruleset/custom-domains.yaml
    interval: 86400

rules:
  - RULE-SET,custom-domains,PROXY
  - MATCH,DIRECT

type: http 表示核心透過 HTTP(S) 取得遠端檔案;path 是規則在本機的快取位置,請使用符合核心設定目錄的相對路徑,避免與既有檔案撞名;interval 以秒為單位,86400 約為一天。更新並非每次開啟網頁都即時發生,剛修改 GitHub 檔案後,可能要等候下一次更新,或在客戶端手動更新設定檔、重新載入核心。

format: yaml 對應上述含有 payload 的 YAML 檔。若你的規則檔採用其他格式,必須讓格式設定與檔案實際內容一致,並確認核心版本支援。部分核心或設定介面對欄位的預設值、路徑處理方式可能不同;遇到解析錯誤時,先查核心版本文件,再對照日誌,不要只靠反覆更換縮排猜測。

設定檔中的 RULE-SET,custom-domains,PROXY 會將命中的規則交給名為 PROXY 的策略組。請換成你設定檔中確實存在的策略組名稱,例如自訂的手動選擇組;如果名稱不存在,規則集本身即使下載成功,路由仍可能報錯或無法按預期運作。還要留意 rules 的先後順序:規則通常由上往下比對,應把需要優先處理的 RULE-SET 放在較寬泛規則及最終匹配規則之前。

rule-providers 定義「從哪裡載入規則」,rules 裡的 RULE-SET 才是「命中後走哪個策略」。兩者缺一不可;只宣告 provider 不會自動套用規則。

發布與驗證:從 GitHub 到實際命中

建議採取小步驟發布,不要第一次就把大量網域、IP 網段與完整規則搬進同一個檔案。先建立一份只含少量測試項目的規則集,確認客戶端能取回並解析,再逐步加入正式內容。以下流程可以作為首次部署的檢查順序:

  1. 建立並提交規則檔:在 GitHub 儲存庫新增 YAML 檔,確認縮排一致、欄位名稱正確,且檔案內容與預定的 behavior 相符。提交訊息可寫明用途,例如「新增工作網域規則」,方便日後追蹤。
  2. 確認 raw URL 可讀:在瀏覽器開啟原始檔網址,檢查網址中的儲存庫、分支與檔案路徑,並確認回應不是 404 或 HTML 頁面。若使用大小寫不同的路徑,也要確保與 GitHub 上的檔名完全一致。
  3. 加入 provider 與引用規則:將 provider 放在設定檔頂層,再把對應的 RULE-SET 放到 rules 的適當位置。確認策略組存在,並檢查後面是否有更早命中的規則攔截流量。
  4. 驗證 YAML 並載入設定:先使用客戶端的設定檔檢查功能或核心驗證工具,修正縮排、冒號與引號等語法問題,再重新載入設定。設定能解析,只代表語法通過,仍需確認 provider 成功更新。
  5. 用連線紀錄確認命中:開啟目標網域或服務,在 Clash 的連線紀錄中查看實際命中的規則類型與策略組。若顯示的是其他規則,檢查規則順序;若沒有連線紀錄,先確認應用程式是否真的產生了新連線。

測試時最好選擇自己能明確辨識的網域,並在修改前後分別觀察連線紀錄。不要只以「網站能不能開」判斷規則成功,因為網站可能透過快取、其他子網域或不同連線路徑載入。若想驗證某條規則,可先查看連線詳細資訊中的主機名稱、命中規則與出站策略,再與規則檔逐項對照。

更新頻率也應符合內容變動需求。個人維護、每週才調整一次的清單,通常沒有必要設成極短間隔;過度頻繁更新不會讓規則判斷更精準,反而增加重複請求與排查時的變數。另一方面,若規則集在重大調整後需要立即生效,可透過客戶端的手動更新或重新載入功能確認,不必為了單次測試永久縮短更新間隔。

替每份規則集寫一段簡短說明,記下用途、內容格式、維護者與最後驗證方式。當半年後回頭看時,你會比面對一串沒有說明的網域更容易判斷哪些項目仍然需要。

用 Git 管理變更,讓規則集可回溯

把規則檔放上 GitHub 的價值,不只是提供一個下載網址,更在於每次變更都有紀錄。新增網域、移除失效項目或調整分類時,請使用有意義的提交訊息,並讓一次提交盡量只處理一類變更。如此一來,若更新後出現誤分流,就能快速定位最近修改,而不是在一大包混合變更裡逐行尋找。

如果規則會影響多台裝置或其他使用者,可先在分支上測試,再合併到供客戶端讀取的穩定分支。正式分支更新前,檢查變更差異,確認沒有誤刪重要規則、意外加入寬泛網域,也沒有把私人資訊或本機路徑提交上去。共享規則集時,最好先說明「哪些使用者/服務會命中」,避免使用者只看到一串網域卻不知道它們的分流意圖。

部署方式也會影響可重現性。直接引用 main 分支較方便,客戶端會依更新週期取得分支目前的內容,但每次提交都可能改變生效結果。若你需要固定版本、降低未測試變更影響,可以改用特定標籤或 commit 對應的 raw URL;代價是規則不會自動跟上後續更新,需要在驗證後手動更新網址。個人日常使用可優先考慮維護方便,團隊或穩定性要求較高的環境則應明確管理發布版本。

GitHub 公開儲存庫不是保密空間,即使之後刪除檔案,先前內容也可能已被複製或保留在提交紀錄中。不要上傳訂閱 URL、節點資訊、存取權杖、內網主機清單或任何不希望公開的資料。若確實需要私有規則來源,先確認客戶端與核心支援的驗證方式及憑證管理方式;不要把 token 直接寫進公開 URL 或設定檔,再把設定檔同步到不受控的位置。

維護方式 優點 需要留意
直接引用穩定分支 設定簡單,提交後可依更新週期取得新內容 未測試的分支變更也可能被客戶端載入
引用固定標籤或版本 版本可重現,方便核對與回復 更新規則時需手動調整引用版本
先測試再合併 可降低錯誤規則直接影響日常使用的風險 需要維護分支與發布流程

常見問題:provider 更新失敗或規則沒有命中

瀏覽器能開 GitHub,為什麼 Clash 還是下載失敗?

瀏覽器與 Mihomo 核心的網路路徑不一定相同。瀏覽器可能使用系統代理,核心下載 provider 時卻走另一條路徑;也可能是 raw URL、分支名稱或檔案路徑有誤。先從日誌確認錯誤類型,再直接測試完整 raw URL、核對 HTTP 狀態與遠端回應內容。如果網址能在瀏覽器開啟但核心仍逾時,請檢查核心更新 provider 時使用的網路環境與 DNS,而不是先修改規則內容。

規則集已下載,為什麼載入時出現解析錯誤?

常見原因包括 YAML 縮排錯誤、format 與實際檔案格式不一致、behavior 和清單內容不相符,或伺服器回傳了錯誤頁面而非規則檔。先在 raw URL 檢查實際內容,再查看核心日誌所指向的檔案與行號。若最近修改過檔案,亦可暫時回復上一個已知可用的 Git 提交,以判斷問題是否由最新變更引起。

provider 更新成功,目標連線卻沒有使用指定策略?

下載成功不等於規則一定命中。請檢查 rules 是否引用正確的 provider 名稱、策略組是否存在,以及前面是否有更早匹配的規則。網域格式也要符合所選行為,例如 domain 類型應放網域項目,完整的 DOMAIN-SUFFIX 規則則應放在相符的規則格式中。最後透過連線紀錄核對實際請求的主機名稱;主站與 API、圖片或 CDN 可能使用不同網域,不能假設一條網域規則涵蓋整個服務。

修改 GitHub 檔案後,客戶端多久會更新?

依設定的 interval 與核心的更新行為而定,修改不一定立刻出現在客戶端。測試時可在客戶端手動更新設定或重新載入 provider,並檢查日誌中的更新結果。若固定版本網址指向特定標籤或提交,還必須將引用更新到新的版本;否則遠端檔案即使有新提交,客戶端仍會讀取舊內容。

建立可維護的 Clash GitHub 規則集流程

相較之下,部分同類工具把規則鎖在單一設定畫面,匯出、共用與回復修改都不夠直覺;有些方案雖能下載遠端清單,卻缺少清楚的更新紀錄,規則失效時很難判斷是來源、格式還是本機設定出了問題。Clash 搭配 Mihomo 的 rule-providers,可以把規則內容與主設定分開,並透過 GitHub 與 Git 保留版本差異、整理多人共用的維護流程。只要使用合適的規則類型、排好匹配順序,再以連線紀錄驗證命中結果,就能讓規則更新更可控,也更容易回復與排錯。若你還沒有合適的客戶端,可前往客戶端下載頁查看支援平台與版本資訊。

→ 立即免費下載 Clash,開啟流暢上網新體驗

前往本站下載頁取得客戶端