Clash自定义 rule-providers 实战：GitHub托管与YAML规则集进阶配置

一、先理解 rule-providers：规则数据与规则策略分开管理

rule-providers 用来定义一份可单独更新的规则集：配置中描述规则集从哪里读取、按什么格式解释、缓存到哪里，以及多久检查一次；主配置的 rules 再通过 RULE-SET 引用它，并指定匹配后使用的策略。这样可以把频繁变化的域名或 IP 列表与节点、代理组及其他主配置分开维护。

规则集不是代理组，也不会自动决定代理出口。提供者里存放匹配条件，主配置中的引用行才指定动作。例如，规则集命中后可以交给 DIRECT、代理组或其他有效策略。若规则集已经成功加载，但引用行指向的策略名称不存在，仍可能造成配置错误或连接处理不符合预期。

配置位置	负责内容	维护时检查
`rule-providers`	定义来源、规则类型、文件格式、缓存路径和更新间隔	内核是否支持对应字段，远程文件是否可访问
规则集文件	保存域名、IP 段或传统规则列表	格式是否与 `behavior` 一致，内容是否符合预期
`rules`	按顺序引用规则集并指定出站策略	规则集名称和策略组名称是否准确，位置是否合适

二、用 GitHub 托管 YAML 规则集

GitHub 仓库可以保存规则文件的历史版本，便于比较修改、回退错误提交，并把规则数据与主配置分开。供内核读取时，应使用仓库文件的原始内容地址，而不是仓库首页、文件预览页或带有登录界面的网页地址。以下地址中的 OWNER、REPO 和文件路径需要替换成自己的仓库信息；这里仅展示地址结构，不提供可直接使用的规则源。

建议在仓库中采用稳定、清晰的目录结构，例如把自定义域名规则放在 rules/custom-domain.yaml，把 IP 段放在独立文件中。一个规则文件尽量只承担一种用途，文件名表达用途即可，不要把日期或临时测试结果直接当作永久文件名。修改默认分支或移动文件后，也要同步更新主配置中的原始内容地址。

YAML 文件结构与 behavior 对应关系

使用 YAML 格式时，规则内容放在顶层 payload 列表中。behavior 决定内核如何解释列表项目：domain 用于域名类条目，ipcidr 用于 IP 网段，classical 用于包含规则类型的传统规则列表。文件内容和提供者声明必须一致；不要把带有 DOMAIN-SUFFIX 前缀的传统规则行误当成纯域名列表。

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

上面是域名行为的示意文件：+.example.com 表示域名后缀匹配，full:login.example.org 表示完整域名匹配。示例域名只用于展示格式。若要加入新的域名，应确认目标是完整主机名还是整个后缀范围，避免把一个子域名需求扩大成整站规则。

若规则集需要混用域名、IP 段及其他规则类型，可将提供者设为 classical，在 payload 中写传统规则条件。例如：

payload:
  - 'DOMAIN,login.example.org'
  - 'DOMAIN-SUFFIX,example.com'
  - 'IP-CIDR,192.0.2.0/24,no-resolve'

具体规则类型及附加参数仍受内核支持范围限制。示例中的网段属于文档用途地址，不代表真实服务地址。不要把出站策略写进规则集条目；规则集被引用时，由主配置的 RULE-SET 行统一指定策略，便于在不改动规则数据的情况下调整分流动作。

三、主配置引用、更新间隔与规则优先级

下面的片段展示一个远程 YAML 域名规则集的声明和引用方式。地址需要换成自己托管文件的原始内容地址，策略名称则要替换为现有配置中确实存在的策略。path 指定本地缓存文件位置；相对路径通常从内核的工作目录解析，客户端的工作目录可能与配置文件所在目录不同，因此应确认实际运行环境能读写该目录。

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

rules:
  - DOMAIN,login.example.org,节点选择
  - RULE-SET,custom-direct,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

type: http 表示从远程地址获取文件；behavior: domain 对应纯域名规则；format: yaml 表示规则文件使用带有 payload 的 YAML 结构；interval: 86400 以秒为单位，表示按一天的间隔检查更新。更新间隔不是“保证某个时刻立刻生效”的定时承诺，网络可达性、内核运行状态和远端缓存都会影响实际更新时间。

规则列表按顺序处理，越靠前的匹配项越先获得机会。示例先放一个完整域名例外，再引用自定义集合，随后才是 GEOIP 和兜底规则。如果自定义集合里包含了某个域名，且它在前面的其他规则已经命中，那么后面的集合不会再改变该连接的出站结果。规则集拆分得再清楚，也不能代替检查主规则列表顺序。

RULE-SET 行放在前面：集合中的规则可以优先参与分流；应确认它不会覆盖必须优先处理的本地地址或特定域名例外。
RULE-SET 行放在后面：前面的宽泛规则可能已经匹配，集合中的条目便没有机会生效。
MATCH 放在末尾：它用于处理前面未命中的连接；放得过早会让后续规则无法发挥作用。
策略名称保持一致：节点选择 是示例名称，必须替换成现有 proxy-groups 中实际定义的名称；如果策略名包含空格或特殊字符，应检查 YAML 格式和名称是否逐字一致。

