Mihomo 自定义 rule-providers 规则集：GitHub 托管与自动更新实战

为什么把自定义规则拆成 rule-providers？ 详解

当分流规则只有几条时，直接把它们写进主配置的 rules 很方便；但规则逐渐变多后，主配置往往会同时承担订阅参数、DNS、代理组和大量业务规则，修改一处就要重新检查整份 YAML。更麻烦的是，规则与主配置绑定在一起：想在多台设备间复用、回滚某次调整，或者把一组域名交给其他人维护，都不够清晰。Mihomo 的 rule-providers 可以把规则列表存放在独立文件中，再由主配置通过名称引用。主配置负责声明“从哪里获取、按什么类型解析、多久更新”，规则文件只负责写匹配项，两者各自维护。

这套方式适合管理个人常用域名、开发工具服务、家庭设备或某个应用的分流清单。它也能减少主配置与远端机场订阅之间的耦合：订阅更新时，只要你的规则引用仍在最终生效配置中，独立规则文件通常不需要跟着手动合并。不过，rule-provider 不是规则优先级的替代品，也不会自动推断某个域名应该走哪个代理组；它只提供规则集合，真正的策略仍由 rules 中的 RULE-SET 条目决定。

还要先确认客户端实际使用的是支持 rule-providers 的 Mihomo 内核。Clash Verge Rev、Mihomo Party 等图形客户端可以管理或加载 Mihomo 配置，但界面里的配置覆写、订阅转换和更新按钮并不完全相同。若你编辑的是订阅生成的配置，远端更新可能覆盖本地改动；建议先确认客户端的配置管理方式，再把自定义 provider 放到能随配置生效的本地配置或覆写层中。不要因为 YAML 能保存，就假设运行中的内核已经读取了它。

先分清三个部分：rule-providers 定义规则集的数据来源，GitHub 仓库保存规则文件，主配置里的 RULE-SET 决定匹配后使用的策略组。排障时分别检查这三处，比把所有问题都归咎于“规则没更新”更快。

在 GitHub 托管规则文件并声明 provider 全面解析

先创建一个公开的 GitHub 仓库，例如 clash-rules，并按用途拆分文件。小型个人仓库可以从简单结构开始：根目录放说明文件，rules/ 目录存放规则清单。文件名尽量表达用途，例如 github.yaml、developer-tools.yaml；不要把互不相关的域名全塞进一个名为 custom.yaml 的大文件。拆分后，更新记录更容易审阅，主配置也能按场景组合规则集。

以下示例采用 domain 行为和 YAML 格式，适合放域名类规则。请将仓库所有者、仓库名和分支替换成自己的实际值，并确保文件路径与 URL 完全对应：

payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN,api.github.com

这里的 payload 是 YAML 规则文件的列表入口。域名规则可以按 Mihomo 支持的规则写法表达；如果要放的是完整 Clash 规则，例如带策略条件的经典规则条目，应选择与文件内容相符的 behavior: classical，而不是把两种格式混在一个 provider 中。IP 网段清单则应采用适合 IP-CIDR 的行为，并在实际配置中确认地址类型和匹配语义。规则类型与文件内容不对应时，provider 可能解析失败，或者加载成功却没有命中预期流量。

在主配置中声明 provider，再于 rules 中引用它。下面的分组名 Proxy 只是示例，应替换成你自己的策略组名称：

rule-providers:
  github:
    type: http
    behavior: classical
    format: yaml
    path: ./ruleset/github.yaml
    url: https://raw.githubusercontent.com/your-name/clash-rules/main/rules/github.yaml
    interval: 86400

rules:
  - RULE-SET,github,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

type: http 表示通过 HTTP 或 HTTPS 获取规则文件；url 指向 GitHub 的 Raw 文件地址；path 是 Mihomo 在本地保存 provider 内容的路径；interval: 86400 表示以秒为单位设置更新间隔，即约一天检查一次。缓存路径所在目录需要能够由 Mihomo 写入。不同客户端的工作目录和配置存储方式可能不同，若日志提示无法写入或找不到缓存文件，不要只改规则 URL，也要检查客户端实际运行内核使用的目录与权限。

仓库中的 main 分支适合持续维护，提交新版本后，Raw 地址仍指向同一路径，provider 下次更新时就能取到新内容。若希望部署可复现、避免某次误提交立即影响所有设备，可以把 URL 中的分支名换成固定的提交哈希或版本标签；这样更新不会自动跟随最新提交，需要在确认规则变更后再改引用地址。公有仓库不需要把 GitHub Token 写进配置。不要把访问令牌、订阅链接、内部域名清单或其他凭据提交到公开仓库；私有仓库的认证配置也不应照搬公开 Raw 地址的示例。

小技巧：首次配置时先用一条容易验证的域名做测试，提交后在浏览器打开对应的 Raw URL，确认响应内容是规则文件而不是 GitHub 页面、404 提示或登录页。确认文件可访问，再让 Mihomo 下载，可以把“仓库地址写错”和“规则格式解析失败”分开排查。

规则优先级、策略组与配置部署 一次讲透

Mihomo 按 rules 从上到下检查，命中后就采用该条规则指定的策略。因此，provider 虽然写在主配置较前的位置，真正影响流量的仍是 RULE-SET 在 rules 列表中的顺序。需要优先代理的自定义域名集合，应放在可能提前匹配它们的宽泛规则之前；如果它排在 GEOIP,CN,DIRECT 或其他较宽规则之后，流量可能已经被前面的规则接走，自定义集合看起来就像“完全没生效”。

