Clash rule-providers进阶配置:用GitHub构建自动化规则集
规则集一旦从几条手工规则扩展到多个域名、网络段和服务分类,直接把内容全部写进主配置就会变得难以维护。修改一条域名规则需要重新检查 YAML 缩进,多个客户端之间也容易出现版本不一致。rule-providers 可以把规则数据拆成独立文件,由 Clash 或 Mihomo 按需加载、缓存和定期更新;再配合 GitHub 仓库与 GitHub Actions,就能把规则生成、校验和发布流程纳入版本控制。
这套方案的核心不是把所有规则搬到 GitHub,而是建立清晰的职责边界:主配置负责端口、DNS、策略组和规则引用,规则仓库负责维护原始数据与生成结果,Actions 负责自动检查和发布。这样既能保留 Clash 配置的可读性,也能通过提交记录追踪每次规则变化,出现误分流时可以快速回退到上一版。
理解 rule-providers 的加载与匹配链路
rule-providers 是规则数据的独立来源定义。它通常包含一个名称、远程地址、本地缓存路径、规则行为和更新间隔。Clash 读取配置后,会根据提供器定义下载或读取规则文件,将其保存到本地路径;在 rules 段中通过 RULE-SET 引用这个提供器。真正决定流量走向的仍然是规则顺序和策略组,而不是提供器本身。
可以把一条连接的处理过程拆成四步。第一步,应用通过系统代理、TUN 或本地监听端口把请求交给内核;第二步,内核取得域名、目标 IP、端口等信息;第三步,内核按照 rules 从上到下检查条件;第四步,命中的 RULE-SET 把连接交给指定策略。规则集只负责提供一批可匹配的条件,不能单独决定使用哪个节点。
rule-providers:
services:
type: http
behavior: domain
format: yaml
path: ./rules/services.yaml
url: https://raw.githubusercontent.com/example/rules/main/services.yaml
interval: 86400
rules:
- RULE-SET,services,代理选择
- MATCH,DIRECT
上面的示例中,services 是提供器名称,path 是本地缓存文件,url 是远程资源地址,interval 表示自动更新间隔,单位通常为秒。规则段中的第一个参数必须与提供器名称完全一致,包含大小写、连字符和下划线差异。名称写错时,配置可能可以载入,但规则集会显示为空或在运行日志中报找不到提供器。
behavior 与 format 怎样选择
behavior 描述规则数据的匹配类型,常见值包括 domain、classical 和 ipcidr。域名型规则适合维护域名或域名后缀;IP 段型规则适合维护 CIDR 网络;经典型规则则可以包含更丰富的 Clash 规则行,例如域名、关键词、端口和 IP 条件。提供器的行为必须与文件内容保持一致,否则即使文件下载成功,也可能无法按预期匹配。
| 类型 | 适用数据 | 示例内容 | 注意事项 |
|---|---|---|---|
domain |
域名或域名后缀 | +example.com |
适合站点分类,文件内容应保持统一格式 |
ipcidr |
IPv4、IPv6 网段 | 203.0.113.0/24 |
通常需要在连接已取得目标 IP 后才能匹配 |
classical |
完整 Clash 规则行 | DOMAIN-SUFFIX,example.com |
表达能力较强,但格式错误更容易导致加载失败 |
format 则描述文件的封装格式。常见的 YAML 规则文件通常带有 payload 字段;纯文本规则通常是一行一条内容;部分 Mihomo 版本还支持经过编译的二进制规则格式。生成仓库时应固定一种格式,不要让同一个 URL 有时返回 YAML、有时返回纯文本。远程文件扩展名、format 和实际内容最好保持一致,便于人工检查和自动校验。
拆分规则集合并设计优先级
规则拆分的第一原则是按用途划分,而不是按文件数量越多越好。可以将经常一起变更的域名放在同一集合中,例如工作服务、流媒体、广告过滤、局域网地址和国内常用服务。一个规则集如果同时包含完全不同的策略需求,后续很容易出现“为了修改一个域名而影响另一类流量”的问题。
建议先建立稳定的目录结构,再为每个集合确定唯一职责:
rules/
domain/
streaming.yaml
work.yaml
direct.yaml
ipcidr/
private.yaml
cloud.yaml
classical/
reject.yaml
special-port.yaml
主配置中的提供器名称也应体现用途,例如 rule-streaming、rule-work 和 rule-private。名称不要使用模糊的 temp、new 或 test2,因为规则仓库长期维护后,模糊名称会让人无法判断它应该放在规则链的什么位置。
规则顺序决定实际优先级
Clash 规则通常从上到下匹配,连接命中第一条符合条件的规则后就停止继续检查。因此,规则集之间的优先级由 rules 中的排列位置决定。更具体、更需要优先处理的规则应放在前面,范围宽泛的规则放在后面,MATCH 必须作为最后的兜底项。
rules:
- RULE-SET,rule-reject,REJECT
- DOMAIN,internal.example.com,DIRECT
- RULE-SET,rule-work,工作策略
- RULE-SET,rule-streaming,流媒体
- RULE-SET,rule-private,DIRECT
- GEOIP,private,DIRECT,no-resolve
- MATCH,代理选择
例如,一个域名同时出现在广告拒绝集合和工作服务集合中,排在前面的规则会生效。若希望工作域名始终可访问,就不能只依赖两个集合的内容,还要明确工作规则与拒绝规则的先后关系。规则集之间出现重叠并不一定是错误,但必须是有意设计,并且应该在仓库测试中固定这种预期。
no-resolve 常用于不希望规则触发额外 DNS 解析的 IP 类规则。是否添加它要结合内核的 DNS 模式和规则用途判断。对域名规则来说,通常应优先使用域名条件完成匹配;对 IP 段规则来说,如果没有目标 IP,内核可能无法进行判断。不要为了“减少 DNS 请求”而给所有规则机械添加 no-resolve,否则可能让本应命中的 IP 规则失效。
用 GitHub Actions 自动生成和发布规则
GitHub 仓库适合保存规则源文件、生成脚本和最终发布文件。建议将“人工维护内容”和“自动产物”分开:人工只编辑白名单、黑名单或分类源文件,Actions 在每次提交后执行去重、格式化、语法检查和文件生成,最后把稳定路径的规则文件发布出来。主配置只引用生成后的固定 URL,不直接依赖某个临时分支或个人电脑上的文件。
一个简单的仓库可以包含以下文件:
rules-source/
streaming.txt
work.txt
reject.txt
scripts/
build-rules.py
rules/
streaming.yaml
work.yaml
reject.yaml
.github/
workflows/
build-rules.yml
规则源文件可以采用一行一个域名的简单格式,并在生成阶段删除空行、注释和重复项。对于来自多个来源的规则,还可以在脚本中统一转换大小写、去掉协议前缀、检查非法字符,并根据不同文件输出不同的 behavior。生成 YAML 时要正确处理引号、冒号和特殊字符,不能只通过字符串拼接制造看似合法的文件。
下面是一份用于说明流程的 Actions 配置。它在提交到主分支时运行,也支持手动触发;具体 Action 版本和运行环境应根据仓库实际情况维护:
name: build-rules
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Build rule files
run: python scripts/build-rules.py
- name: Check generated files
run: python scripts/check-rules.py
- name: Commit changes
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add rules/
git diff --cached --quiet || git commit -m "build: update rules"
git push
如果生成脚本会读取外部订阅或第三方列表,应增加超时、失败退出和内容大小限制。外部数据暂时不可用时,不要把空文件发布为最新规则,否则 Clash 下一次更新可能会把原有缓存替换成空集合。更稳妥的做法是先生成到临时目录,通过数量检查和格式检查后,再覆盖正式目录。
动手搭建一个可更新的规则集
下面以一个域名型规则集为例,演示从源文件到 Clash 配置的完整连接。操作前先准备一个可以访问的规则仓库,并确认最终发布地址能够直接返回文件内容,而不是返回网页 HTML。GitHub 仓库中的普通页面地址不能直接作为规则 URL,通常应使用对应分支的原始文件地址或稳定的发布地址。
- 创建源文件。在仓库中建立
rules-source/streaming.txt,每行放置一个域名或域名后缀。使用统一写法,不要混入带路径的完整 URL、搜索参数和无关注释。 - 清洗并生成 YAML。脚本删除空行和重复项,检查域名格式,然后生成包含
payload的规则文件。生成结果应固定排序,让 Git 提交只反映真实内容变化。 - 执行自动检查。检查文件是否存在、规则数量是否超过最低阈值、是否出现明显的 HTML 错误页,以及 YAML 是否能被解析。任何检查失败都应让工作流失败,不要继续发布。
- 提交并确认原始地址。工作流成功后,打开生成文件检查内容,再确认原始文件地址可以在未登录状态下访问。若仓库是私有的,普通 Clash 实例通常不能直接使用需要登录的资源。
- 写入主配置。将提供器放入
rule-providers,并在rules中引用同名提供器。先保留较长的interval进行测试,确认内容稳定后再调整更新周期。 - 重新载入并查看日志。不要只观察网页是否能打开,应在客户端的规则提供器页面或内核日志中确认文件下载成功、缓存路径正确、规则数量正常。
rule-providers:
rule-streaming:
type: http
behavior: domain
format: yaml
path: ./rules/rule-streaming.yaml
url: https://raw.githubusercontent.com/example/rules/main/rules/streaming.yaml
interval: 43200
proxy-groups:
- name: 流媒体
type: select
proxies:
- 自动选择
- DIRECT
rules:
- RULE-SET,rule-streaming,流媒体
- MATCH,代理选择
如果规则文件采用经典格式,提供器应改用相匹配的 behavior 和文件内容。例如文件可以包含:
payload:
- DOMAIN-SUFFIX,example.com
- DOMAIN-KEYWORD,video
- DOMAIN,api.example.net
不同内核对规则提供器的格式细节可能存在差异。遇到文件下载成功但规则数量为零时,优先检查 behavior、format 和 payload 层级;遇到配置解析失败时,检查 YAML 缩进、重复键和不可见字符。不要仅凭浏览器打开文件正常,就判断 Clash 一定能够加载,因为浏览器可以显示文本,而内核需要按照指定格式解析。
缓存、更新与故障排查
规则提供器通常会把远程文件保存到 path 指定的位置。缓存的意义是让内核在网络暂时不可用时仍可以使用上一份规则,同时减少每次启动都下载远程文件的压力。缓存路径应放在客户端有权限写入的目录,且不同提供器不能共用同一个文件名,否则可能发生内容相互覆盖。
interval 不是 GitHub Actions 的构建周期,而是 Clash 内核检查远程规则的周期。两者应分别设计:Actions 可以在源文件变化后立即生成新文件,内核则根据自己的间隔拉取。若内核更新过于频繁,可能遇到网络限制或重复下载;若间隔设置过长,仓库虽然已经更新,客户端仍会继续使用旧缓存。测试阶段可以手动执行规则更新,稳定后再采用合理的小时级周期。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 提供器显示下载失败 | URL、网络、证书和响应状态 | 确认地址返回规则文件而非网页或重定向登录页 |
| 下载成功但规则数为零 | behavior、format、payload | 让文件封装格式与提供器声明保持一致 |
| 规则命中但流量走错策略 | rules 顺序和策略组名称 | 检查是否被更早规则或错误的策略引用截断 |
| 更新后规则突然变少 | Actions 产物和源数据 | 增加最低数量检查,失败时保留上一版文件 |
| 本地文件无法保存 | path 权限和目录位置 | 改用客户端可写目录,避免指向只读安装目录 |
排查时可以先把远程 URL 临时替换为本地文件,判断问题来自规则内容还是网络下载。如果本地文件可以加载,远程文件失败,重点检查原始地址、代理连通性、TLS 证书和缓存更新。如果远程下载成功但命中结果不正确,则应在连接记录中查看最终命中的规则,并逐条核对提供器名称、规则顺序和策略组名称。
还要注意 GitHub Raw 或其他静态文件服务可能存在缓存。提交完成后立即访问时,边缘节点不一定已经返回最新内容。不要通过不断修改 URL 参数规避缓存,这会让配置失去稳定地址;更好的做法是等待缓存刷新,并在发布流程中使用版本号、发布目录或明确的变更记录。对于必须快速回退的规则,可以保留上一版本文件,并让主配置在验证新版本后再切换。
常见问题
rule-providers 能替代 rules 吗?
不能完全替代。rule-providers 负责定义外部或本地规则数据来源,rules 负责规定匹配顺序和命中后的策略。即使提供器文件已经下载,如果没有在 rules 中使用 RULE-SET 引用,它也不会自动参与分流。通常应把长期维护的大型集合放入提供器,把少量必须优先处理的例外规则直接写在主配置中。
为什么仓库页面能打开,Clash 却无法更新?
仓库网页地址返回的是 HTML 页面,不是规则文件本身。Clash 需要获取可直接解析的文本或规则格式,因此应使用能够返回原始文件内容的稳定地址。确认地址时,可以使用命令行查看响应头和内容开头,检查状态码是否为成功,并确认没有登录跳转、访问限制或错误页面。
自动更新后规则变空,怎样避免?
在 GitHub Actions 中增加规则数量、文件大小和格式检查,生成结果不符合最低要求时直接让工作流失败。不要在检查失败后覆盖正式发布文件,也不要让客户端无条件接受明显为空的远程响应。保留上一份有效规则和可回退提交,可以把外部数据源中断的影响降到最低。
公开规则仓库会泄露订阅信息吗?
规则仓库本身不必包含订阅地址、节点密码或账户令牌。将公开规则与私有节点配置分离,只发布域名、IP 段等可公开数据;需要访问私有源时使用仓库 Secrets,并检查 Actions 日志是否打印了完整 URL。主配置中的控制接口密钥和本地认证信息也不应提交到公开仓库。