Mihomo rule-providers 下载失败排查:定位出站、格式与路径问题
简答: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,避免把节点订阅更新与规则下载混在一起。规则集合文档列出了规则源名称、下载地址、缓存路径和下载代理等配置项。
- 打开当前生效配置,找到
rule-providers下失败的名称,记录其url、path、proxy、behavior、format。同时保存相关覆写内容,便于核对最终生效配置。 - 将当前配置复制到自己创建的非临时备份目录。根据实际 HomeDir 和 path 找到对应缓存;文件存在时另存一份,文件不存在时记录“首次下载,无缓存”。
- 进入所用面板的规则集合页面,找到该名称后触发一次更新,再到日志页面截取对应错误。入口位置和按钮名称以当前版本界面为准;没有单独更新功能时,使用该部署方式已有的加载流程。
- 保留第一条错误及其前后上下文,分享前隐藏 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- 如果已有 URL、path、behavior、format 均正确,只修改 proxy 一项;缓存路径继续使用原路径。
- 按当前部署方式重新加载配置,再对目标 provider 更新一次;面板入口以当前版本为准。
- 检查下载响应、解析错误和规则集合状态,而不是仅看更新按钮是否结束转动。
- 若原错误不变或出现新错误,恢复原 proxy 值,按新的第一条错误转入格式或路径分支。
贯穿示例:从错误片段到成功判据
- 假如日志先出现某个 provider 的 YAML 解析错误:先保存该配置与缓存,再用它的同一 URL 执行两次 GET。
- 假如直连正文是 HTML,而显式代理正文是符合声明的 YAML:先保持格式字段不变,只将该 provider 的 proxy 指向已验证的现有出站。
- 重新加载后,若正文正确但仍解析失败:结束下载出站分支,转查实际生效配置与正文结构。
- 只有更新后解析通过、目标集合被加载,才算完成规则源故障修复;本例是条件推演,不是实测案例。
路径与缓存修复:先证明写入问题,再考虑替换文件
路径修复的目标是让实际内核在正确位置写入,而不是扩大整个目录的权限。规则集合路径说明要求 path 唯一,并限制在允许的安全路径内;容器只读挂载则应结合Docker 挂载说明处理。
- 将 path 按实际 HomeDir 解析,确认没有其他 provider 使用同一文件;父目录应已存在,并允许实际运行身份访问。
- 路径位于 HomeDir 外时,优先考虑恢复到 HomeDir 内的专用缓存目录。确需额外路径时,再按文档配置范围尽可能小的 SAFE_PATHS,并核对实际服务环境。
- 日志明确指向权限或只读问题时,只核查目标目录、运行身份和挂载方式。个人账户可以编辑文件,不能替代对服务运行身份的检查。
- 怀疑旧缓存内容异常时,先停止实际内核,把对应文件复制到非临时备份目录,再将原文件改名留存;仅对这一个 provider 重新下载。
- 新文件无法解析或加载时,停止内核,保留失败文件,恢复原路径下的旧副本及原配置,再启动验证。
- 首次下载没有旧副本:修复来源、格式或写入问题后再获取文件,不能用创建空文件代替下载。
- 已有缓存更新失败:保留副本,并查询当前加载状态;是否仍能使用旧规则,需要实际运行结果确认。
- 如果备份曾放入系统临时目录,应先转存到非临时位置;重启或重新部署后发现备份丢失时,需要重新上传自己保存的副本。
四阶段验收与下一步阅读
规则源故障结束于下载、解析与加载恢复;实际命中是后续独立验收。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 引用名称、规则顺序和新连接的命中详情,并把匹配规则与使用的策略组或节点分开记录。