TAG官网 - TAG VPN套餐价格 | Bronze、Silver、Gold计划 - TAG Pro网络加速返回首页

Mihomo rule-providers 下载失败排查:定位出站、格式与路径问题

更新于 2026-11-17 · tagss11.buzz

简答:Mihomo rule-providers 下载失败,应先保留配置与缓存,再按第一条错误检查下载出站、HTTP 响应、文件格式和写入路径;下载成功后还要确认解析与加载。

定义:rule-providers 是 Mihomo 的规则集合配置项,可从 HTTP、本地文件或内联内容加载规则,与提供节点的 proxy-providers 不同。

先按第一条错误分流,暂时保留现有缓存

看到“initial rule provider”后跟“yaml: line”,先检查响应内容与格式,而不是先换节点。该组合可见于Mihomo 项目的规则源解析错误报告;它是特定报告中的原文片段,不代表所有版本都使用相同提示。本站是第三方使用指南站,本文只处理规则集合下载与更新问题。

最快的第一步:保留配置和缓存,只复现一个失败的规则集合,记录最先出现的完整错误。规则集合字段的含义参见Mihomo 规则集合文档。

当前现象优先检查完成这一分支的条件失败后的处理
首次下载失败,尚无可用文件实际 URL、下载出站、最终 GET 响应取得完整且格式正确的规则文件恢复修改前配置;不能把空文件当作规则缓存
已有缓存,仅本次更新失败旧文件是否仍被加载,再检查下载链路新文件解析和加载均通过保留旧副本;实际是否仍使用旧规则,以运行状态为准
响应已取得,但出现 YAML 或 payload 相关错误正文是否为规则文件,behavior 与 format 是否对应解析通过,规则集合可查询恢复原字段,转入格式核查
出现路径、权限或只读文件系统错误运行实例、HomeDir、目标目录和挂载权限实际运行身份能写入指定缓存位置恢复原路径或挂载设置,保留现有缓存

后文命令使用 Windows PowerShell;其他部署环境提供实例与路径核查方法,不假设它们共用同一套目录。

记录故障对象:只处理一个规则集合

先确认失败对象位于 rule-providers,避免把节点订阅更新与规则下载混在一起。规则集合文档列出了规则源名称、下载地址、缓存路径和下载代理等配置项。

  1. 打开当前生效配置,找到 rule-providers 下失败的名称,记录其 url、path、proxy、behavior、format。同时保存相关覆写内容,便于核对最终生效配置。
  2. 将当前配置复制到自己创建的非临时备份目录。根据实际 HomeDir 和 path 找到对应缓存;文件存在时另存一份,文件不存在时记录“首次下载,无缓存”。
  3. 进入所用面板的规则集合页面,找到该名称后触发一次更新,再到日志页面截取对应错误。入口位置和按钮名称以当前版本界面为准;没有单独更新功能时,使用该部署方式已有的加载流程。
  4. 保留第一条错误及其前后上下文,分享前隐藏 URL 查询参数、Authorization、控制接口密钥、用户名及私人目录名。

如果面板能连接控制接口,可依据Mihomo API 文档核对 /providers/rules 中是否存在目标集合,以及针对指定集合的更新接口;这不是主订阅更新接口。

  • 正常结果:错误能对应到一个确定的 provider 名称,而不是仅有“更新失败”的汇总提示。
  • 停止条件:无法确定生效配置或运行实例时,先完成下一节核查。
  • 恢复方式:每次只恢复本轮修改的配置项;需要恢复缓存时,先停止实际内核,再恢复到原位置。

先核对运行实例,再判断实际缓存路径

缓存路径要从正在运行的实例反查,不能根据下载目录或编辑器当前目录猜测。规则集合文档说明,path 必须唯一,并受 HomeDir 与 SAFE_PATHS 的安全路径限制;HomeDir 可由启动参数 -d 指定。

