Mihomo 规则集加载失败:按日志定位下载、格式与引用问题
简答: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 error | behavior 或 format 与文件内容不匹配 | 区分 classical、domain、ipcidr,并检查 yaml、text、mrs |
| permission denied、safe path、path not allowed | path 不在允许目录或文件不可写 | 改用 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 命中后的策略组。 |
| behavior | domain、ipcidr、classical 要根据实际内容选择,不能只按文件扩展名判断。 |
| format | yaml、text、mrs 必须与实际编码和规则集类型匹配;mrs 的支持范围以当前文档为准。 |
如果出现 path not allowed 或 permission denied,先把路径改成工作目录下的相对路径测试。确需保存到其他位置时,再按当前系统设置 SAFE_PATHS;官方 API 文档说明,Windows 使用分号分隔,其他系统使用冒号分隔,具体仍以当前启动方式为准。
第三步:区分 classical、domain、ipcidr 与文件格式
规则集下载成功后仍然报解析错误,优先检查“内容类型”和 behavior 是否对应。官方内容文档说明:classical 可包含多种路由规则;domain 使用域名通配形式;ipcidr 使用 CIDR 网段。可参考 Mihomo 规则集内容格式文档。
| 实际内容 | 通常对应 | 常见错误 |
|---|---|---|
| DOMAIN、DOMAIN-SUFFIX、GEOIP、IP-CIDR 等带规则类型的行 | classical | 误设为 domain,导致解析失败或规则不符合预期 |
| 纯域名或域名通配项 | domain | 把带 DOMAIN-SUFFIX 前缀的内容当成纯域名列表 |
| 纯 IP 网段,例如 192.168.1.0/24 | ipcidr | 混入域名或 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 限制。
- 备份当前配置,再只修改一个问题字段,避免多个变量同时变化。
- 重新加载配置或重启内核,确认没有新的 YAML、路径或字段错误。
- 在 provider 状态中确认目标名称存在,并查看更新时间、文件状态或规则数量。
- 在规则列表或日志中确认请求是否命中预期规则,而不是被更早的规则或 MATCH 处理。
- 如果仍失败,保留首条错误日志、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 的账户对该文件夹有读写权限。
相关阅读
- Mihomo 订阅导入后没有节点,先做基础配置排查
- 如果规则加载后 TUN 仍无法上网,继续排查 Windows 网络层
- 需要区分订阅内容错误与客户端配置错误时,可参考格式排查思路
- 其他客户端更新内容失败时,也可按超时、无效内容和空结果分层定位