建议按照“精确例外、专用规则集、一般地区规则、兜底规则”的思路排列，而不是不断把新条目追加到列表末尾。举例来说，如果某个域名在更广泛的规则集里会被直连，但你明确希望它走代理，可以把更具体的规则放在宽规则之前；如果希望自定义集合只补充特定应用域名，也应避免把它写成覆盖范围过大的关键字规则。规则集越宽，越需要检查它是否抢先匹配与预期无关的子域名。

  • 先确认目标策略组：RULE-SET,github,Proxy 中的 Proxy 必须与配置里的策略组名称完全一致。组名拼错、使用了订阅刷新后已不存在的组名，可能导致配置校验失败或流量无法按预期选择出口。
  • 避免重复和相互遮蔽：同一域名若同时出现在多个集合中，先命中的那条规则决定结果。维护时记录规则集用途，并检查更靠前的规则是否已经覆盖了目标域名。
  • 保留兜底规则：像 MATCH,Proxy 这样的最终规则应处于列表末尾。若兜底规则提前出现，其后的 provider 引用就没有匹配机会。
  • 在最终配置中验证：如果客户端通过订阅合并、覆写或配置转换生成运行配置，应检查实际生效配置里是否仍有 provider 声明和对应的 RULE-SET 条目，而不只是查看自己编辑的源文件。

修改前建议备份当前配置，并先做一次语法检查。Mihomo 的配置校验入口会随客户端而异：有的客户端提供配置检查或重载按钮，有的需要查看内核日志。保存后观察日志中是否出现 provider 加载、下载或解析错误；只有配置重新加载成功，规则变更才算部署完成。若客户端会在每次订阅更新时重建配置，可以将 provider 放进持久化的覆写或本地配置层，并在订阅刷新后再次确认最终配置没有丢失。

  1. 准备规则文件：在本地编辑 YAML，检查缩进、列表符号和规则写法，再提交到 GitHub 仓库。
  2. 验证 Raw 地址：打开配置中的 url，确认能直接看到刚提交的文件内容，且地址中的仓库、分支和文件路径一致。
  3. 检查主配置引用：核对 provider 名称、行为类型、缓存路径、更新间隔，以及 RULE-SET 使用的策略组名。
  4. 重新加载并观察日志：通过客户端的配置检查、重载或内核重启功能应用变更，确认 provider 下载和解析成功。
  5. 用实际连接验证：访问规则集中的目标域名，在连接记录或日志中查看命中的规则和最终策略组，不要仅凭网页能否打开判断是否命中。

自动更新、缓存验证与常见排障 深入理解

interval 控制 Mihomo 检查远端规则的更新频率，但它不等于“每次访问都会请求 GitHub”，也不保证远端文件一提交就立即应用。缓存文件让内核能够在一定条件下继续使用已获取的数据；远端网络不可达、Raw URL 返回错误或规则文件解析失败时，运行结果还会受到已有缓存和当前客户端处理方式影响。需要立刻验证变更时，应使用客户端提供的 provider 更新操作（若有），或者按客户端支持的方式重新加载配置，并结合日志确认实际更新结果。

排查时建议从源文件一路追到流量命中，不要一次性改 URL、行为类型、规则顺序和策略组。先确认 GitHub Raw 地址返回的是预期文件，再确认缓存路径可写、provider 能被加载，接着核对规则列表顺序，最后查看目标连接记录。这样的顺序能区分下载失败、解析失败、规则未命中与策略选择错误，减少“换个节点试试”带来的无效操作。

  • 日志提示下载失败：先在浏览器中访问 Raw URL，检查仓库是否公开、分支和路径是否正确，以及当前网络能否访问 GitHub。若浏览器显示 404、HTML 页面或认证跳转，Mihomo 得到的就不是预期规则内容。
  • provider 加载或解析报错：检查 YAML 缩进、payload 列表结构、规则项格式，以及 behavior 和实际内容是否匹配。只修改一个问题后重载，便于判断是哪项修复起了作用。
  • 日志显示已加载，但流量没有命中：检查域名是否真的属于规则集、目标应用实际连接的主机名是什么，以及前面是否已有更宽泛的规则先命中。某些应用还会连接独立的 API 或 CDN 域名，不能只根据首页域名推断整项服务的流量。
  • 编辑文件后设备仍使用旧规则：确认提交已经进入 URL 指向的分支或版本，并检查客户端是否触发 provider 更新。固定提交哈希的地址不会自动跟随新提交，切换到固定版本后应同步维护版本引用。
  • 订阅刷新后规则消失：查看客户端是否重新生成了主配置，以及本地覆写是否仍被应用。把自定义内容放在订阅更新能够保留的位置，比每次刷新后手工重贴更可靠。

GitHub 仓库本身也应按配置资产来管理。每次提交只做一类清晰变更，在提交说明中写明新增、删除或调整的域名及原因；改动后先检查差异，避免误删整段列表或把测试域名一并发布。重要规则可以通过版本标签或固定提交地址留存可回滚版本，发现误分流时恢复旧版，再逐条定位问题。多人协作时，不要直接在主分支上混合未经验证的改动；先在分支中测试 Raw 文件与规则命中，再合并发布。这样既能利用自动更新减少维护操作，也保留了人工审阅和回退的空间。

不同 Clash 图形客户端在 provider 更新按钮、订阅覆写和日志展示上各有差异，有的更偏向一键使用，有的则需要用户自行追踪配置来源；直接把规则长期塞进主配置虽然直观，却会让版本回滚和跨设备复用变得繁琐。Clash 的优势在于把 Mihomo 客户端使用、规则配置与排障流程整理成更容易查阅的中文资料，方便你按步骤核对配置结构、更新状态和连接命中结果。若你准备在桌面端实际搭建这套规则工作流，可以先前往下载适合设备的客户端，再按本文方法逐项验证。