· 订阅与配置 · 预计阅读 9 分钟

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

通过 rule-providers 将自定义分流规则从 Clash 主配置中拆分，使用 YAML 编写规则并托管到 GitHub。本文介绍关键字段、自动更新、规则优先级与故障排查，帮助开发者实现可版本控制、易维护的规则集管理流程。

一、为什么把规则拆成 rule-providers

随着自定义分流规则增加，主配置里的 rules 会越来越长。把规则直接写在主配置中，短期内便于查看；但当规则由多人维护、需要单独审阅，或者要在多份配置之间复用时，修改和发布就容易互相干扰。mihomo 的 rule-providers 可以把规则内容放到独立文件，再由主配置按名称引用。

这类提供者只负责加载规则，不负责创建代理节点或策略组。主配置仍需要定义可用的出站策略，并通过 RULE-SET 指定命中规则后交给哪个策略。拆分后，规则文件可以独立进行版本控制；主配置则保留提供者地址、匹配类型、更新间隔和规则顺序等运行设置。

一个规则集通常由三部分组成：GitHub 上的规则文件、主配置中的 rule-providers 声明，以及 rules 中的 RULE-SET 引用。缺少其中任一环节，都可能出现文件能访问但规则不生效的情况。建议先从一组少量、容易验证的域名开始，再逐步扩展到较大的列表。

二、用 YAML 编写规则并托管到 GitHub

先按内容选择 behavior

behavior 告诉 mihomo 如何解释规则文件中的每一项。规则文件一般以顶层 payload 列表保存条目；不要把一整份 Clash 主配置直接放进来，也不要把节点列表误当作规则集。

下面是一个 domain 类型的独立规则文件示例。将其保存为仓库中的 rules/custom-domains.yaml：

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

域名规则不需要写成完整主配置中的 rules: 条目。提交前检查 YAML 缩进、引号和列表符号；同一个仓库可以按用途拆成多个文件，例如广告域名、开发服务域名或需要特定策略的域名。为了便于审阅，建议每组规则有简短说明，并避免把同一条目反复复制到多个文件。

建立仓库并使用 Raw 文件地址

创建 GitHub 仓库后，将规则文件提交到固定目录。若使用公开仓库，mihomo 的 url 应指向文件的原始内容地址，而不是仓库首页、文件预览页或下载压缩包。常见地址结构如下：

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

把 OWNER、REPOSITORY 和 BRANCH 替换为仓库所有者、仓库名和分支名。实际部署前，用浏览器或命令行打开该地址，确认返回的是 YAML 文本，而不是 GitHub 登录页、404 页面或 HTML 错误页。公开规则仓库不应包含订阅链接、访问令牌、个人 IP 清单等敏感信息。

分支地址便于持续更新：提交新规则后，提供者在下次成功拉取时可以获得新内容。若更重视固定版本和可复现性，可使用指向特定提交的 Raw 地址；但这类地址不会随着分支前进自动取得后续修改，需要在主配置中主动更新提交版本。

三、在主配置中声明提供者并设置自动更新

下面是一个局部配置示例。假设策略组已经存在，名称为 Proxy；如果你的策略组名称不同，必须将示例中的引用替换为主配置中的真实名称。此片段不能单独作为完整配置使用。

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

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

RULE-SET,custom-domains,Proxy 中的 custom-domains 必须与提供者声明的键名完全一致；最后一项 Proxy 必须是已经定义的策略组或可用出站。规则按 rules 中的顺序匹配，前面的规则命中后，后续规则不会再决定该连接的策略。因此，自定义规则集通常应放在相应通用域名规则、IP 规则和最终兜底项之前。

四、验证更新、匹配结果与规则优先级

先验证配置能解析、文件能下载

先备份正在使用的配置，再将示例改成自己的地址和策略组名称。若运行的是 mihomo 命令行版本，可在测试配置时使用该版本支持的配置检查方式，例如通过 mihomo -t -f config.yaml 检查语法；图形客户端则查看配置校验结果、启动日志或规则提供者状态页。不同版本与客户端的菜单名称可能不同，应以实际界面显示为准。

  1. 检查远程地址：确认 Raw 地址可访问，文件内容包含预期的 payload，且没有多余的 Markdown 代码围栏。
  2. 检查本地路径：确认 path 对应位置可写。若客户端使用沙盒或独立服务运行，不能仅凭用户账户能访问该目录就推断内核也能写入。
  3. 检查提供者状态：查看日志中是否有下载失败、YAML 解析失败或规则集加载失败等信息。记录时间和错误原文，便于与仓库提交时间对照。
  4. 检查实际命中：访问一条明确位于规则集中的域名，在连接详情中核对命中的规则名称和出站策略，而不是只看策略组当前选中项。

规则更新通常受配置加载、定时更新和网络可达性影响。刚提交 GitHub 修改后，客户端可能仍在使用本地缓存；需要等待配置中设定的间隔，或使用客户端提供的规则提供者更新操作。若更新操作只重新加载主配置、不触发提供者下载，应以日志和提供者状态确认结果，不要仅凭点击按钮后页面刷新就认定规则已经更新。

用最小规则集检查优先级

规则集命中后使用的是引用行中指定的策略。若同一域名在更早的规则中已经匹配，例如先前存在一个范围更大的 DOMAIN-SUFFIX 规则，那么后面的自定义规则集可能没有机会生效。排查时先搜索主配置内所有可能覆盖目标域名的规则，再检查它们的先后位置。

如果连接列表显示规则命中正确、策略也正确，但访问仍失败，问题可能在节点、DNS、网络连接或目标服务，而不一定是规则提供者。先确认实际出站和目标域名，再进行单变量测试；不要同时改规则、DNS 和节点设置，否则很难定位变化来源。

五、常见故障排查与长期维护

现象优先检查项
下载返回 404核对仓库所有者、仓库名、分支、目录和文件名；确认文件已提交到该分支。
YAML 解析失败检查缩进、冒号、列表符号及 payload 是否位于顶层；确认远程响应不是 HTML 页面。
提供者加载成功但没有预期命中核对 behavior 与条目格式、RULE-SET 名称、规则顺序和目标策略组。
修改仓库后客户端仍使用旧规则检查更新间隔、提供者更新时间、本地缓存及客户端是否实际触发远程刷新。
桌面客户端能更新，重启后配置丢失确认编辑的是持久覆写配置，而不是每次由订阅生成的临时运行文件；检查客户端的合并顺序。

长期维护时，建议将规则按用途拆分，并采用可读的文件名，例如 custom-domains.yaml、work-networks.yaml。每次提交只处理一类改动，写清变更原因；提交后先用测试配置验证，再观察客户端是否成功下载和命中。使用分支保护或代码审阅，可以降低误删关键规则、提交错误格式的风险。

更新间隔不宜设得过短。规则列表很少变化时，数小时或一天更新一次通常更容易管理；若确实需要快速发布变更，应先评估 GitHub Raw 的可用性、客户端刷新方式及本地缓存行为，而不是单纯把间隔改成几秒。远程服务暂时不可用时，本地缓存是否继续使用取决于内核和当前状态，重要配置应有备份，并保留可回滚的 Git 提交。

最后，公开仓库的地址和内容都可被访问，不要把包含个人信息或服务凭据的规则文件公开。使用私有仓库时，也不要把个人访问令牌直接写进可共享的主配置；客户端是否支持安全的认证凭据管理需要单独确认。通过拆分文件、固定规则格式、验证更新日志和检查实际命中，可以让自定义分流规则更易审阅、复用和回滚，同时避免把远程规则托管误当作无需验证的自动化。

Clash Mac版安装包