Mihomo自定义规则集进阶配置:Rule Providers托管与自动校验

为什么把自定义规则拆成 Rule Providers

当配置里的 rules 越写越长,改一条域名就要重新检查整份主配置;如果几台设备共用规则,还得在每份 YAML 里重复维护。Mihomo 的 rule-providers 可以把规则内容拆成独立文件,由主配置声明来源、类型和更新间隔,再通过 RULE-SET 在规则列表中引用。这样做的价值不只是「少写几行」:规则可以单独审阅、版本管理和回滚,配置主体也更容易读懂。

Rule Provider 不会替你决定流量走向。它提供的是一组规则,最终命中哪条、使用哪个策略,仍由主配置的 rules 顺序和 RULE-SET 后面的策略名决定。把这两层职责分开,才能在连接日志里判断问题究竟来自规则内容、规则顺序,还是策略组本身。本文用一个托管在 GitHub 的 YAML 规则集演示完整流程,并加入基础 CI 检查,帮助尽早发现格式错误和引用遗漏。

Rule Provider 与策略组不是一回事:前者回答「哪些流量属于这一组规则」,后者回答「命中后使用哪种代理或直连策略」。自定义规则集不会自动创建策略组,也不会自动改变规则优先级。

先读懂 rule-providers 的关键字段

一个远程 Provider 至少要说清楚规则从哪里来、规则采用什么匹配语义,以及 Mihomo 将规则文件保存在哪里。下面的示例把开发站点域名作为一个独立集合;实际使用时,应根据自己的连接日志和需求替换域名,避免直接复制未经核验的清单。

rule-providers:
  dev-sites:
    type: http
    behavior: domain
    format: yaml
    url: https://raw.githubusercontent.com/example-org/mihomo-rules/main/providers/dev-sites.yaml
    path: ./ruleset/dev-sites.yaml
    interval: 86400

type: http 表示从 HTTP(S) 地址获取规则,适合 GitHub Raw 等静态文件托管;behavior 则声明规则按什么类型解释。常见取值包括 domain、ipcidr 和 classical:域名集合用于域名匹配,IP 集合用于地址段匹配,经典规则可包含多种 Mihomo 规则类型。选择时应与文件内容一致,不能把普通域名列表标成 IP 段集合。

format: yaml 表示文件采用 YAML 规则集格式。规则文件可写成如下结构:

payload:
  - DOMAIN,developer.example
  - DOMAIN-SUFFIX,docs.example
  - DOMAIN-KEYWORD,packages

其中规则类型应符合 Mihomo 对应版本支持的语法。若 Provider 的 behavior 是 domain,更适合使用域名或域名后缀条目;若希望在一个集合里混合更丰富的规则类型,可评估使用 classical,并按 Mihomo 文档要求组织内容。不要仅凭 YAML 能被解析就判断规则一定有效:语法正确、行为类型匹配、目标域名准确,是三个不同的检查层次。

path 是内核保存下载文件的位置。相对路径通常以配置文件所在位置为基准,但不同客户端可能会复制、转换或在自己的配置目录中运行文件。初次部署时建议检查客户端实际使用的配置路径,并确认该目录可写;如果规则更新失败,日志中出现路径不存在或权限错误,首先检查这里,而不是贸然更换规则 URL。interval 以秒计,86400 表示约一天更新一次。设置过短会增加请求频率,却不一定让规则更及时;对稳定维护的集合,每日或每几小时检查通常比每分钟拉取更合理。

用 GitHub 托管规则集并建立可回滚的发布流程

建议为规则集合单独建仓库,至少区分 Provider 文件、校验脚本和文档。例如仓库中保留 providers/dev-sites.yaml、scripts/validate.py 与 README.md。这样规则改动的差异清晰,不会和个人主配置、订阅链接或设备信息混在一起。仓库可以公开托管不含敏感信息的通用规则;不要把访问令牌、私有订阅、内网域名清单或个人 IP 地址写入公开文件。

