Mihomo 订阅导入失败怎么办？完整排查步骤

更新于 2026-10-18 · xnssr.cyou

简答：Mihomo 订阅导入失败，建议先在浏览器或命令行确认订阅 URL 能返回内容，再检查 proxy-providers 的 type、url、path 和 YAML 缩进，最后用 mihomo -t -f 配置文件检查配置；如果能下载但没有节点，重点检查订阅格式和 proxy-groups 是否通过 use 引用了 provider。

定义：Mihomo 订阅导入失败，是指客户端或 Mihomo 内核无法下载订阅内容、解析代理节点，或解析成功但没有把节点加入可用代理组。

先判断：到底是哪一步失败

“订阅导入失败”不一定都是订阅链接失效。Mihomo 通常需要经过“取得链接—下载内容—解析格式—保存 provider—加入代理组”几个环节，任何一环出错都会表现为导入失败。官方配置中，远程订阅一般通过 proxy-providers 定义，type: http 用于远程地址，url 是订阅地址，path 用于保存本地缓存，interval 以秒为单位控制更新间隔。可参考Mihomo proxy-providers 配置文档。

现象	更可能的原因	优先检查位置
点击导入后提示 URL 无法访问	链接过期、复制不完整、网络或证书连接失败	订阅 URL、网络、系统时间
可以下载，但提示解析失败	返回内容不是 Mihomo 可识别的代理集合格式，或内容为空	返回正文、订阅格式、客户端兼容性
配置可以加载，但节点列表为空	provider 没有成功更新，或者被过滤条件排除	`filter`、`exclude-filter`、`exclude-type`
节点已出现，但代理组里没有	`proxy-groups` 没有使用该 provider	代理组中的 `use` 或节点引用
配置文件直接启动失败	YAML 缩进、字段拼写、重复名称或引用错误	配置文件和启动日志

按顺序重新导入订阅

重新复制完整订阅地址。
确认复制的是完整 URL，前后没有空格、换行或被截断的参数。不要把网页标题、二维码说明文字或多个链接一起粘贴到 URL 输入框。
先单独测试链接是否能返回内容。
在浏览器地址栏打开订阅地址，或在终端执行以下命令：
```
curl -L -I "你的订阅URL"
```
如果返回 401、403、404、5xx，或者长时间无法建立连接，先处理链接权限、有效期或网络问题。若返回的是登录页、HTML 错误页或空内容，它就不是可直接交给 Mihomo 解析的订阅正文。
确认客户端使用的是 Mihomo 配置而不是普通文本节点。
如果使用的是图形客户端，导入功能的名称和位置可能不同；如果直接编辑 Mihomo 配置，则需要把订阅放在 proxy-providers 下，而不是把 URL 直接写成 proxies 列表中的一项。
使用最小化配置测试。
先不要同时加入复杂规则、TUN、DNS 或大量代理组，建立一个只包含 provider 的测试配置。例如：
```
proxy-providers:
  my-subscription:
    type: http
    url: "你的订阅URL"
    path: ./proxy_providers/my-subscription.yaml
    interval: 3600

proxy-groups:
  - name: Proxy
    type: select
    use:
      - my-subscription

rules:
  - MATCH,Proxy
```
my-subscription 是 provider 名称，可以自行修改，但同一配置中的名称必须保持一致。官方示例展示了通过 proxy-providers 定义 HTTP provider，并使用 proxy-groups 中的 use 引用 provider。
检查配置文件语法。
在 Mihomo 所在目录执行：
```
mihomo -t -f config.yaml
```
如果配置文件不在当前目录，替换为实际路径。出现 YAML 错误时，先修复报错指出的行号，再重新测试。Mihomo 使用 YAML 配置，YAML 对大小写敏感，缩进只能使用空格，不能使用 Tab；可参考Mihomo 配置语法说明。-t 只能说明配置能够通过检查，不能证明远程订阅一定可访问或节点一定能连接。

常见错误的具体处理方法

提示连接超时、无法解析域名或 TLS 错误

先确认设备本身能访问订阅域名，再检查系统时间是否准确。时间偏差过大可能导致 HTTPS 证书校验失败。也可以暂时关闭其他网络规则或切换到正常的网络环境进行一次下载测试。不要一开始就修改大量 DNS、TUN 或证书选项，否则很难判断真正原因。

提示返回内容不是有效配置或解析失败

下载成功不等于内容格式正确。将返回内容保存为文本后查看开头几行：如果是 HTML 页面、登录页面、JSON 错误信息或空白文件，说明服务端没有返回代理集合。Mihomo 的 provider 支持 http、file 和 inline 类型；远程订阅应使用 type: http 并填写 url。不要把多个 URI 节点逐行直接放进主配置的 proxy-providers 名称下；如果要使用本地文件，应按官方文档要求使用 type: file 和 path。