桌面环境:确认最终配置与内核实例

  • 入口:所用客户端的配置管理或运行信息页面,查找当前配置及数据目录相关功能;具体位置以当前版本为准。
  • 点击或打开的对象:当前启用的配置,以及对应的规则缓存位置。若启用了覆写,核对实际交给内核的 provider 字段。
  • 正常结果:配置内的 provider 名称、日志中的名称和缓存文件能对应起来。
  • 停止条件与恢复:找不到实际数据目录时,先保留配置,不批量删除搜索到的同名文件;路径修改无效时恢复原值。

systemd:从服务定义核对启动目录

先确认真实服务名。以下只读命令以 mihomo.service 为例,服务名不同时必须替换;读取受限日志可能需要管理员权限。systemctl 手册说明了 cat 和 show 的用途,Mihomo 创建运行服务文档提供了服务与日志检查方法。

systemctl cat mihomo.service
systemctl show mihomo.service -p ExecStart -p User -p Group -p MainPID
journalctl -u mihomo.service -o cat -n 80 --no-pager
  • 正常结果:能确认实际启动命令、运行进程及配置目录;服务文档中的示例目录不是所有安装方式的固定路径。
  • 停止条件与恢复:服务未找到或进程不对应时,先查真实服务;本节只读命令不需要恢复配置。

Docker:区分容器路径与宿主机路径

在具有 Docker 管理权限的终端执行只读检查,将占位名称替换为实际容器名。Docker 绑定挂载文档说明了宿主机 Source、容器 Destination,以及只读挂载的区别。

docker inspect YOUR_CONTAINER_NAME
  • 检查对象:启动参数和 Mounts,核对缓存所在容器目录映射到了哪个宿主机位置,以及是否允许写入。
  • 正常结果:知道应备份的宿主机目录,且缓存目录不是只读挂载。
  • 停止条件与恢复:只有宿主机下载成功,不能结束容器网络排查;修改挂载前保存原部署文件,失败时恢复原定义。

路由器封装环境:本页不提供固定路径

  • 先从封装工具当前界面或启动信息确认内核参数、配置位置和缓存位置,界面位置以当前版本为准。
  • 无法确认实际实例时,停止文件删除和权限修改,保留已有导出备份;后文桌面下载结果只能作为旁证。
  • 本页范围缩小为原生内核与已能确认启动参数的部署环境,不把桌面目录套用到路由器。

Windows 同机对照:检查最终 GET,而非只看浏览器

对同一个 URL 分别执行不使用应用层代理、显式使用本地代理的 GET,才能比较两条下载路径。以下命令依据curl 官方手册,跟随重定向并保存响应头和正文;它们不会覆盖 Mihomo 配置或缓存。

先在 PowerShell 中进入自己新建的诊断目录。将两条命令中的地址都替换为同一个失败 URL,将 127.0.0.1:7890 替换为实际 HTTP 或 mixed 代理端口;这里的端口只是占位值,不是控制接口端口。URL 应为正常远程域名,代理测试中的排除地址 127.0.0.2 不应是目标服务器。

curl.exe -q --noproxy "*" --location --connect-timeout 10 --max-time 45 --dump-header direct.headers.txt --output direct.body --write-out "HTTP=%{http_code} BYTES=%{size_download}\n" "https://rules.example.invalid/rules.yaml"
curl.exe -q --proxy "http://127.0.0.1:7890" --noproxy "127.0.0.2" --location --connect-timeout 10 --max-time 45 --dump-header proxy.headers.txt --output proxy.body --write-out "HTTP=%{http_code} BYTES=%{size_download}\n" "https://rules.example.invalid/rules.yaml"

这里的“直连”仅指 curl 不使用应用层代理。如果 TUN、透明转发或网关策略仍在接管流量,不能据此宣称获得了真实直连结果;在共享网络上保持现状并记录限制。需要暂停个人设备 TUN 做对照时,先保存原状态,完成后恢复。

实际观察下一步判断何时结束本轮测试
无应用层代理失败,显式代理取得正确规则优先检查 provider 的 proxy 字段,进入最小修改步骤同一 URL 经目标出站可重复取得正确内容
两边都失败按终端错误及 HTTP 响应检查域名、证书、访问授权或源站已定位到具体错误分支,不继续反复刷新
两边都成功,内核仍失败转查运行环境差异、最终配置、格式和文件写入确认不是 curl 本身的下载问题
HTTP 成功,但正文是网页或接口错误核对原始文件地址、授权和重定向目标取得规则正文,而不只是成功状态码

