小鹿網路 - 安全穩定網路加速返回首页

Mihomo 规则集加载失败:按日志定位下载、格式与引用问题

更新于 2026-11-18 · deardeernetworks.buzz

简答:Mihomo 规则集加载失败,不要先删缓存或重写整份配置。最快顺序是:先看首条日志,再检查规则 URL 的 HTTP 响应和返回内容,随后核对 type、path、proxy、behavior、format,最后确认 RULE-SET 名称、规则顺序和实际命中。若下载成功但规则不生效,问题通常已经从“加载”转为“引用或匹配”。

定义:Mihomo 规则集加载失败,是指 rule-providers 定义的规则源在下载、解析、保存、重新加载或被 RULE-SET 引用时出现异常。

先看这张速查表:根据日志决定下一步

以下字段名和接口以当前 Mihomo 文档为准;不同客户端的日志入口名称可能不同,但应尽量找到内核日志,而不是只看客户端弹窗。

错误现象与优先检查项
日志或现象优先判断处理动作
timeout、connection refused、network error规则 URL、DNS、网络或下载代理直接请求 URL,分别测试 DIRECT 与配置中的 proxy
403、404、401地址失效、权限限制或需要请求头核对 URL、访问权限和 header,不要把登录页当规则文件
yaml、parse、unmarshal、format errorbehavior 或 format 与文件内容不匹配区分 classical、domain、ipcidr,并检查 yaml、text、mrs
permission denied、safe path、path not allowedpath 不在允许目录或文件不可写改用 HomeDir 内路径,或按当前系统设置 SAFE_PATHS
规则集显示已加载,但访问仍未命中RULE-SET 名称、规则顺序或目标类型不匹配检查 provider 名称、引用位置和 MATCH 兜底
304 或更新时间没有变化需要区分缓存校验与真正失败同时查看 provider 状态、本地文件时间、规则数量和实际命中

核心结论:先按日志把问题分成下载、解析、落盘、引用、命中五层,通常比反复刷新或删除全部缓存更快。

第一步:确认规则源返回的不是网页或错误 JSON

当日志指向 timeout、403、404 或解析错误时,先在同一台设备上检查规则 URL。以下命令中的 URL 只是占位符,需替换成实际地址;命令参数名称和客户端入口以当前版本为准。

# macOS / Linux:查看响应头和前几行正文
curl -I -L "https://example.com/rules.yaml"
curl -L --max-time 20 "https://example.com/rules.yaml" | head -n 20

# Windows PowerShell:查看状态码和返回内容
$url = "https://example.com/rules.yaml"
$r = Invoke-WebRequest -Uri $url -MaximumRedirection 5
$r.StatusCode
$r.Headers
$r.Content.Substring(0, [Math]::Min(500, $r.Content.Length))

重点核对四项:HTTP 状态是否成功、Content-Type 是否合理、正文是否确实是规则内容、是否被重定向到登录页或错误页面。若正文开头出现 HTML 标签、登录提示或 JSON 错误对象,即使 URL 能打开,也不能直接按 yaml 或 text 规则集加载。

如果只在 Mihomo 中失败而浏览器能打开,检查 rule-provider 的 proxy。官方文档定义它用于规则集下载或更新,不能把它等同于规则命中后的策略组;规则源下载使用哪个出站,应以 provider 的配置为准。可先临时使用确认可用的下载路径测试,再恢复原配置。

DNS 或 TUN 也可能影响规则 URL 的访问,但不要直接假定是 DNS 问题。先用上面的命令确认同一网络下能否解析和访问,再按客户端日志继续定位。

第二步:核对 rule-providers 的字段关系

官方配置中,type、url、path、proxy、behavior 和 format 各自负责不同层面。http 类型需要配置 url;path 应保持唯一,并受 HomeDir 与安全路径限制;behavior 必须和文件内容相符;format 支持 yaml、text、mrs。详情请核对 Mihomo rule-providers 配置文档。

rule-providers:
  example_rules:
    type: http
    url: "https://example.com/rules.yaml"
    path: ./rules/example_rules.yaml
    interval: 86400
    proxy: DIRECT
    behavior: domain
    format: yaml
配置字段的排查重点
字段检查方法
name名称必须唯一,后面的 RULE-SET 引用必须逐字一致。
type远程文件通常使用 http;本地文件和内嵌内容不要误套用远程 URL 逻辑。
url检查重定向、访问权限和返回正文,不能只看浏览器是否能打开。
path避免重复路径;优先放在 Mihomo 工作目录或 HomeDir 允许范围内。
proxy只表示下载或更新规则集时使用的代理路径,不等于 RULE-SET 命中后的策略组。
behaviordomain、ipcidr、classical 要根据实际内容选择,不能只按文件扩展名判断。
formatyaml、text、mrs 必须与实际编码和规则集类型匹配;mrs 的支持范围以当前文档为准。

如果出现 path not allowed 或 permission denied,先把路径改成工作目录下的相对路径测试。确需保存到其他位置时,再按当前系统设置 SAFE_PATHS;官方 API 文档说明,Windows 使用分号分隔,其他系统使用冒号分隔,具体仍以当前启动方式为准。

第三步:区分 classical、domain、ipcidr 与文件格式

规则集下载成功后仍然报解析错误,优先检查“内容类型”和 behavior 是否对应。官方内容文档说明:classical 可包含多种路由规则;domain 使用域名通配形式;ipcidr 使用 CIDR 网段。可参考 Mihomo 规则集内容格式文档。

