Clash / Mihomo 的 provider 机制很适合把节点列表和主配置拆开，但它也让错误多了一层。主配置启动正常，不代表 provider 已经加载；provider 文件下载成功，也不代表分组真的用了它。

快速对照表

检查项正常表现异常表现
URL返回 provider YAML返回 HTML、空文本、登录页
path本地生成缓存文件权限不足、目录不存在
interval能按周期更新过短导致频繁失败
health-check只影响可用性检测URL 错或超时让节点灰掉
filter只筛目标节点正则过严导致列表为空
group use分组引用 provider名称不一致，分组无节点

provider 为空最常见的是 URL 拿错。很多订阅地址返回完整配置，而 proxy-providers 期待 provider 片段；两者结构不同，不能互换。

URL 与 path

把 provider URL 单独打开，正文里应能看到节点列表。若返回 <html>、错误提示或完整 Clash 配置，都要回订阅后台换「provider」或「Clash 节点列表」格式。path 是本地缓存文件，OpenClash、Docker、NAS 上要确认目录存在且进程可写。

如果你还没有确定订阅格式，使用兼容 Clash / Singbox / V2Ray 的订阅时也要区分「完整 Clash YAML」和「proxy-provider 片段」，这两种不是同一个入口。

group use 不能写错

示例结构大致如下：

proxy-providers:
  main-provider:
    type: http
    url: https://example.com/provider.yaml
    path: ./providers/main.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: Auto
    type: url-test
    use:
      - main-provider

use 里的 main-provider 必须和上方 key 完全一致。大小写、下划线、短横线不一致，Mihomo 不会猜你的意思。

排查清单

  • provider URL 可直接下载，状态码不是 301 循环或 403。
  • 文件正文不是完整配置里的 proxy-groups、rules 大包。
  • path 所在目录存在，客户端有写入权限。
  • filter 先临时注释，排除正则筛空。
  • health-check.url 使用轻量可访问地址。
  • 分组里写的是 use，不是把 provider 名称塞进 proxies。

相关阅读