Mihomo规则集更新失败怎么办？按日志、格式、代理和缓存排查
简答：Mihomo规则集更新失败，先不要删除缓存或重写整份配置：记录第一个错误、检查规则 URL 的真实响应，再核对 rule-providers 的 url、path、proxy、behavior 和 format。若旧规则文件仍存在，更新失败不一定等于当前规则立即失效；修复后还要检查文件更新时间、规则数量和实际命中情况。
定义：Mihomo规则集更新失败，是指 rule-providers 中的 HTTP 规则源无法下载、下载内容无法按指定格式解析、缓存文件无法写入，或更新后规则没有被当前配置实际引用。
先试这一步：用一张表确定排查层级
本文只讲 Mihomo 的 rule-providers，不处理节点订阅、TUN 启动或系统代理故障。不同图形客户端的按钮名称可能不同，以下判断以 Mihomo 内核配置和日志为准；客户端是否提供对应按钮，需要以当前客户端版本为准。
| 现象或日志关键词 | 优先检查 | 处理动作 |
|---|---|---|
| timeout、connection refused、DNS error | URL连通性、DNS、下载出站 | 先用 DIRECT 或可用代理分别测试，确认规则源域名能解析并返回 |
| 403、401、404、5xx | URL、权限、上游状态 | 检查链接是否过期、是否需要请求头，确认返回的不是登录页或错误页面 |
| payload、parse、unmarshal、invalid rule | behavior 与 format | 按真实文件内容调整 domain、ipcidr、classical 及 yaml、text、mrs |
| permission denied、path、safe path | path、HomeDir、写入权限 | 把文件放入允许目录，或按当前部署方式核对安全路径设置 |
| 304、文件未变化 | 条件请求与本地缓存 | 不要立即删除缓存，核对本地文件、修改时间、规则数量和 reload 状态 |
Mihomo 官方配置文档说明，HTTP 规则源需要配置 url，path 用于本地文件，interval 的单位是秒，proxy 决定下载或更新所经过的代理，behavior 与规则内容类型有关，format 支持 yaml、text 和 mrs。查看 Mihomo 官方 rule-providers 文档
第一步：备份配置并抓住第一条错误
- 先复制当前配置文件和对应的规则缓存目录，保留原始文件名与时间。
- 只刷新一个失败的规则集，不要同时删除缓存、重启内核、改 DNS 和更换节点，否则无法判断是哪一步产生变化。
- 在客户端日志页、内核标准输出或服务日志中，搜索失败的 provider 名称。优先记录第一条错误及其前后的 URL、HTTP 状态、解析错误和路径信息。
- 如果日志只有“更新失败”，提高日志级别后再复现；具体入口因客户端不同而变化，不要把某个图形客户端的菜单名称当作 Mihomo 内核固定界面。
若使用外部控制器或面板，先确认它连接的是当前正在运行的 Mihomo 实例。官方文档将 external-controller 定义为控制内核的 REST API，并提醒未配置密钥或暴露到局域网时需要自行做好访问控制。查看 Mihomo 官方外部控制器说明
第二步：检查 URL 返回的到底是不是规则文件
规则链接能打开，不代表 Mihomo 收到的就是规则内容。常见误判包括：返回 HTML 登录页、JSON 错误、403/404 页面、重定向到需要登录的地址，或服务器返回空内容。
- 不要把包含令牌、UUID、密码或完整订阅凭据的 URL 发到群聊、工单或截图中。
- 在 PowerShell 中运行以下可执行检查，命令会要求你在本机粘贴 URL，不会把凭据写进文章或脚本：
$u = Read-Host "粘贴规则 URL（不要公开输出）"
$out = Join-Path $PWD "mihomo-rule-check.bin"
$headers = Join-Path $PWD "mihomo-rule-headers.txt"
curl.exe -L --max-time 20 -D $headers -o $out $u
Get-Content $headers
Get-Item $out | Select-Object Length,LastWriteTime预期是能看到最终响应状态、Content-Type 或重定向信息，并得到一个非零大小的本地文件。随后用文本编辑器或十六进制工具查看文件开头：如果出现 HTML、登录提示或 JSON 错误信息，先修复 URL、权限或请求头，不要继续调整 behavior。
第三步：逐项核对 rule-providers 配置
下面是结构片段，不是可以直接复制的完整配置；其中 URL、文件名和代理组必须替换为你配置中真实存在的值。
rule-providers:
example:
type: http
url: "实际规则 URL"
path: ./rules/example.yaml
interval: 86400
proxy: DIRECT
behavior: classical
format: yaml- type: HTTP 规则源通常使用
type: http；本地文件和内联规则不是同一种更新方式。 - url: 只有 HTTP provider 才需要；确认地址没有被截断、过期或依赖未提供的请求头。
- path: 不要让多个 provider 共用同一路径。官方文档还说明，路径会受到 HomeDir 安全限制；放在允许范围之外可能触发路径安全错误。
- proxy: 它只影响 Mihomo 下载或更新规则时的出站路径，不等于规则命中后流量一定使用同一个策略。若代理组名称不存在、为空或尚未加载，下载可能失败；可先用
DIRECT做对照测试。 - behavior: 必须和规则内容匹配，例如 domain、ipcidr、classical 不是可随意互换的标签。
- format: 按实际文件选择 yaml、text 或 mrs，不要只因为文件扩展名是
.txt或.yaml就假设内容格式正确。
官方文档明确列出了这些字段及其约束；尤其是 behavior 与 format 的组合，应该根据文件内容核对，而不是只修改扩展名。核对字段定义与格式限制
第四步：按错误类型修复并保留回滚路径
超时、DNS错误或连接被拒绝
先在同一台设备上测试规则源域名是否能解析，再比较 proxy: DIRECT 和当前代理组。只改下载出站，不要同时改系统 DNS、TUN 和节点。若 DIRECT 能下载而代理不能，重点检查代理组是否存在、是否有可用成员，以及客户端是否真的加载了这份配置。
403、401、404或5xx
403/401通常需要核对访问权限、令牌和请求头；404通常要检查路径、分支或文件名；5xx则应先确认上游是否暂时返回错误。不要把服务器错误页面直接交给规则解析器，也不要公开完整认证信息。
解析失败或规则格式不匹配
先确认文件是 YAML、逐行文本、MRS，还是包含 payload 的其他结构。若规则内容的行为是 domain，却配置成 ipcidr 或 classical，下载即使成功也可能在解析阶段失败。修复后仅重新加载这个 provider，并观察是否出现规则数量或更新时间变化。
permission denied、path不安全或文件写不进去
检查 path 的实际绝对位置、运行 Mihomo 的用户权限和 HomeDir。官方文档说明，规则文件路径受到 HomeDir 限制；如确需额外路径，应按当前部署环境核对 SAFE_PATHS，并先确认目录确实可信。修改前保留原配置，失败时恢复旧的 path 或旧缓存。
第五步：更新后不要只看“按钮成功”
- 查看 provider 的更新时间、规则数量或面板显示的状态是否发生合理变化。
- 检查
path对应文件的修改时间和大小；文件变大不等于内容正确，必要时查看开头几行并确认不是 HTML 或 JSON 错误。 - 在 Mihomo 日志中确认没有新的 parse、load 或 refresh error。
- 用一个你明确知道应匹配的域名或 IP 做实际访问测试，再观察规则命中记录。单次访问成功只能证明一次链路，不能证明所有规则都已恢复。
- 如果更新失败但旧缓存仍在，先保留旧缓存并记录问题，不要为了“清干净”而删除最后一份可用规则。
规则 provider 与节点订阅是两套对象：规则源更新成功，不代表节点可用；节点可用，也不代表规则已经命中。若更新后依然表现异常，应回到日志中确认实际加载的配置和 provider 名称。
最小回滚方案：恢复到上一次可用状态
- 停止正在频繁重试的客户端或内核。
- 恢复备份的配置文件，尤其是
rule-providers段。 - 保留旧规则缓存，不要先删除。
- 重新启动后只验证一个已知规则集和一个已知访问目标。
- 确认恢复后，再单独修改 URL、proxy、behavior、format 或 path 中的一项。
如果修改了外部控制器、API 密钥或监听地址，也要同步检查访问范围；官方文档提醒，未配置密钥的控制接口不应暴露给不受信任的网络。
常见问题
规则集更新失败会马上导致无法上网吗？
不一定。若本地仍有此前加载成功的规则缓存，当前进程可能继续使用旧内容；但这不能证明规则已经是最新，也不能证明所有域名仍能正确命中。请结合日志、缓存文件和实际规则命中结果判断。
日志里的304是不是更新失败？
不要只凭“304”三个字符下结论。先检查本地 path 文件是否存在、内容是否完整、修改时间是否合理，以及客户端是否完成 reload。只有在本地文件缺失、解析失败或规则数量异常时，才继续处理缓存或上游响应。
把proxy改成DIRECT后能更新，说明什么？
这通常说明规则 URL 本身至少在当前网络下可以访问，而原先配置的下载出站、代理组名称、代理链或代理节点需要进一步核对。它不等于 DIRECT 永远更好，也不代表规则命中流量会走 DIRECT。
为什么文件扩展名改成.mrs后仍然失败？
扩展名不会自动转换文件内容。应先确认实际内容是否为 MRS，再让 format 与内容匹配；官方文档还说明，MRS 对 behavior 存在适用范围限制，不能把任意规则文本直接改名为 MRS。
图形客户端里找不到规则集更新按钮怎么办？
不要据此判断内核没有 rule-providers。先查看客户端使用的配置文件、内核日志和 provider 实际路径；按钮名称与功能入口由客户端决定，无法仅凭 Mihomo 内核文档推断。
常见问题
Mihomo规则集更新失败会马上导致无法上网吗？
不一定。旧缓存仍可能被当前进程使用，但需要结合日志、缓存文件和规则命中结果确认，不能只看客户端是否还能打开网页。
把rule-providers的proxy改成DIRECT后恢复，说明什么？
优先说明下载出站或代理组存在问题。继续核对代理组名称、成员状态和当前配置是否真正加载，不要把这个结果理解为所有流量都应改走DIRECT。
304状态码需要删除规则缓存吗？
不建议先删除。先检查path文件是否存在、内容是否完整、更新时间和reload状态；只有确认缓存损坏或无法读取时，才在备份后处理缓存。
为什么修改文件扩展名后，Mihomo仍然无法解析？
扩展名不会转换内容格式。应核对真实内容、behavior和format；MRS也不能通过简单改名获得。