Mihomo 自訂分流規則進階設定:GitHub 託管與 CI 檢查

先釐清 rule-providers:把規則資料和分流決策拆開管理

在 Mihomo 裡,自訂分流規則不一定要全部寫在主設定檔的 rules 清單中。當網域清單逐漸變長、需要多台裝置共用,或希望每次更新都能留下版本紀錄時,可以把規則資料放在 GitHub,再透過 rule-providers 下載到本機快取,最後由主設定檔的 RULE-SET 規則指定流量要送往哪個策略組。這樣一來,規則資料、更新週期和代理策略各自有清楚邊界,比直接在多份設定檔複製貼上一長串網域更容易檢查與回復。

請先分辨兩個容易混淆的部分:rule-providers 定義的是「規則從哪裡取得、採用哪種格式、多久更新一次」;rules 裡的 RULE-SET 則是「命中這組規則時,交給哪個策略組」。provider 本身不會自動替你選擇節點,也不會因為名稱裡有 GitHub 就把 GitHub 流量送往某個出口。真正的流量決策仍受主設定檔規則順序、策略組與最末端兜底規則共同影響。

本文使用 Mihomo 支援的 http provider,將規則檔託管在 GitHub repository,並示範以 GitHub Actions 做基本 YAML 與內容檢查。範例以網域後綴清單為主;你應依自己的連線紀錄與合法使用情境調整域名,不要把未驗證的網域大量加入規則集。Mihomo 核心版本、客戶端包裝方式與設定檔載入位置可能不同,實際使用前請確認核心支援的 provider 欄位與規則格式。

behavior: domain 適合網域類規則資料,behavior: ipcidr 用於 IP 網段,behavior: classical 則可承載完整規則條目。規則檔的內容格式必須與宣告的 behavior 相符;只改欄位名稱,不能讓不相容的內容自動轉換。

GitHub repository 怎麼規劃:讓規則可追蹤、可回復

建立專用 repository 或在既有設定 repository 中建立獨立目錄皆可。若規則會被多個裝置引用,建議使用清楚且穩定的檔案路徑,例如 rules/domain/work.yaml,避免把個人暫存檔、測試用規則和正式使用的清單混在一起。每筆規則應有明確用途,並在 README 記錄資料來源、維護者、更新方式與最後人工檢查日期。不要在公開 repository 放入訂閱網址、存取權杖、私有網域清單或其他憑證。

以下是網域類 provider 的規則檔示意。payload 內列出網域後綴,不要加入完整的 DOMAIN-SUFFIX, 規則前綴;若需要混合多種規則類型,請改採合適的 classical 格式,並依核心文件確認具體語法。

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

公開 repository 的原始檔通常可透過 raw.githubusercontent.com 取得。使用 GitHub 網頁上的檔案瀏覽頁網址,而不是 raw 檔案網址,常會下載到 HTML 頁面而非 YAML。若 repository 是私有的,不要假設 Mihomo 能直接使用瀏覽器登入狀態;改用經過評估、可安全授權且符合核心支援方式的託管方案,並避免把長效 token 明文寫進設定檔或公開連結。

主設定檔可以像下面這樣引用 provider,再以 RULE-SET 指向實際策略組。範例中的策略組名稱必須先在 proxy-groups 定義,並替換成你設定裡確實存在的名稱;主設定檔的其他訂閱欄位不需要照抄。

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

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

url 是遠端檔案位置,path 是核心在本機保存或讀取 provider 資料的路徑,兩者不可互換。相對路徑如何解析,可能受啟動核心時指定的工作目錄與客戶端的設定檔管理方式影響;如果更新失敗,先從核心日誌確認實際讀取位置,再核對資料夾是否可寫、父目錄是否存在,以及不同作業系統上的路徑格式。interval 以秒表示,設定為一天只代表檢查更新的週期,不保證遠端檔案一定可連線,也不代表每次檢查都會下載內容。

規則順序與更新策略:避免「已載入卻沒有命中」

provider 正常載入,只代表規則資料可用,不代表流量一定會走到預期出口。Mihomo 會依 rules 的排列順序逐條判斷,先命中的規則就會決定該連線的處理方式。因此,較精確的自訂規則通常要放在可能提前涵蓋相同流量的廣泛規則之前;若某個網域已先被其他 DOMAIN-SUFFIX、GEOIP 或其他規則集命中,後面的自訂 provider 就不會再有機會處理它。

維護時不要只看設定檔文字,應同時查看客戶端的連線紀錄、核心日誌與策略組選擇結果。重現問題時記下連線的目標 hostname、命中的規則類型、規則集名稱與最後使用的策略組。若連線紀錄只顯示 IP,可能需要檢查 DNS 模式、嗅探設定或連線建立方式;在尚未確認 hostname 之前,不宜立即擴大規則範圍,否則容易把不相關流量一併改道。

症狀 優先檢查 處理方向
provider 載入失敗或日誌顯示下載錯誤 raw URL、網路可達性、HTTP 回應與本機路徑 確認網址直接回傳 YAML,並檢查核心是否能寫入快取目錄。
YAML 可解析,但 provider 初始化失敗 behavior 與 payload 格式 確認網域清單沒有混入完整規則前綴或不支援的資料結構。
provider 顯示正常,連線仍走錯策略 rules 順序、策略組名稱與實際 hostname 確認是否有更早規則命中,並在連線紀錄中核對最終匹配結果。
改了 GitHub 檔案,但裝置仍使用舊內容 更新週期、本機快取、分支與路徑 確認核心取用的是預期 branch 和檔案,再透過客戶端或核心支援的方式手動更新。

