Mihomo 订阅更新失败怎么办？按报错恢复节点与配置
简答：Mihomo 订阅更新失败时不要先删除旧配置。先确认失败发生在订阅下载、Provider 更新、配置解析还是节点连接，再测试完整订阅 URL、查看 HTTP 返回和 Mihomo 日志，最后复测更新时间、节点数量与实际连通性。
定义：Mihomo 订阅更新失败，是指客户端或内核无法从远程 URL 获取、解析或写入代理节点集合，而不是单个节点连接失败。
先看报错：对应处理动作速查
如果旧节点仍能使用，先不要删除配置、清空缓存或重置订阅地址。Mihomo 的远程代理集合通常由 proxy-providers 管理，官方文档明确区分了远程 URL、保存路径、更新间隔和下载代理等字段；因此“订阅更新失败”可能发生在下载、保存、解析或后续引用中的任一层。可先查看Mihomo 代理集合配置文档确认当前配置属于哪一种类型。
| 看到的现象 | 优先检查 | 先做什么 |
|---|---|---|
Timeout、context deadline exceeded | 订阅域名、当前网络、DNS、服务端响应 | 暂时关闭 TUN 或其他代理，改用手机热点重试；不要连续刷新。 |
DNS resolve failed、no such host | 订阅域名解析，不一定是节点 DNS | 先测试订阅域名解析，再区分系统 DNS、Mihomo DNS 和 TUN 路径。 |
401 | 身份凭据或订阅令牌 | 从服务方控制台重新复制完整地址，核对是否已过期或被重置。 |
403、429 | 访问权限、请求限制、账号状态 | 停止重复请求，检查账号状态与服务公告，并向服务方确认限制原因。 |
404 | 地址路径或订阅入口已变化 | 不要手改路径，重新复制完整订阅 URL。 |
500、502、503 | 远端服务或上游响应 | 用另一网络交叉测试；若多网络均失败，保留旧配置并等待服务方确认。 |
YAML parse error、格式错误 | 返回内容不是有效配置，或格式与当前内核不兼容 | 检查 URL 返回的是配置内容，而不是登录页、验证码页或 HTML 错误页。 |
| 更新成功但节点不变 | 实际更新时间、Provider 引用、远端内容是否变化 | 查看 Provider 的更新时间和节点数量，不要只看主界面旧节点列表。 |
HTTP 状态码的含义应以协议定义为准：RFC 9110 将 401 与认证挑战相关联，将 403 定义为服务器理解请求但拒绝执行，并分别说明了 404、429 以及 5xx 响应的语义。它们只能帮助定位方向，不能单独证明某个服务商已经故障。
最短可复制流程：先保留，再验证，再更新
- 保留当前配置。在客户端中导出或复制当前配置文件；如果没有导出功能，至少不要删除仍能使用的 Provider 和节点。这样即使新订阅返回空内容或解析失败，也能回滚到旧配置。
- 确认你排查的是哪一条链路。首次导入失败属于 URL 或格式问题；已导入但刷新失败属于远程下载或 Provider 问题；节点能更新但无法连接，则应转到节点、DNS、规则或网络问题，不要反复修改订阅地址。
- 重新复制完整订阅 URL。从服务方账户页面复制，不要凭记忆补参数。检查开头和结尾是否完整，是否混入空格、换行、引号或网页地址；订阅 URL 中的令牌属于敏感信息，不要公开发到截图、群聊或工单。
- 脱离客户端测试 URL。用浏览器打开或使用系统命令行请求该地址，观察 HTTP 状态、响应类型和内容开头。可执行的命令示例为
curl -I -L --max-time 15 "你的订阅URL"；其中“你的订阅URL”是占位符，不能原样执行。若命令行不熟悉，浏览器测试也可以，但浏览器能打开不代表返回内容一定是有效 Mihomo 配置。 - 确认返回内容。有效返回通常应能被客户端识别为节点集合或配置；如果页面显示登录表单、验证码、HTML 错误页、JSON 错误信息或内容明显被截断，不要把它保存为 YAML，也不要继续改 DNS。
- 再回到 Mihomo 更新 Provider。如果你使用控制面板，可查看 Provider 的更新时间、状态与节点数量；官方 API 文档列出了
/providers/proxies查询所有代理集合，以及对指定代理集合执行PUT更新的接口。使用 API 时必须填入自己的控制器地址和密钥，不要把真实密钥写入公开脚本。 - 复测并记录结果。更新后同时核对更新时间是否变化、节点数量是否合理、策略组是否仍引用该 Provider，以及任选一个节点是否能完成延迟测试。只看到“更新按钮转完”不能证明节点已经真正更新。
官方配置中，HTTP 类型代理集合需要 url，可用 path 指定本地保存位置，并可设置 interval 更新间隔；如果这些字段来自客户端自动生成的配置，不建议直接凭经验改名或改路径，应先备份后再调整。
按错误类型继续分流
1. Timeout、DNS 和连接被拒绝
先做一次只改变一个条件的交叉测试：保持订阅 URL 不变，依次切换手机热点、关闭系统代理、暂时关闭 TUN，再重试一次。若仅在某个网络失败，优先检查该网络的 DNS、出口策略或本地代理冲突；若所有网络都失败，则保留旧配置，记录时间、状态码和错误文本，向服务方核实订阅入口。
Mihomo 的 DNS 配置同时涉及普通域名解析、节点域名解析和直连解析。官方 DNS 文档列出了 nameserver、proxy-server-nameserver、direct-nameserver 等不同用途，其中 proxy-server-nameserver 专门用于解析代理节点域名。订阅 URL 本身仍可能由系统或下载路径解析，因此不要看到 DNS 报错就直接复制一份复杂 DNS 配置；先判断失败的是订阅域名、节点域名还是目标网站。
2. 401、403、404、429 和 5xx
- 401：重点检查令牌、登录状态和订阅是否被重新生成。重新复制完整地址通常比手动修改参数更安全。
- 403：可能是权限不足、访问策略或来源限制。不要通过不断更换客户端来绕过，先向服务方确认账户权限和允许的使用方式。
- 404：优先怀疑链接路径已失效或复制错误。不要把网页首页当作订阅地址。
- 429：通常意味着请求过于频繁或触发服务端限制。停止连续刷新，等待后再试，并检查是否有多个设备或客户端同时自动更新。
- 500、502、503：属于服务端或上游响应方向。单次错误不足以判断长期状态，建议用另一网络复测并保留旧配置。
3. YAML、格式解析和 Provider Error
如果 URL 可以访问但 Mihomo 报 YAML 解析失败，先查看返回内容是不是 HTML、登录页、错误 JSON 或空白文件。然后检查客户端实际使用的是 Mihomo 内核，而不是另一个兼容性不同的内核；不同客户端的菜单名称和配置编辑方式可能不同，不能把一个客户端的修复步骤直接套到另一个客户端。
官方文档说明，代理集合内容可以是 YAML、URI 或 Base64 等形式，但这些内容的组织方式并不完全相同；代理集合内容文档也指出不同格式不能随意混写。遇到格式错误时，优先让服务方确认应使用的订阅格式，再在客户端中选择匹配的导入方式。
更新成功后的验证与回滚清单
完成更新后，按下面顺序检查，避免把“按钮执行完成”误认为“配置可用”：
- 时间：Provider 的更新时间是否变为本次操作之后。
- 数量：节点数量是否从空值恢复；若明显减少，先不要删除旧配置，确认远端内容是否确实变化。
- 引用：策略组是否仍通过
use引用了正确的 Provider。官方代理组文档说明，代理组可以通过use引用代理集合，因此节点存在但策略组不显示时，要检查引用名称。 - 连通性：先做单节点延迟测试，再测试实际应用；延迟测试失败不等于订阅下载失败，两者应分开记录。
- 安全性：确认没有把订阅令牌、控制器密钥、完整配置或带身份参数的 URL 发到公开位置。
如果新内容导致配置无法启动，停止自动更新，恢复刚才的备份文件或切回原 Provider；不要在没有备份的情况下连续覆盖配置。恢复后先确认旧节点能否使用，再单独处理新订阅。若需要反馈问题，可提供客户端名称、Mihomo 内核版本、错误关键词、HTTP 状态码、发生时间和脱敏后的配置结构，但应遮挡订阅令牌、控制器密钥、节点地址中的敏感参数。
本文步骤按 2026-11-03 可核验的 Mihomo 官方配置与 API 文档整理；客户端界面、内核版本和具体菜单可能随发行版变化，遇到界面不一致时以当前客户端显示和官方文档为准。
相关操作入口
如果你已经确认订阅能正常更新，但仍然无法连接，可继续查看站内的Mihomo 订阅配置与代理模式设置；如果问题集中在虚拟网卡、权限或 TUN 启动，再看Mihomo TUN 模式无法启动的排查步骤。不要把订阅下载失败、节点连接失败和 TUN 未启动当成同一个问题处理。
常见问题
Mihomo 订阅更新失败但旧节点还能用，需要删除旧节点吗？
不需要。旧节点仍能用时，先导出或保留当前配置，再排查新订阅的 URL、HTTP 返回和 Provider 状态。删除旧配置会减少回滚选择，不能解决远端地址失效、权限错误或格式错误。
浏览器能打开订阅链接，为什么 Mihomo 还是更新失败？
浏览器能建立连接只说明页面或响应可访问，不代表返回的是 Mihomo 能解析的节点集合。请继续检查 HTTP 状态、响应内容是否为 HTML 或登录页、是否被截断，以及客户端使用的内核和订阅格式是否匹配。
Mihomo 报 DNS resolve failed，应该直接修改 DNS 配置吗？
不要直接套用复杂配置。先判断失败对象是订阅域名、节点域名还是目标网站，再用手机热点、关闭 TUN 或恢复默认 DNS 做交叉测试。Mihomo 官方文档对普通解析、代理节点解析和直连解析分别提供了不同字段。
订阅更新成功但节点列表没有变化，算更新失败吗？
不一定。先查看 Provider 的更新时间、节点数量和返回状态；如果时间已更新但远端内容没有变化，列表可能确实保持不变。如果时间没有变化，或策略组没有引用该 Provider，才需要继续检查更新路径和配置引用。
如何安全地向服务方反馈 Mihomo 订阅更新问题？
提供客户端名称、内核版本、错误关键词、HTTP 状态码、发生时间和脱敏后的日志即可。订阅 URL、令牌、控制器密钥、完整节点配置和带身份参数的截图都应遮挡。