用文本编辑器打开响应头文件,查看最后一段响应;仅对 YAML 或 text 正文检查开头内容,二进制 MRS 按发布者说明核验。命令未使用 HEAD,也未将错误响应直接覆盖缓存。诊断文件可能含敏感响应信息,用完删除;这些命令不依赖前一终端定义的变量。

按网络错误与 HTTP 响应选择下一步

先解决下载链路,再修改规则格式。curl 手册分别说明了解析、连接、TLS 和 HTTP 传输相关结果;下表是按这些层次组织的诊断建议,不是对某个规则服务状态的判断。

错误类别可执行检查正常结果停止与恢复
超时、连接中断比较同机两条 GET;显式代理失败时,先核对本地监听端口和所选出站能完整取得响应,文件内容可继续核验两条路径均失败时,保留错误与原配置,转交网络或规则源维护方核查
域名解析失败核对 URL 主机名是否拼错,再比较相同运行环境中的解析结果目标域名能被当前下载环境解析确认解析失败后先处理该域名,不批量改写所有 DNS 设置
TLS 或证书验证失败检查设备时间、证书信任及是否存在组织网络的 HTTPS 检查正常完成证书验证并取得正文保留验证,交由网络管理员确认信任链;恢复诊断期间调整的网络设置
HTTP 401、403检查源站要求的授权、请求头和访问条件,核对配置是否遗漏必要 header合法授权下返回规则内容无有效授权时停止重试,恢复原请求头并联系维护方
HTTP 404核对分支、文件名和原始文件路径,而非仓库展示页实际资源存在且内容正确地址无法确认时保留旧缓存,不猜测替代下载地址
HTTP 429 或 5xx保留响应;若有 Retry-After,按其指示安排重试,并核查维护方说明后续请求取得完整规则仍失败时结束本轮测试,保留旧状态,避免连续点击更新

若响应是 304,应结合条件请求与本地副本判断,不能把没有正文的响应另存成新规则。上述 GET 对照命令没有主动添加缓存验证头;如果它们仍得到无正文响应,先核查响应链路,再处理缓存。

用实际正文核对 behavior、format、header 与大小限制

HTTP 下载完成不代表内容能被规则解析器接受,文件后缀也不能代替正文核验。内容结构见Mihomo 规则集合内容文档,字段与 MRS 限制见规则集合配置文档。

核查对象判断步骤通过条件不通过的处理
yaml 与 text检查发布者声明及真实结构;YAML 规则内容按文档核对 payload,纯文本按对应行为逐行核对format 与实际编码结构一致只更正该 provider 的格式字段;无效时恢复原值并重新核对正文
domain、ipcidr、classical判断条目是域名、IP 网段,还是带匹配类型的完整规则behavior 与条目语义对应停止尝试随机组合,取得发布者对应格式的文件
mrs核对是否确为 MRS 二进制,并检查声明的 behavior使用 domain 或 ipcidr;文档不支持 classical 与 mrs 的组合恢复原配置,改用发布者明确提供的兼容格式
header查看失败 provider 的请求头,依据规则源要求核对授权和 User-Agent发送必要且有效的请求头授权无法确认时结束测试;删除诊断材料中的令牌
size-limit在当前配置中检查是否设置了非零限制,对照已保存文件的实际字节数合法文件大小在配置限制内确认文件可信后再调整该项;无效时恢复原限制

文档规定 size-limit 单位为字节,默认 0 表示不限制。这里只提供配置核查入口,不编写未经来源证实的“超限报错原文”;旧内核对扩展字段的支持情况需核实。

最小修改:只调整下载出站,不替换整份配置

只有同机对照支持“某个出站能下载正确内容”时,才优先调整该 provider 的 proxy。Mihomo 文档将 proxy 定义为规则源下载与更新所使用的代理。

下面是结构示意,不是完整可运行配置。必须保留自己的 provider 名称和可信 URL;代理名称必须替换为现有、可用的出站名称;behavior 与 format 仅适用于已确认的 classical YAML 文件。合并到现有 rule-providers 下,不能额外创建第二个同名顶层键。

