Clash自定义规则集托管GitHub:rule-providers工程实践指南
为什么用 GitHub 托管 Clash 自定义规则集
当配置文件里的 rules 越堆越长,问题通常不只是「看起来乱」:订阅更新可能覆盖手工修改,几台设备之间也容易出现规则不一致;想临时加一个域名,还得在主配置里找位置、确认顺序,再重新检查 YAML 缩进。对于需要长期维护分流策略的用户,更稳妥的做法是把规则内容拆出去,交给 rule-providers 按需加载,再把主配置留给策略组、DNS 和规则引用。
GitHub 适合作为规则集的公开托管位置:规则文件可以纳入 Git 版本控制,通过提交记录查看谁改了什么,也能利用分支或标签区分日常更新与稳定版本。Clash 主配置只需保存 provider 的 URL、缓存路径、规则类型和刷新周期;日常新增规则时,改动集中在规则仓库,不必反复编辑那份较大的订阅配置。这种拆分尤其适合多台设备共享规则、多人协作审阅,或需要回滚误改的场景。
先明确一个边界:GitHub 托管的是规则数据,不是代理节点,也不会自动替你设计分流策略。规则集负责描述「哪些流量匹配」,主配置里的 rules 则负责把命中的流量送到哪个策略组。即使 provider 已成功下载,如果引用顺序放错,或者策略组名称不存在,实际分流仍可能不符合预期。
先整理 GitHub 仓库:规则文件与版本要分层
建议单独建立一个公开的规则仓库,避免把访问令牌、订阅地址或个人配置误放进公开仓库。文件命名要能表达用途,例如 work-sites.yaml、media-domains.yaml、lan-cidrs.yaml,并在仓库说明中记录规则来源、维护人、更新日期和适用内核。将规则按职责拆分,比把所有条目塞进一个「杂项」文件更容易审核,也更方便定位某类误匹配。
clash-rules/
├── README.md
├── rules/
│ ├── work-sites.yaml
│ ├── media-domains.yaml
│ └── lan-cidrs.yaml
└── releases/
└── 2026-09-28/
日常维护可以直接使用默认分支的 Raw 文件地址,例如 https://raw.githubusercontent.com/用户名/仓库名/main/rules/work-sites.yaml。请将示例中的用户名、仓库名和文件路径替换成自己的实际值,并在浏览器中打开 URL,确认返回的是规则文件文本,而不是 GitHub 仓库网页、404 页面或登录页。公开仓库通常更适合被客户端直接拉取;私有仓库需要认证,而标准 provider URL 并不等同于自动携带 GitHub 登录状态,不能把私有仓库链接当作可直接使用的公开地址。
若希望减少外部访问 GitHub Raw 的不确定性,可以考虑由 GitHub Pages 或其他静态托管服务发布文件,但要验证最终 URL 能被客户端访问、响应内容是有效规则文件,并留意缓存刷新延迟。无论选哪种托管方式,都不应把 token、订阅密钥、内网主机清单等敏感内容放进公开规则仓库。
Mihomo rule-providers 配置示例与规则类型
在主配置的顶层添加 rule-providers,再在 rules 中使用 RULE-SET 引用。以下示例假设策略组名称 Work 已经存在;如果你的配置使用的是其他名称,应把它改成现有策略组的准确名称。YAML 对缩进敏感,建议使用空格而不是 Tab,并避免重复定义同名 provider。
rule-providers:
work-sites:
type: http
behavior: domain
format: yaml
url: "https://raw.githubusercontent.com/用户名/仓库名/main/rules/work-sites.yaml"
path: ./ruleset/work-sites.yaml
interval: 86400
rules:
- RULE-SET,work-sites,Work
- MATCH,PROXY
规则文件本身采用 YAML 格式时,可用 payload 保存条目:
payload:
- DOMAIN-SUFFIX,example.com
- DOMAIN,login.example.net
- DOMAIN-KEYWORD,workportal
behavior 要与文件内容匹配。domain 用于域名类规则;ipcidr 用于 IP 网段类规则;classical 适合包含多种传统规则类型的集合,例如域名、进程或网络类型等。不要仅因为文件名叫「IP 规则」就填写 ipcidr,实际条目才是判断依据。对于 YAML 以外的规则格式,要确认当前 Mihomo 版本支持该格式,并让 format 与文件内容一致;配置与文件格式不匹配时,常见结果是下载成功但解析失败。
| 配置项 | 作用 | 维护时要核对 |
|---|---|---|
type |
指定 provider 的加载方式,常见为 HTTP 远程文件或本地文件 | 远程文件使用 http;本地文件应按内核支持的语法配置 |
behavior |
声明规则集合的类型 | 域名、IP 网段与混合规则不可随意互换 |
format |
描述远程规则文件的序列化格式 | 确认是 YAML 还是当前内核支持的其他格式 |
url |
远程规则文件地址 | 用浏览器或命令行验证地址可访问且内容正确 |
path |
规则集在运行环境中的本地缓存路径 | 使用适合客户端运行环境的相对路径,避免写成另一台设备的绝对路径 |
interval |
远程规则集的自动更新间隔,单位为秒 | 按规则变化频率设置,不必为了「实时」设置过短 |
主配置中的规则遵循先匹配先处理的顺序,因此 RULE-SET,work-sites,Work 应放在可能先命中的宽泛规则之前。举例来说,如果上方已有会把大量域名送入其他策略组的规则,放在其后的 provider 规则就可能根本没有机会命中。MATCH 通常用于兜底,应放在规则列表末尾;不要把它放到自定义规则集之前,否则后续规则失去作用。
自动更新、GitHub 版本管理与回滚策略
interval: 86400 表示按秒配置一天的更新间隔。它并不意味着每次提交后所有客户端都会立即刷新:客户端可能尚未启动、当前网络无法访问托管地址,或仍处在下一次检查之前。Mihomo 通常会在 provider 更新周期到达时尝试获取新文件;不同客户端也可能提供手动更新规则集的入口。修改规则后,可在客户端的配置或规则集管理界面手动触发更新,再查看更新时间和运行日志确认结果。
选择刷新周期时,应结合规则变更频率与使用场景。稳定的内部域名清单可以使用较长周期;需要频繁修正的列表可缩短间隔,但过度频繁地访问远程仓库并不会让分流判断更准确,反而会增加请求次数和远端服务依赖。provider 的 path 是本地缓存位置,启动时或网络暂时不可用时,缓存可能影响你看到的规则版本;排查时要同时核对远程文件内容、客户端缓存路径和最近一次成功更新时间。
Git 分支上的文件地址会随着提交变化,适合持续更新;但这也意味着一个未经审核的提交可能立刻影响所有跟随该 URL 的设备。对稳定性要求较高时,可以在提交前使用 Pull Request 或独立测试分支审阅,再通过 Git 标签、版本目录或固定提交对应的文件地址发布经过验证的版本。这样一旦新规则造成误分流,就能把 URL 切回已知可用版本,而不必凭记忆逐条删除规则。
如果多个设备要使用同一套规则,尽量让它们指向同一个受控版本,并记录客户端内核版本、配置更新时间和规则仓库提交号。不要只依赖文件名判断版本:GitHub 默认分支上的同一路径可以被覆盖,URL 没变不代表文件内容没变。稳定环境可固定到版本化路径,测试设备再跟踪主分支;两种通道并行,既保留更新速度,也保留回退能力。
从下载失败到规则未命中:按层排查
出现异常时,先把问题拆成「配置解析」「远程获取」「规则匹配」「策略执行」四层。先检查客户端内核日志有没有 YAML 解析错误、provider 初始化失败或 HTTP 状态码;再用浏览器或命令行直接访问 URL,确认网络能到达托管服务。若响应是 404,优先检查仓库名、分支名、大小写和路径;如果收到的是 HTML 页面而非 YAML 内容,说明拿到的很可能是仓库页面 URL,不是 Raw 文件地址。
如果 provider 显示已加载,但目标流量仍走错策略,先确认规则文件是否包含目标域名对应的条目,再检查 behavior 与规则类型是否匹配、RULE-SET 中的 provider 名是否与定义完全一致,以及规则顺序是否被前面的规则截获。连接日志或客户端的规则命中详情可以帮助确认实际匹配项;测试时尽量使用具体域名和单一连接,避免只看「网站打不开」就同时改 DNS、节点和多条规则。
- provider 找不到:检查
rules中引用的名称是否与rule-providers下的键完全一致,包括大小写与连字符。 - 远程拉取失败:检查 Raw URL、设备网络、TLS 访问情况,以及客户端是否能访问 GitHub;同时确认远程仓库没有被设为私有。
- 解析规则失败:检查 YAML 缩进、顶层
payload结构、规则格式和behavior,并查看日志中的具体行号。 - 规则已加载却未命中:检查目标域名是否真的属于规则条目、是否被更早的规则匹配,以及应用连接是否使用了预期的代理内核。
- 修改后设备表现不一致:对照各设备的内核版本、provider 更新时间、本地缓存路径和实际规则文件版本。
修改规则后,先在测试配置或一台非关键设备上更新 provider,观察目标域名的命中记录与出口策略,再推广到其他设备。遇到无法复现的问题时,记录时间、客户端与内核版本、访问域名、provider 更新结果及命中策略;这组信息比「规则好像没生效」更有排障价值。也不要把整份配置、订阅 URL 或包含个人信息的日志公开贴到仓库和讨论区。
Clash rule-providers 常见问题
使用 rule-providers 一定要用 Mihomo 吗?
具体支持范围取决于运行的内核和配置语法。本文的 format、行为类型等示例按 Mihomo 兼容配置编写;老版本内核或其他 Clash 分支可能不支持相同字段。遇到「未知配置项」或 provider 类型报错时,先核对客户端当前选择的内核及其版本,不要只凭客户端名称判断兼容性。
GitHub 仓库必须设为公开吗?
如果客户端要通过普通 HTTP URL 直接获取规则文件,公开仓库通常是最简单的方式。私有仓库需要身份认证,而浏览器登录态不会自动附加到 Mihomo 的远程请求中。不要为了让客户端拉取文件而把个人令牌写进公开 YAML、配置截图或仓库提交记录;确实需要私有托管时,应选用支持安全认证的部署方案,并谨慎管理凭据。
提交了新规则,为什么客户端没有马上生效?
可能是自动更新间隔尚未到达、客户端还在使用缓存、远程地址不可达,或当前客户端没有自动重新载入已更新的 provider。先手动触发规则集更新并检查日志中的更新时间,再核对 URL 实际返回的内容。若规则已加载但流量仍不匹配,还需继续检查规则顺序和命中详情。
GitHub Raw 地址可以直接用于长期生产环境吗?
可以作为简单的公开托管方案,但要考虑 GitHub 访问可用性、缓存以及默认分支内容随提交变化等因素。对稳定性要求更高时,使用经审阅的发布版本或版本化文件,并保留上一版以便快速回退;同时在测试设备验证更新结果,不要把「URL 能打开」等同于「所有客户端均已成功更新」。
把规则集做成可审阅、可复用的工程资产
相比之下,一些同类代理客户端或传统手工配置方式,规则往往与主配置紧密耦合:多设备同步要反复复制粘贴,更新后难以确认改动来源,误加一条宽泛规则也可能影响整份配置。Clash 的 rule-providers 能把规则内容与主配置解耦,再借助 GitHub 的提交记录、分支和版本发布流程,让规则集更容易复用、审阅与回滚。无论是维护个人设备的域名清单,还是为团队配置一套稳定分流,都可以先从小范围规则开始,验证下载、命中和策略出口后逐步扩展。如果还没有合适的客户端,可前往客户端下载页查看不同平台的版本;选择支持 Mihomo 的客户端后,再按本文方法搭建自己的规则工作流。