更新週期不宜設得過短。頻繁輪詢會增加遠端請求,也可能在網路不穩時反覆留下錯誤日誌;若規則變更不頻繁,採用每日或更長週期通常較容易維護。重要規則調整時,可以先在測試設定檔手動更新 provider,觀察命中結果,再合併到日常使用的設定。GitHub 的 commit 記錄提供了變更差異與回退線索,但裝置端是否立刻使用新版內容,仍取決於核心的更新行為與快取狀態。

新增規則時一次只改一個小範圍,先記錄 hostname、預期策略與實際命中結果。這種可重現的對照,比同時調整 DNS、代理組、規則集和更新週期更容易找出問題來源。

用 GitHub Actions 做 CI 檢查:先擋住格式與重複項

GitHub 上的檔案能被下載,不等於內容就能被 Mihomo 正確使用。CI 的第一層目標,是在 pull request 或 push 時檢查 YAML 是否可解析、是否有預期的頂層欄位、規則是否重複,以及清單是否意外變成空集合。這能攔住常見的人為疏失,但不能取代 Mihomo 核心本身的載入測試,也不能證明某個網域一定應該走代理。規則語意、來源可信度與實際命中狀況仍需人工驗證。

以下示意工作流程使用 Python 與 PyYAML 解析規則檔,再檢查 payload 類型、空值與重複項。請在 repository 中確認依賴版本與工作流程權限符合你的維護政策;若使用第三方 Action,應固定到可信任的版本或 commit,避免無限制地執行外部程式碼。

name: Validate rule providers

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"
      - run: python -m pip install PyYAML
      - run: python scripts/check_rules.py rules/domain/work.yaml

可以把檢查程式放在 scripts/check_rules.py。以下範例僅針對示意中的網域清單格式:除 YAML 語法外,也拒絕空清單和重複條目。實際團隊若有多種 provider,應依各自的 behavior 分別驗證,避免用一套過度寬鬆的檢查器假裝能涵蓋所有格式。

import sys
import yaml

with open(sys.argv[1], encoding="utf-8") as stream:
    data = yaml.safe_load(stream)

if not isinstance(data, dict) or not isinstance(data.get("payload"), list):
    raise SystemExit("Expected a mapping with a payload list")

items = data["payload"]
if not items:
    raise SystemExit("Payload must not be empty")

if any(not isinstance(item, str) or not item.strip() for item in items):
    raise SystemExit("Every payload entry must be a non-empty string")

if len(items) != len(set(items)):
    raise SystemExit("Duplicate payload entries found")

再往前一步,可以加入域名格式檢查、允許的頂層鍵檢查、變更行數上限,或對正式清單要求 pull request 審核。若 CI 環境能安全取得與正式環境相同版本的 Mihomo,也可以使用該核心提供的設定測試命令驗證主設定檔;但請先確認命令參數及 provider 的本機檔案準備方式,因為單純解析主設定檔不一定會下載遠端 provider,也未必能驗證 GitHub 上的最新檔案。不要將訂閱資訊或私密憑證放進 CI 日誌。

從測試到正式套用:建立可回復的維護流程

對長期維護而言,最重要的不是一次寫出很大的規則集,而是每次變更都有理由、能審查、能回復。建議把 GitHub repository 當作規則的來源紀錄:提交訊息說明新增或刪除項目的原因,pull request 附上連線紀錄或文件依據,CI 負責基本格式檢查,最後再用一台測試裝置驗證更新與命中行為。確認沒有把不相關域名送到錯誤策略後,再讓其他裝置依相同 provider URL 更新。

發布前可依序檢查:遠端 raw URL 是否能取得預期內容;規則檔能否通過 YAML 與自訂 CI 檢查;主設定檔中 provider 名稱與 RULE-SET 名稱是否完全一致;引用的策略組是否存在;規則順序是否符合預期;快取路徑在目標作業系統上是否可寫;最後再觀察核心日誌及連線紀錄。若更新後出現異常,先回退 GitHub 上最近一次變更,並在客戶端重新載入或更新 provider,而不是同時重寫整份設定,這樣較容易確認是資料內容、載入流程還是分流策略造成問題。

也要為規則設定維護邊界:只收錄可說明用途、來源與預期行為的項目;定期刪除已不再使用的網域;避免將整個大型雲端平台或頂級網域一概送往同一策略組。規則越寬,誤傷機率與排查成本通常越高。若連線目標使用共享 CDN 或雲端服務,請先觀察實際 hostname 與影響範圍,再選擇精確網域、網域後綴或其他適用的規則型態。

不要把 GitHub Actions 的 YAML 通過視為「Mihomo 一定會成功載入」的保證。CI 解析、核心設定測試與真實網路連線是不同層次的驗證;變更正式規則前,應在實際使用的核心版本與客戶端中確認結果,並保留可快速回退的 commit。

部分同類代理工具只提供固定的內建清單,想新增例外時得反覆手動編輯,難以知道哪次變更造成誤判;另一些工具雖能匯入遠端規則,卻缺少版本差異、格式檢查與清楚的更新紀錄。Mihomo 的 rule-providers 配合 GitHub,能把規則資料、更新週期和分流策略分開管理,再利用 CI 提早攔截格式錯誤,讓自訂規則更容易共用、審查與回復。若你準備開始建立自己的 Mihomo 設定,可前往客戶端下載頁了解各平台版本;也可以先從小型規則清單開始測試,確認載入與命中結果後再逐步擴充。

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

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