rule-providers:
  YOUR_EXISTING_PROVIDER:
    type: http
    url: "https://rules.example.invalid/rules.yaml"
    path: ./rules/YOUR_EXISTING_PROVIDER.yaml
    interval: 86400
    proxy: "REPLACE_WITH_EXISTING_PROXY_NAME"
    behavior: classical
    format: yaml
  1. 如果已有 URL、path、behavior、format 均正确,只修改 proxy 一项;缓存路径继续使用原路径。
  2. 按当前部署方式重新加载配置,再对目标 provider 更新一次;面板入口以当前版本为准。
  3. 检查下载响应、解析错误和规则集合状态,而不是仅看更新按钮是否结束转动。
  4. 若原错误不变或出现新错误,恢复原 proxy 值,按新的第一条错误转入格式或路径分支。

贯穿示例:从错误片段到成功判据

  • 假如日志先出现某个 provider 的 YAML 解析错误:先保存该配置与缓存,再用它的同一 URL 执行两次 GET。
  • 假如直连正文是 HTML,而显式代理正文是符合声明的 YAML:先保持格式字段不变,只将该 provider 的 proxy 指向已验证的现有出站。
  • 重新加载后,若正文正确但仍解析失败:结束下载出站分支,转查实际生效配置与正文结构。
  • 只有更新后解析通过、目标集合被加载,才算完成规则源故障修复;本例是条件推演,不是实测案例。

路径与缓存修复:先证明写入问题,再考虑替换文件

路径修复的目标是让实际内核在正确位置写入,而不是扩大整个目录的权限。规则集合路径说明要求 path 唯一,并限制在允许的安全路径内;容器只读挂载则应结合Docker 挂载说明处理。

  1. 将 path 按实际 HomeDir 解析,确认没有其他 provider 使用同一文件;父目录应已存在,并允许实际运行身份访问。
  2. 路径位于 HomeDir 外时,优先考虑恢复到 HomeDir 内的专用缓存目录。确需额外路径时,再按文档配置范围尽可能小的 SAFE_PATHS,并核对实际服务环境。
  3. 日志明确指向权限或只读问题时,只核查目标目录、运行身份和挂载方式。个人账户可以编辑文件,不能替代对服务运行身份的检查。
  4. 怀疑旧缓存内容异常时,先停止实际内核,把对应文件复制到非临时备份目录,再将原文件改名留存;仅对这一个 provider 重新下载。
  5. 新文件无法解析或加载时,停止内核,保留失败文件,恢复原路径下的旧副本及原配置,再启动验证。
  • 首次下载没有旧副本:修复来源、格式或写入问题后再获取文件,不能用创建空文件代替下载。
  • 已有缓存更新失败:保留副本,并查询当前加载状态;是否仍能使用旧规则,需要实际运行结果确认。
  • 如果备份曾放入系统临时目录,应先转存到非临时位置;重启或重新部署后发现备份丢失时,需要重新上传自己保存的副本。

四阶段验收与下一步阅读

规则源故障结束于下载、解析与加载恢复;实际命中是后续独立验收。Mihomo API 文档提供规则集合、规则和连接查询接口,路由规则文档说明 RULE-SET 引用与规则顺序。

阶段验收动作通过标准
下载检查最终 GET 响应与文件取得预期规则内容,而非网页、错误对象或不完整文件
解析重新加载后观察目标 provider 错误没有对应的格式或条目解析错误
加载查询规则集合状态目标名称存在,集合信息与预期一致
命中发起一条预期应命中的新连接,查看连接详情命中预期规则,并使用预期策略组或节点

规则与策略应分别记录:RULE-SET、DOMAIN-SUFFIX 等是匹配类型;策略组或节点是匹配后的处理目标。文件已加载但连接未命中时,转入规则顺序和引用核查,不继续清理下载缓存。

继续操作可按问题选择:需要确认配置来源,阅读Mihomo 配置文件切换与生效确认;集合已加载但分流不符合预期,阅读Mihomo 代理规则不生效排查;只有节点出站本身也异常时,再看Mihomo 节点显示但无法连接排查。