内容与 behavior 的对应关系
实际内容通常对应常见错误
DOMAIN、DOMAIN-SUFFIX、GEOIP、IP-CIDR 等带规则类型的行classical误设为 domain,导致解析失败或规则不符合预期
纯域名或域名通配项domain把带 DOMAIN-SUFFIX 前缀的内容当成纯域名列表
纯 IP 网段,例如 192.168.1.0/24ipcidr混入域名或 classical 规则行
MRS 二进制规则集mrs用 text 或 yaml 读取,或选择了不匹配的 behavior

不要只根据文件名是 .yaml、.txt 或 .mrs 来决定 behavior。打开返回内容,确认它到底是带规则类型的 classical、纯域名、纯 CIDR,还是 MRS 文件。

第四步:确认 provider 已加载,并且 RULE-SET 真正被引用

“规则集加载成功”和“访问请求命中规则”是两件事。配置中的 provider 名称必须与规则引用完全一致,例如:

rules:
  - RULE-SET,example_rules,Proxy
  - MATCH,DIRECT

检查三点:第一,example_rules 是否就是 rule-providers 下的名称;第二,RULE-SET 是否放在可能提前匹配的规则之后或之前,取决于你的预期;第三,最后是否有明确的 MATCH 兜底。规则顺序错误时,provider 可能已经加载,但请求在到达 RULE-SET 前就被其他规则处理。

如果客户端提供内核 API,可先读取规则集和规则信息。官方 API 文档列出了 /providers/rules、/providers/rules/{providers_name}、/rules、/logs 和 /version 等接口;访问 API 需要使用当前配置中的 controller 地址和密钥,不能照抄示例端口或密钥。参考 Mihomo API 文档。

# 以下为结构示例,需替换 controller、端口和密钥
curl -H "Authorization: Bearer YOUR_SECRET" \
  "http://127.0.0.1:CONTROLLER_PORT/providers/rules"

curl -H "Authorization: Bearer YOUR_SECRET" \
  "http://127.0.0.1:CONTROLLER_PORT/rules"

curl -H "Authorization: Bearer YOUR_SECRET" \
  "http://127.0.0.1:CONTROLLER_PORT/logs?level=debug"

验收时至少记录:provider 是否出现在列表中、规则数量是否为非零、更新时间是否变化、日志是否还有解析或写入错误,以及访问目标时是否出现对应规则命中。若 provider 状态正常但规则数量为零,继续检查文件内容和格式;若规则数量正常但未命中,继续检查 RULE-SET 引用、规则顺序和请求实际使用的域名或 IP。

修复后验收清单:不要只看“刷新成功”

完成修改后,按“重新加载—查看状态—实际访问”三步验收。配置重新加载接口的参数和权限以当前 API 文档为准,路径不在工作目录时还要注意 SAFE_PATHS 限制。

  1. 备份当前配置,再只修改一个问题字段,避免多个变量同时变化。
  2. 重新加载配置或重启内核,确认没有新的 YAML、路径或字段错误。
  3. 在 provider 状态中确认目标名称存在,并查看更新时间、文件状态或规则数量。
  4. 在规则列表或日志中确认请求是否命中预期规则,而不是被更早的规则或 MATCH 处理。
  5. 如果仍失败,保留首条错误日志、HTTP 状态、返回内容前几行和实际 path,方便继续定位。

最短判断:没有 provider 状态,先查下载或解析;有 provider 但规则数量异常,查内容格式或缓存文件;规则数量正常但访问不按预期,查 RULE-SET 引用和规则顺序。

本文为第三方使用指南,不能替代 Mihomo 当前版本文档;客户端界面、日志入口和字段兼容性可能不同,遇到不一致时应以当前文档和实际内核日志为准。

常见问题

Mihomo 规则集加载失败,应该先删缓存吗?

不建议把删缓存作为第一步。先保存首条日志,检查 URL 返回内容、provider 状态和本地 path。只有在确认本地缓存损坏、路径变化或需要重新获取文件时,才在备份后处理缓存,并在操作后重新加载配置。

规则 URL 浏览器能打开,为什么 Mihomo 仍然加载失败?

浏览器和 Mihomo 可能使用不同的 DNS、网络出口、请求头或下载代理。先用命令查看 HTTP 状态和正文,确认返回的不是登录页、HTML 错误页或 JSON 错误,再检查 provider 的 proxy 与 header 配置。

behavior 应该选 classical、domain 还是 ipcidr?

看规则文件实际内容,不看文件名。带 DOMAIN-SUFFIX、GEOIP、IP-CIDR 等规则类型的内容通常按 classical 核对;纯域名按 domain 核对;纯 CIDR 网段按 ipcidr 核对。最终以当前 Mihomo 内容格式文档为准。

规则集已经加载,但 RULE-SET 没有命中怎么办?

先确认 RULE-SET 后面的 provider 名称与 rule-providers 名称完全一致,再检查规则顺序、请求实际使用的域名或 IP,以及是否被前面的规则提前处理。最后用规则列表和 debug 日志确认命中情况。

path 报 safe path 或 permission denied 怎么处理?

先改用 Mihomo 工作目录或 HomeDir 下的相对路径测试。若必须使用其他目录,按当前系统和启动方式配置 SAFE_PATHS,并确认运行 Mihomo 的账户对该文件夹有读写权限。

相关阅读

参考资料

  1. mihomo 官方文档:Rule-Providers 配置
  2. mihomo 官方文档:规则集内容格式
  3. mihomo 官方文档:API 接口