Mihomo 规则集加载失败怎么办？按四层快速排查
简答：Mihomo 规则集加载失败，先看日志中的第一条错误，再区分下载失败、格式解析失败、Provider 未加载和规则未命中。最快的处理顺序是：核对 URL 与返回内容→检查 type、behavior、format→确认 path 可写→确认 rules 中使用了同名 RULE-SET，最后再更新缓存或重载配置。
定义：Mihomo 规则集加载失败，是指 rule-providers 定义的远程或本地规则文件没有成功下载、解析、载入，或虽然载入却没有被规则链实际引用和命中。
先看这张判断表：不要把规则集故障当成节点故障
规则集负责告诉 Mihomo“哪些域名或 IP 应匹配哪条规则”，节点负责承载已经选择的流量。规则集失败不一定代表节点不可用；反过来，规则集显示已加载，也不代表当前访问一定走到了预期策略。
| 现象或日志关键词 | 优先检查层级 | 判断标准 | 下一步 |
|---|---|---|---|
timeout、context deadline exceeded | 下载 | 规则 URL 请求超时或下载出站不可达 | 用浏览器或 curl.exe 检查 URL，再检查 proxy 或网络 |
404、403、401 | 地址或权限 | 服务器明确返回错误状态 | 核对 URL、文件路径和访问权限，不要盲目清缓存 |
yaml、parse、decode、format | 解析 | 文件已返回，但内容格式与配置不一致 | 核对 behavior 与 format |
provider not found 或找不到同名 Provider | 引用 | RULE-SET 后面的名称与 Provider 键名不一致 | 逐字符核对名称、大小写和缩进 |
| Provider 已更新但访问仍走错策略 | 命中 | 规则集存在，但规则顺序、模式或引用不正确 | 检查规则顺序、模式和连接详情 |
permission denied、文件写入失败 | 缓存路径 | path 指向的位置不可写或不在允许目录 | 改用 Mihomo 工作目录下的相对路径并重载 |
官方配置说明中，HTTP 类型需要配置 url，path 是本地文件路径，behavior 支持 domain、ipcidr、classical，format 支持 yaml、text、mrs。可对照 Mihomo Rule Providers 文档。
第一步：检查规则 URL 是否真的返回规则文件
先不要删除旧缓存。旧文件可能仍能被 Mihomo 读取，直接清理会把“更新失败”扩大成“完全没有规则”。在 Windows PowerShell 中运行下面的命令；命令只读取响应头，不会公开订阅令牌或私钥。
curl.exe -I -L "https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/private.mrs"
预期是能够获得 HTTP 响应，并且最终地址不是登录页、错误页或 HTML 验证页。若出现 404、403 或持续超时，问题优先在 URL、远端权限、当前网络或下载出站，不在 YAML 缩进。
如果需要检查响应正文，建议只查看文件开头的少量内容，不要把包含令牌的完整订阅内容粘贴到公共平台。对于 .mrs 二进制规则集，文本查看可能没有可读内容，这本身不等于文件损坏；应结合 HTTP 状态、文件大小和 Mihomo Provider 状态判断。
官方示例使用了 MetaCubeX 规则数据中的 .mrs 文件，并将域名规则集设置为 behavior: domain、format: mrs。可对照官方示例配置。
第二步：核对最容易写错的五个字段
下面是一个可运行结构的最小示例，使用公开规则文件，不包含订阅密钥。它只演示一个域名规则集和一条引用规则；其中策略名 DIRECT 是 Mihomo 常见内置策略目标，若你的配置没有对应策略组，应改成当前配置中真实存在的策略名称。
rule-providers:
private_domain:
type: http
url: "https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/private.mrs"
path: ./rule-providers/private_domain.mrs
interval: 86400
behavior: domain
format: mrs
rules:
- RULE-SET,private_domain,DIRECT
- MATCH,DIRECT- 名称：
private_domain必须与RULE-SET,private_domain,...中的名称完全一致。 - type：远程文件通常使用
http；本地文件使用file；内联内容使用inline。 - behavior：域名列表用
domain，IP 网段用ipcidr，带完整经典规则语法的文件用classical。 - format：必须与实际文件对应。官方文档列出的选项是
yaml、text、mrs。 - path：路径应唯一且可写。相对路径更容易随 Mihomo 工作目录管理；不要随意写入受限目录。
最常见的配置错误是把纯域名列表声明成 classical，或把经典规则文件声明成 domain；这会导致解析成功但规则内容不符合预期，甚至直接加载失败。不同规则文件的内容格式应以发布方说明和文件实际内容为准。
第三步：按错误类型处理下载、解析和缓存
遇到 timeout 或连接失败
先用普通网络请求测试 URL，再判断是否需要为 Provider 指定下载出站。Mihomo 的 proxy 字段用于指定规则更新时使用的代理；如果填写了不存在的策略名，更新仍可能失败。临时排查时可以先删除错误的 proxy 字段，确认直连下载是否可行；如果远端地址只能通过代理访问，再填入当前配置中确实存在的策略名。
遇到 404、403 或 HTML 内容
这通常说明地址失效、权限不足或请求被重定向到错误页面。不要把“浏览器能打开”当成充分证明，因为浏览器可能携带 Cookie，而 Mihomo 的请求没有相同会话。用 curl.exe -I -L 查看最终状态，并检查 URL 是否少了文件扩展名、分支名或路径层级。
遇到 YAML、format 或 decode 错误
核对 behavior 与 format 的组合。官方说明中，classical 内容可以包含多种路由规则，但不应再嵌套 rule-set 或 sub-rule；domain 内容则应是域名匹配列表，ipcidr 内容应是 IP 网段。可查看规则集内容格式说明。
遇到 304、旧文件或更新后仍不变
304\ 代表缓存验证结果，不应单独视为错误。先查看 Provider 的更新时间、文件大小和规则数量，再决定是否清缓存。建议顺序是：备份配置→记录当前 path→手动更新 Provider→重载配置→关闭旧连接后重新测试。只有在文件损坏、路径不可写或状态长期异常时，才考虑删除对应缓存文件。
第四步：确认规则集已经加载，并且真的命中
“加载成功”和“规则生效”是两个不同结论。Mihomo API 提供了规则 Provider、规则和连接信息接口；如果客户端暴露了 External Controller，可以用这些接口检查状态。API 地址、端口和密钥以当前配置为准，不要把下面的地址当成所有客户端都固定可用。
读取全部规则集状态：
curl.exe http://127.0.0.1:9090/providers/rules
读取当前规则及命中信息：
curl.exe http://127.0.0.1:9090/rules
如果 API 返回未授权或连接失败，先检查 External Controller 是否启用、监听地址和密钥。官方 API 文档说明，规则信息中可能包含 Provider 名称、规则数量、命中次数和最近命中时间；这些只能证明 Mihomo 的内部状态，仍应结合实际访问目标复核。可对照 Mihomo API 文档。
验收建议分三层：第一，Provider 状态不再报错；第二，规则数量不是异常的零值；第三，访问一个明确属于该规则集的测试域名，在连接详情或规则命中信息中看到预期规则。若第三步失败，检查规则顺序，因为 Mihomo 规则按从上到下匹配，前面的规则可能已经提前接管了流量。规则顺序和 RULE-SET 引用方式见官方规则文档。
不同客户端中的安全恢复顺序
- 备份：复制当前配置文件或导出配置，保留原始
rule-providers、rules和 Provider 缓存路径。 - 最小化：暂时只保留一个已核验 URL 的 Provider，避免多个错误源同时报错。
- 重载：在客户端中执行配置重载或重新载入；具体按钮名称以当前前端为准，不要根据其他客户端的菜单名称盲点。
- 更新：只更新出错的规则集，观察日志中的第一条新错误。
- 复核：检查 Provider 状态、规则数量、命中信息和一次实际连接。
- 回滚：如果重载后节点、DNS 或系统代理出现新问题，恢复备份配置，关闭新启用的 TUN 或系统代理改动，再单独处理规则集。
如果你使用的是带 Mihomo 内核的图形客户端，前端通常只是配置编辑和状态展示层；规则下载、缓存、解析和命中仍由内核完成。因此，换客户端不一定能解决远端 URL 失效或字段不匹配问题。先把日志和最小配置隔离出来，通常比反复重装更容易定位。
边界云连接场景下的进一步排查
如果规则集已经加载，但访问仍然变慢、分流错误或连接失败，再进入网络层排查：先确认代理端口是否监听，再确认系统代理或 TUN 是否真正接管目标应用，最后检查 DNS 解析结果与规则类型是否匹配。不要用一次网页打开结果推断所有应用都已走同一条路径。
本文是 xianzhey.shop 的第三方使用指南，不是任何客户端或服务品牌的官网。涉及订阅地址、令牌和私钥时，只做脱敏核对，不要公开完整内容；具体服务入口和状态应以对应官方页面为准。
常见问题
规则集加载失败会导致所有节点都不能用吗？
不一定。规则集主要影响分流判断，节点本身可能仍能测速或建立连接。但如果配置依赖该规则集决定代理、直连或拒绝，相关目标可能出现分流错误。应分别测试节点连接、Provider 状态和规则命中。
可以直接删除 rule-providers 缓存重新下载吗？
不建议作为第一步。先备份配置并记录缓存路径，因为旧缓存可能仍能提供规则；直接删除后，如果远端 URL 仍不可达，故障会从“更新失败”变成“没有可用规则”。只有确认文件损坏、路径错误或需要强制重建时再清理。
为什么 URL 能在浏览器打开，Mihomo 还是提示下载失败？
浏览器和 Mihomo 的请求环境可能不同，包括代理、Cookie、重定向、证书和 User-Agent。用 curl.exe -I -L 检查最终响应，并确认返回的是规则文件而不是登录页、HTML 错误页或验证页面。
domain、ipcidr、classical 应该怎么选？
domain 用于域名规则，ipcidr 用于 IP 网段，classical 用于包含完整经典路由语法的规则文件。选择应依据规则文件实际内容，不要只看文件扩展名。
Provider 显示正常，但规则没有生效怎么办？
检查 rules 中是否存在同名 RULE-SET，再检查规则顺序、运行模式和实际连接详情。前置规则可能已经匹配目标，导致后面的规则集没有机会命中。
常见问题
规则集加载失败会导致所有节点都不能用吗？
不一定。规则集负责分流判断，节点可能仍能建立连接；但依赖该规则集的目标可能分流错误，应分别测试节点、Provider 状态和规则命中。
可以直接删除 Mihomo 规则集缓存吗？
不建议作为第一步。先备份配置并检查 URL、响应状态和路径权限，保留旧缓存可避免远端故障扩大成完全没有规则。
为什么规则 URL 在浏览器能打开，Mihomo 仍然下载失败？
浏览器可能使用了不同代理、Cookie 或重定向环境。使用 curl.exe 检查最终 HTTP 状态，并确认返回的确实是规则文件而不是 HTML 页面。
Provider 已加载但规则没有命中怎么办？
检查 RULE-SET 引用名称、规则顺序、运行模式和连接详情。前面的规则可能已经匹配目标，导致后面的规则集未执行。