四、远程托管与本地规则的维护取舍

远程规则适合需要跨设备复用、希望集中发布更新的场景；本地规则适合只在单台设备使用、需要离线维护，或暂时不希望依赖外部下载的场景。mihomo 的规则提供者可以按支持的类型读取远程内容或本地文件，但两种方式的更新和故障表现不同。选择前先明确规则由谁维护、多久变化一次，以及远程不可用时需要怎样处理。

方式	优点	需要注意
`type: http`	规则与主配置分离，可按间隔获取远端更新，适合多设备共用	依赖网络和远端文件可访问；地址迁移或分支改名要同步调整
`type: file`	内容保存在本机，可离线使用，便于本地测试	要确认内核实际读取的路径及文件读写权限，更新需自行部署

GitHub 仓库可以设置为公开或私有。公开仓库的原始文件不需要把访问令牌写进配置；私有仓库的访问认证则要考虑客户端或内核是否支持、令牌如何安全保存以及令牌泄露后的撤销方式。不要把令牌直接拼进 URL，也不要把带凭据的配置上传到公开仓库、截图或问题反馈中。若要供多个设备读取，优先设计不暴露个人账户凭据的发布方式。

远程规则下载失败时，内核是否能继续使用已有缓存，取决于当前版本、缓存状态及配置。不能把缓存视为远程源永远可用的替代品。规则路径应稳定，设备升级或迁移时应备份需要长期保留的本地文件，并检查应用是否会清理临时目录。对重要规则，可在正式发布前保存已验证版本，以便更新内容异常时回滚。

更新节奏与内容审核

静态的个人例外规则通常不需要频繁轮询；每天更新一次可作为示例起点，实际间隔应结合规则变更频率与设备数量调整。过短的间隔不会让规则判断更准确，却会增加远程请求频率；过长则可能延迟修正。对变动频繁的列表，先确认来源更新节奏，再设置合理间隔，不要把刷新频率当作规则质量指标。

每次提交先检查新增、删除和修改的条目，避免把临时测试域名误发布到正式规则集。
文件名和提供者名称保持稳定；若调整字段、行为类型或文件格式，应先在测试配置中验证，再迁移所有引用。
规则文件只放匹配数据，不放订阅地址、节点凭据、个人访问令牌或其他敏感信息。
变更后记录修改目的和回退方法；当某个服务访问异常时，可快速判断是规则内容、规则优先级还是代理策略导致。

五、YAML 校验、配置生效与常见排错顺序

YAML 对缩进和数据结构敏感，先检查语法，再确认规则语义，最后验证运行时加载。缩进建议统一使用空格，不要在同一层级混用不一致的缩进。带有冒号、井号或特殊符号的字符串应根据上下文使用引号；URL 也建议加引号，减少特殊字符造成的解析歧义。列表中的每项必须处于同一缩进层级，payload: 下面应是列表，而不是把规则写成一个长字符串。

在安装了 mihomo 命令行程序的环境中，可使用配置测试命令检查配置文件是否能解析。将文件名换成实际配置路径：

mihomo -t -f config.yaml

测试通过只说明配置结构可以被当前内核解析，不代表远程源一定可访问，也不证明规则匹配结果符合预期。图形客户端通常会在更新配置或启动内核时提供日志；如果客户端生成了合并后的运行配置，应检查实际生效文件，而不是只检查原始订阅模板。

先看解析错误：检查缩进、冒号、引号、重复顶层键，以及 rule-providers 与 rules 是否处在正确层级。
再看提供者加载：核对远程地址能否返回规则文件，而不是仓库网页、登录页面或错误提示页；检查本地缓存路径是否可写。
核对格式与行为：domain、ipcidr、classical 必须与文件内容相符；YAML 文件要有预期的 payload 列表结构。
确认主规则引用：规则集名称与提供者定义的键完全一致，并且引用行位于预期的优先级位置。
验证实际连接：使用连接记录查看命中的规则和最终出站策略。修改规则后建立新连接，避免把旧连接状态误认为新配置结果。

如果配置解析成功但规则没有命中，先确认目标连接进入了内核，再检查内核实际识别到的是域名还是 IP。随后比对规则集行为类型、条目写法和主规则顺序。若规则命中但出站不对，重点检查 RULE-SET 后指定的策略是否存在、代理组当前选择是否正确。把“文件下载”“配置加载”“规则命中”“策略出站”分成四步验证，比只观察网页能否打开更容易定位问题。

最后，将个人规则作为可维护的数据源处理：保留清晰文件结构，控制更新频率，审查每次变更，并备份已验证版本。规则提供者的价值不在于把主配置拆得更复杂，而在于让规则内容、更新方式和分流策略各自清晰，出现异常时能快速定位和回退。