示例 URL 使用 main 分支,优点是更新后客户端可以按间隔获取最新内容,缺点是分支内容变化会直接影响所有使用者。正式使用时可以采取「提交到主分支、CI 校验通过、再创建版本标签」的流程,并在发布说明中记录变更内容。若希望每次变更都自动生效,就要把快速修复和误发布风险一并纳入考虑;若更看重可复现性,则可将 Provider URL 指向固定版本或发布资产,并在确认后更新到新版本。

GitHub Raw 适合发布体积较小、静态且不需要鉴权的规则文件,但它不是完整的发布治理方案。生产使用中要检查仓库与分支名称是否正确、文件路径大小写是否匹配、URL 是否能返回原始 YAML,而不是 GitHub 网页 HTML。可以在浏览器或命令行打开该地址确认响应内容;如果返回 404,先核对分支和文件路径。如果访问受到网络环境限制,则即使本地 YAML 完全正确,客户端也可能因无法取回远程文件而无法更新。

为方便审计,每次变更尽量使用小而明确的提交:新增域名与删除过时条目分开提交,说明依据和影响范围。发现误分流时,可以对照版本记录定位最近改动,再回滚对应提交,而不必从一长串订阅规则中猜测哪个条目改变了行为。多人共同维护时,保护主分支并要求变更经过校验,也比直接在默认分支上编辑更容易控制风险。

在主配置中引用,并把规则放在正确位置

Provider 声明完成后,还要在主配置的 rules 中引用它。假设策略组名称为 开发代理,最小示例如下:

rules:
  - RULE-SET,dev-sites,开发代理
  - GEOIP,CN,DIRECT
  - MATCH,开发代理

RULE-SET 的第一个参数应与 rule-providers 下的键名完全一致,第三个参数应是主配置中实际存在的策略名。名称拼写不一致、大小写不一致,或策略组并未定义,都可能让配置校验失败或产生非预期结果。规则按从上到下的顺序匹配,因此 Provider 需要放在可能提前接住同一流量的宽泛规则之前。若一个域名先命中更早的通用集合,后面的自定义 Provider 就没有机会生效。

建议先把自定义集合放在 GEOIP、国内外大集合和兜底规则之前,再用连接日志确认实际命中结果。不要把所有规则都放到最前面:优先级过高的关键词或宽泛域名后缀也可能误伤无关服务。对关键业务,可以先使用明确的完整域名或已验证的后缀,观察一段时间后再扩大范围。对于 IP 类型 Provider,还应考虑 DNS 解析、IPv4/IPv6 和规则命中对象之间的关系,不能只凭域名访问失败就断定 IP 集合没有生效。

修改后不要只看客户端是否显示「已连接」。分别核对配置解析状态、Provider 下载状态和具体连接的命中规则:如果主配置能启动但 Provider 报下载错误,问题多半在远程 URL、网络或文件路径;如果 Provider 已加载但流量仍走错策略,应检查规则顺序、规则类型和策略名称。将这三类状态拆开看,比反复切换全局模式更容易定位原因。

用 CI 校验 YAML、规则条目与主配置引用

人工检查容易漏掉缩进、重复规则和名称拼写。把基础检查放进 GitHub Actions,可以在每次提交或合并请求时自动拒绝明显错误。下面的 Python 示例使用 PyYAML 解析 Provider 文件,检查顶层结构、规则列表和常见规则前缀;它是轻量门禁,不是 Mihomo 规则语义的完整实现。

import sys
import yaml

ALLOWED_PREFIXES = {
    "DOMAIN", "DOMAIN-SUFFIX", "DOMAIN-KEYWORD",
    "IP-CIDR", "IP-CIDR6", "GEOIP", "PROCESS-NAME",
    "SRC-IP-CIDR", "DST-PORT", "NETWORK"
}