提示节点为空或全部被过滤

先删除或注释 provider 下的 filter、exclude-filter 和 exclude-type，重新更新一次。如果节点恢复，再逐项加回过滤条件。官方文档说明，filter 用于匹配节点名称，exclude-filter 用于排除匹配名称的节点，exclude-type 用于按代理类型排除；正则写错时可能把所有节点都筛掉。

提示代理组找不到节点

如果 provider 名称是 my-subscription，代理组应通过以下方式引用：

proxy-groups:
  - name: Proxy
    type: select
    use:
      - my-subscription

也可以在代理组中使用具体节点名，但订阅节点名称可能会变化，使用 provider 名称更适合自动更新。官方配置示例展示了代理组通过 use 引用 provider，并可配合 filter 筛选节点，详见Mihomo 官方配置示例。

提示文件无法保存或更新后内容不变

检查 path 所在目录是否存在、是否有写入权限，以及不同 provider 是否使用了相同的缓存路径。官方文档说明，path 必须唯一；如果省略该字段，Mihomo 会根据 URL 的 MD5 使用文件名。排查时可以先为每个 provider 设置不同的相对路径，并确保路径位于 Mihomo 允许使用的目录内。

导入后仍不能使用时的检查顺序

在客户端中手动执行一次 provider 更新，不要只重启界面。
打开运行日志，查看是下载错误、解析错误、过滤后为空，还是具体节点连接错误。
确认代理组确实选中了该 provider 中的节点，而不是仍停留在 DIRECT 或其他组。
使用一个简单的连接测试目标检查延迟和连通性；不要把延迟数值直接当作实际下载速度。
如果更新间隔设置过长，手动更新后仍需确认缓存文件的修改时间是否变化。
升级 Mihomo 或客户端前先备份配置，并记录当前版本；不同版本可能支持不同字段，遇到“字段不存在”时应以对应版本的官方文档为准。

安全方面，不要把包含访问凭据的订阅 URL 发到公开论坛或截图中。订阅链接通常相当于访问授权，泄露后应及时在服务提供方处重置或更换。对于具体订阅服务的可用性、有效期、返回格式和状态，本文无法替代服务提供方的核验。

结论：最短排查路径

如果只想快速定位问题，可以按这个顺序操作：重新复制 URL → 浏览器或 curl 检查返回内容 → 用最小化 proxy-providers 配置测试 → 执行 mihomo -t -f config.yaml → 检查 proxy-groups.use → 查看更新日志。多数导入失败都能在“链接不可访问、内容格式不兼容、YAML 配置错误、代理组未引用”这四类原因中找到对应线索。

如果你还需要确认当前客户端是否支持 Mihomo 配置、订阅或 provider，可以先查看本站的兼容应用说明；遇到无法归类的报错，可参考常见问题中的通用排查思路。

常见问题

Mihomo 订阅 URL 可以直接写在 proxies 下面吗？

通常不建议这样做。远程订阅应按官方配置使用 proxy-providers，设置 type: http、url 和可选的 path、interval，再在 proxy-groups 中通过 use 引用 provider。proxies 主要用于直接定义具体代理节点。

Mihomo 提示订阅更新成功，但节点列表还是空的怎么办？

先检查返回内容是否为空或不是代理集合格式，再暂时删除 filter、exclude-filter 和 exclude-type。之后确认代理组是否通过 use 引用了正确的 provider 名称，并查看更新日志中是否有解析或过滤信息。

执行 mihomo -t -f config.yaml 通过，就代表订阅一定能用吗？

不代表。该命令主要用于检查配置文件能否被解析和加载；远程 URL 是否可访问、返回格式是否正确、节点是否真实可连接，还需要通过 provider 更新、日志和实际连接测试分别确认。

为什么订阅链接在浏览器能打开，Mihomo 还是导入失败？

浏览器能打开只说明请求得到了响应，返回内容可能仍是登录页、错误页或需要特定请求头的内容。请保存或查看返回正文，并核对是否需要 Authorization 等请求头；Mihomo 的 provider 支持通过 header 配置自定义 HTTP 请求头，具体以订阅提供方要求为准。

修改了订阅配置后，为什么 Mihomo 仍然使用旧节点？

可能是更新间隔尚未到达、客户端没有执行手动更新、缓存路径没有写权限，或多个 provider 使用了相同缓存路径。先手动更新，再查看 path 文件的修改时间和运行日志。