Mihomo 订阅导入失败怎么办？403、404、解析错误排查
简答：先确认订阅链接能返回可识别的 YAML、URI 或 Base64 内容，再对照 Mihomo 日志判断是 403、404、超时还是格式解析错误；最后检查账号状态、客户端配置和内核版本，避免只反复点击更新。
定义：Mihomo 订阅导入失败，是指客户端无法下载订阅内容、无法把返回内容解析为代理集合，或更新后没有生成可用节点。
先试这一步：确认订阅链接返回的到底是什么
本文与 Mihomo 项目及开发者无隶属关系。不要先反复删除配置或更换节点，先把订阅链接当作一个普通 HTTP 请求检查：它是否能访问、返回什么状态码、正文是不是订阅内容。
| 现象 | 优先怀疑 | 下一步 | 判定标准 |
|---|---|---|---|
| 浏览器打不开或返回 403 | 权限、登录状态、链接访问策略或账号状态 | 重新从服务提供方后台复制链接，并检查账号状态 | 同一链接在重新登录或重新生成后能返回订阅正文 |
| 返回 404 | 链接路径失效、复制不完整或资源已不存在 | 检查链接是否被截断、是否多了空格，再重新生成 | 返回状态变为 200，且正文不是错误页面 |
| 一直转圈或超时 | 当前网络无法访问订阅地址、DNS 或代理链路问题 | 换网络测试，再检查 Mihomo 的下载方式是否设置了代理 | 请求在合理时间内完成，并能看到正文 |
| 返回 200 但仍解析失败 | 内容格式、字段或内核兼容性 | 保存正文，检查 YAML、URI、Base64 三种格式是否被混用 | 正文能被 Mihomo 识别并生成代理集合 |
HTTP 标准中，403 表示服务器理解请求但拒绝履行，404 表示当前资源没有可用表示；408、502、503、504 则分别涉及请求超时、网关错误、服务暂不可用或上游响应超时。状态码只能缩小范围，不能单独证明是账号失效。可对照 RFC 9110：HTTP 语义与状态码定义。
步骤一：用浏览器和 curl 做一次独立验证
先在浏览器地址栏打开订阅链接。浏览器可能直接下载文件，也可能显示一段文本；重点不是页面是否好看，而是响应后是否出现配置正文、节点 URI 或 Base64 内容。如果显示登录页、HTML 错误页或 JSON 错误信息，Mihomo 通常也无法把它当作有效订阅。
如果电脑装有 curl，可在命令行执行下面的检查。请把示例地址替换为你自己的订阅链接，不要把包含令牌的真实链接发布到截图、工单或公开聊天中。
curl -sS -D - -o subscription.body "替换为你的订阅链接"
# 查看响应正文前 20 行
head -n 20 subscription.body这条命令的目的，是把响应头保存到终端、把正文写入本地文件。Windows PowerShell 没有 head 时，可使用：
Get-Content .\subscription.body -TotalCount 20判定时看两项：第一，响应头中的 HTTP 状态是否为 200；第二，正文是否是订阅数据，而不是登录页面、验证码页面、HTML 错误页或一段服务端报错。200 只代表请求成功返回，不代表内容一定符合 Mihomo 配置格式。
步骤二：根据 Mihomo 日志区分格式错误
Mihomo 的代理集合可以通过 proxy-providers 配置远程 HTTP 地址，常用字段包括 type、url、path 和 interval。其中 HTTP 类型需要配置 url，本地保存路径还必须满足 Mihomo 的路径安全限制。字段定义以 Mihomo 文档：代理集合配置 为准。
如果日志出现 yaml: unmarshal errors、format invalid 或类似“无法把字符串解析为代理集合”的信息，优先检查订阅正文格式。Mihomo 文档明确区分 YAML、URI 和 Base64：三种内容不能混写在同一个文件中；URI 或 Base64 内容也不需要额外添加 proxies: 字段。可参照 Mihomo 文档：代理集合内容格式。
- 正文以
proxies:开头：通常应按 YAML 配置内容处理，继续检查缩进、字段名称和节点类型。 - 正文是一行或多行
ss://、vmess://等 URI：不要再套一层proxies:，应使用客户端提供的订阅导入入口。 - 正文是一长串 Base64 字符：不要手动随意替换字符或拼接 YAML；先确认服务提供方给出的格式与 Mihomo 当前导入方式匹配。
- 正文是 HTML、登录页或 JSON 错误：先回到链接和账号检查，不要把错误页面保存成配置文件。
步骤三：403、404、超时分别怎么处理
403：先检查权限和账号，不要只更换客户端
403 的含义是服务器拒绝完成请求，但 RFC 9110 也指出，拒绝原因不一定只与凭据有关。因此应依次核对：是否复制了完整链接、链接是否包含被截断的参数、账号是否仍可使用、服务提供方后台是否要求重新生成订阅，以及当前网络是否需要特定访问方式。若浏览器和 Mihomo 都得到 403，问题更偏向链接或服务端权限；若浏览器正常而 Mihomo 为 403，则比较请求方式、请求头和客户端配置。
404：重新生成链接并排除复制错误
404 只说明服务器没有提供当前请求对应的资源，并不能直接证明账号已经失效。重新从后台复制一次完整链接，检查前后是否多出空格、换行或缺少字符，再用浏览器和 curl 复测。若新链接仍返回 404，应在服务提供方后台核实链接是否被重置或资源路径是否改变。
超时：做直连与换网络的单变量对照
先在同一设备上用浏览器访问，再切换到另一条网络复测，例如移动热点或有线网络。一次只改变一个变量：如果换网络后成功，优先检查 DNS、路由或当前网络到订阅域名的连通性；如果所有网络都超时，再核对订阅地址是否仍有效。Mihomo 的代理集合支持通过指定代理下载或更新，可查看 代理集合配置中的 proxy 字段说明，但不要在没有确认代理链路可用前盲目开启“通过代理更新”。
步骤四：检查配置入口、内核和更新状态
如果订阅链接在浏览器中正常、正文格式也正确，但 Mihomo 仍然没有节点，检查你使用的是哪一种入口：是客户端的订阅管理界面，还是配置文件中的 proxy-providers。官方快速配置示例使用 type: http、url 和更新间隔来声明远程代理集合，可参考 Mihomo 文档：快速配置示例。
- 确认远程订阅地址填在
url，没有误填到本地文件路径字段。 - 确认 provider 名称唯一；官方文档要求名称必须存在且不能重复。
- 确认本地
path没有指向被系统拒绝的目录；必要时先使用默认目录测试。 - 保存配置后重新加载或重启 Mihomo，再观察日志是否出现 provider 成功更新，而不是只看界面上的旧节点。
- 若日志出现未知字段、协议字段不支持或启动阶段的配置解析错误，到 Mihomo 官方 Releases 核对当前版本说明，再决定是否升级。不要只凭网上教程填写未在当前文档中确认的字段。
如果问题只在电脑睡眠或合盖后出现，可能是定时更新没有按预期触发。Mihomo 官方仓库的 Issue #3327 记录了与系统休眠后 provider 更新延迟有关的复现讨论；遇到这种现象，可先手动刷新订阅或重启核心，并记录发生时间、设备系统和日志，再判断是否属于同类问题。该 Issue 是问题报告，不等于所有设备都会出现相同现象。
官方 API 文档还列出了代理集合查询和更新接口，包括 /providers/proxies 与针对具体 provider 的更新接口；只有在你明确启用了外部控制器并了解认证配置时才使用，不建议把带有密钥的控制器地址直接发给他人。详情见 Mihomo API 文档。
最后的自查清单：什么时候可以判断问题已解决
- 订阅链接在浏览器或 curl 中能得到稳定响应，且不是 HTML 登录页或错误页。
- HTTP 状态与日志现象一致：403、404、超时和格式解析错误分别按对应路径处理。
- 正文格式只采用 YAML、URI 或 Base64 中的一种，没有额外套用冲突字段。
- Mihomo 日志显示 provider 已完成更新，配置界面能看到节点数量或代理集合内容变化。
- 重启 Mihomo 后配置仍能正常加载，没有新的
Parse config error或字段解析错误。 - 如果只有某个网络失败，已经完成换网络对照；如果只有睡眠后失败，已经记录手动刷新或重启是否恢复。
仍无法判断时，保留三份材料再反馈：订阅请求的 HTTP 状态、响应正文的前几行脱敏内容、Mihomo 失败时的完整日志片段。不要提交包含完整订阅令牌、账号密码或外部控制器密钥的截图。
常见问题
Mihomo 订阅导入失败，浏览器能打开就说明链接没问题吗？
不一定。浏览器能打开只说明请求得到了响应，还要确认正文不是登录页、HTML 错误页或 JSON 提示，并检查内容是否属于 Mihomo 能识别的 YAML、URI 或 Base64 格式。
Mihomo 导入订阅出现 403，是不是一定要升级内核？
不是。403 首先表示服务器拒绝请求，可能与链接权限、账号状态、访问策略或请求方式有关。先用浏览器或 curl 对照测试，再检查账号和链接；只有日志同时提示字段或协议不支持时，才需要核对内核版本。
订阅返回 200，但 Mihomo 仍提示 YAML 解析错误怎么办？
保存响应正文并检查格式。YAML、URI、Base64 不能混写；如果正文是 URI 或 Base64，不要再额外添加 proxies 字段。随后对照 Mihomo 的代理集合内容文档检查导入入口。
Mihomo 订阅更新一直转圈，换节点有用吗？
不一定。先区分订阅下载和节点连接：如果订阅请求本身超时，换节点只有在更新请求明确通过代理且该代理可用时才可能有帮助。建议先换网络，再检查 DNS、订阅地址和 provider 的下载设置。
电脑睡眠后 Mihomo 订阅不自动更新，应该怎么做？
先手动刷新订阅或重启 Mihomo，观察是否立即恢复，并记录系统、时间和日志。官方仓库存在关于系统休眠影响 provider 定时更新的 Issue 讨论，但具体表现仍需按设备和版本复现。