def main(path):
    with open(path, "r", encoding="utf-8") as file:
        data = yaml.safe_load(file)

    if not isinstance(data, dict) or not isinstance(data.get("payload"), list):
        raise ValueError("expected a YAML mapping with a payload list")

    seen = set()
    for number, rule in enumerate(data["payload"], start=1):
        if not isinstance(rule, str) or not rule.strip():
            raise ValueError(f"payload item {number} must be a non-empty string")
        prefix = rule.split(",", 1)[0].strip().upper()
        if prefix not in ALLOWED_PREFIXES:
            raise ValueError(f"unsupported rule prefix at item {number}: {prefix}")
        if rule in seen:
            raise ValueError(f"duplicate rule at item {number}: {rule}")
        seen.add(rule)

if __name__ == "__main__":
    try:
        main(sys.argv[1])
    except Exception as error:
        print(error, file=sys.stderr)
        sys.exit(1)

在仓库中添加 requirements.txt,内容声明 PyYAML 依赖;再配置工作流安装 Python 依赖并运行脚本。检查器中的规则前缀只是示例白名单,应依据你实际使用的 Mihomo 版本和 Provider 类型调整。尤其是 classical 集合,可能包含与域名列表不同的规则表达式,不能套用只检查域名集合的假设。严谨做法是按不同 behavior 编写对应校验逻辑,并为每类规则准备有效与无效样例。

结构检查之外,还应验证主配置是否引用了已定义的 Provider。可以在 CI 中解析主配置的 rule-providers 与 rules,收集所有 RULE-SET 使用的名称,并检查两边集合一致;同时核对每个 Provider 的策略名称是否出现在 proxy-groups 或合法的内置策略中。由于配置可能包含客户端模板变量、订阅生成字段或 Mihomo 特有语法,通用 YAML 解析器未必能够完整验证最终配置,因此这类静态检查应与目标 Mihomo 版本的配置测试配合,而不能互相替代。

把 Provider 文件、主配置片段和校验脚本放在同一变更中审查,并在合并前检查规则顺序。若能在测试环境中运行对应版本的 Mihomo 配置校验,再抽样检查连接日志,才算同时覆盖了格式、引用和实际分流。

更新策略、故障定位与长期维护

Provider 更新失败时,按链路逐层排查。首先确认主配置能够解析,随后查看 Mihomo 日志中是否出现对应 Provider 名称和请求错误,再检查 URL 是否能直接返回 YAML、客户端运行目录是否可写,以及更新间隔是否已经到期。若刚修改远端文件,客户端并不一定立刻重新请求;可以等待下一次更新周期,或按客户端提供的方式触发配置重载、内核重启或手动更新。不要在未保存备份的情况下频繁删除缓存文件,否则可能把可诊断的问题变成无法复现的状态。

规则更新后出现误分流,优先比较新旧版本的差异,而不是马上清空全部规则。检查新增后缀是否覆盖了不相关子域,关键词是否过宽,IP 段是否过期,以及规则是否被移动到更高优先级。对于服务商会动态调整 CDN 或 API 域名的应用,规则列表应以实际连接日志为依据,定期清理失效条目;静态规则集并不意味着它可以永久免维护。

还要为规则集制定简单的变更纪律:保留可读的提交记录,给关键版本打标签,记录规则来源与用途,不把临时排障条目长期留在公共集合里。对不同设备或不同环境有差异的规则,可以拆成多个 Provider,而不是用一份含有大量例外的集合承担所有职责。拆分也不宜过度;每个集合都应有清晰目的、稳定命名和对应的测试,否则维护成本会从主配置转移到一堆难以追踪的小文件上。

与部分同类客户端把规则与策略固化在界面、更新过程不透明的做法相比,Mihomo 的 Rule Providers 可以将规则源、匹配行为、缓存路径和更新周期显式写入 YAML,并借助 GitHub 的提交记录与 CI 把错误挡在发布之前。它需要一定的配置和维护意识,却能让个人设备与团队环境共享一套可审计、可回滚的规则流程。若你希望先获取兼容 Mihomo 的客户端,再按本文搭建自己的规则集,可以前往客户端下载页查看可用版本。

→ 立即免费下载 Clash,开启流畅上网新体验

前往本站下载页获取客户端