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,通常应使用对应分支的原始文件地址或稳定的发布地址。

  1. 创建源文件。在仓库中建立 rules-source/streaming.txt,每行放置一个域名或域名后缀。使用统一写法,不要混入带路径的完整 URL、搜索参数和无关注释。
  2. 清洗并生成 YAML。脚本删除空行和重复项,检查域名格式,然后生成包含 payload 的规则文件。生成结果应固定排序,让 Git 提交只反映真实内容变化。
  3. 执行自动检查。检查文件是否存在、规则数量是否超过最低阈值、是否出现明显的 HTML 错误页,以及 YAML 是否能被解析。任何检查失败都应让工作流失败,不要继续发布。
  4. 提交并确认原始地址。工作流成功后,打开生成文件检查内容,再确认原始文件地址可以在未登录状态下访问。若仓库是私有的,普通 Clash 实例通常不能直接使用需要登录的资源。
  5. 写入主配置。将提供器放入 rule-providers,并在 rules 中引用同名提供器。先保留较长的 interval 进行测试,确认内容稳定后再调整更新周期。
  6. 重新载入并查看日志。不要只观察网页是否能打开,应在客户端的规则提供器页面或内核日志中确认文件下载成功、缓存路径正确、规则数量正常。
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。主配置中的控制接口密钥和本地认证信息也不应提交到公开仓库。

下载Clash