核验说明:资料访问日期为 2026-11-17。本文没有提供源站可用性、线路测速或服务状态结论;配置与命令包含明确占位内容,界面以当前版本为准。涉及凭据的下载文件、响应头和诊断记录应在使用后安全删除。

参考资料

以下均为正文已引用的一手资料,访问日期统一为 2026-11-17。

  • Mihomo 文档:规则集合(rule-provider);URL:https://wiki.metacubex.one/config/rule-providers/;访问日期:2026-11-17。
  • Mihomo 文档:规则集合内容;URL:https://wiki.metacubex.one/config/rule-providers/content/;访问日期:2026-11-17。
  • Mihomo 文档:API;URL:https://wiki.metacubex.one/api/;访问日期:2026-11-17。
  • Mihomo 文档:路由规则;URL:https://wiki.metacubex.one/config/rules/;访问日期:2026-11-17。
  • Mihomo 文档:创建运行服务;URL:https://wiki.metacubex.one/startup/service/;访问日期:2026-11-17。
  • curl 官方手册:curl — How To Use;URL:https://curl.se/docs/manpage.html;访问日期:2026-11-17。
  • systemd 官方手册:systemctl — Control the systemd system and service manager;URL:https://www.freedesktop.org/software/systemd/man/latest/systemctl.html;访问日期:2026-11-17。
  • Docker 官方文档:Bind mounts;URL:https://docs.docker.com/engine/storage/bind-mounts/;访问日期:2026-11-17。
  • Mihomo 项目问题报告:YAML parser error in windows #378;URL:https://github.com/MetaCubeX/mihomo/issues/378;访问日期:2026-11-17。仅用于核对该报告中的错误片段,不作为所有版本故障结论。

常见问题

Mihomo rule-providers 下载失败就是节点订阅失效吗?

不是。本文定义和字段依据见正文引用的规则集合文档:rule-providers 提供规则集合,proxy-providers 提供节点集合。应先根据日志确认失败对象,不能仅凭规则更新失败判断节点订阅状态。

浏览器能打开规则地址,为什么 Mihomo 仍然下载失败?

浏览器结果不能替代内核下载验证。按正文 curl 对照步骤取得最终 GET 正文,再核对运行环境、下载代理、授权、格式和缓存写入;浏览器显示的内容也可能是文件展示页,而非规则文件本身。

更新失败后应该直接删除所有规则缓存吗?

不建议把批量删除作为第一步。先确认实际缓存位置并保存副本,只检查一个失败集合。已有缓存是否仍被加载,应查询运行状态;确需替换文件时,按正文先停止内核、留存原文件,再验证新下载。

rule-providers 的 proxy 字段填本地端口还是代理名称?

这里填写配置中可用的代理出站名称,不是 curl 使用的本地 HTTP 端口。正文配置示意中的名称必须替换;字段含义见就近引用的 Mihomo 规则集合文档。

MRS 文件能使用 behavior: classical 吗?

正文引用的规则集合文档说明,MRS 的 behavior 支持 domain 或 ipcidr,不支持 classical。应使用发布者明确提供的兼容格式,不能只修改文件扩展名。

下载和加载都成功了,为什么分流仍然不符合预期?

下载、解析、加载与实际命中是不同阶段。集合已加载后,应检查 RULE-SET 引用名称、规则顺序和新连接的命中详情,并把匹配规则与使用的策略组或节点分开记录。

相关阅读

参考资料

  1. Mihomo 文档:规则集合(rule-provider);访问日期:2026-11-17
  2. Mihomo 文档:规则集合内容;访问日期:2026-11-17
  3. Mihomo 文档:路由规则;访问日期:2026-11-17
  4. Mihomo 文档:创建运行服务;访问日期:2026-11-17
  5. curl 官方手册:curl — How To Use;访问日期:2026-11-17(curl.se)
  6. Docker 官方文档:Bind mounts;访问日期:2026-11-17
  7. Mihomo 项目问题报告:YAML parser error in windows #378;访问日期:2026-11-17