Mihomo 订阅导入失败怎么办？按报错定位链接、格式与配置问题
简答：如果 Mihomo 订阅导入失败，先不要删除旧配置：重新复制完整 URL，用浏览器或命令行检查 HTTP 状态码和返回内容，再判断是链接权限、订阅格式、YAML 解析、配置校验还是 Profile 未启用。看到 401/403/404/429 先处理链接或账户状态，看到 YAML parse error 则检查返回内容和配置结构。
定义：Mihomo 订阅导入失败，是指客户端无法下载订阅、无法把返回内容解析成 Mihomo 可用配置，或导入成功但没有启用当前 Profile 的统称。
先看现象：5 层速查表决定排查方向
本文是 CloudFisher 渔云的第三方使用指南，不是任何客户端或服务的官方网站。处理订阅问题时，最重要的是先区分“订阅没有下载下来”和“下载下来但内容不能用”。这两类问题的处理方法不同。
| 现象或日志 | 优先检查 | 处理方向 |
|---|---|---|
timeout、连接超时、无法访问 URL | 当前网络、订阅域名解析、是否配置了下载代理 | 换网络测试，检查 DNS 与订阅域名；不要先改 YAML |
401 Unauthorized | 订阅凭据、Token、登录状态 | 重新复制订阅链接，检查账户或订阅状态；必要时在服务后台重置链接 |
403 Forbidden | 访问权限、请求来源、账户限制 | 确认订阅是否允许当前请求，按服务方说明重新生成或复制链接 |
404 Not Found | URL 是否完整、路径是否已失效 | 删除旧地址并从服务后台重新复制，检查是否混入换行或中文标点 |
429 Too Many Requests | 短时间内重复请求或服务端限流 | 停止连续刷新，等待后再试；同时保留旧 Profile |
| 浏览器显示登录页、验证码页、HTML 或 JSON 错误 | 返回内容是否为配置文件 | 该 URL 不是可直接导入的配置响应，需重新获取订阅链接 |
YAML parse error、yaml: unmarshal | 内容格式、缩进、字段和订阅类型 | 确认返回的是 Mihomo YAML，而非 Base64、单节点链接或其他客户端 JSON |
| 导入成功但节点为空 | Provider、过滤规则、转换模板、当前 Profile | 先检查 Provider 是否更新成功，再关闭覆写或过滤规则复现 |
HTTP 状态码只是服务器对请求结果的描述，不等于 Mihomo 配置解析结果。RFC 9110：HTTP Semantics 将 401、403、404 等状态码分别用于认证凭据缺失、服务器拒绝请求和资源不存在等情况；因此，看到这些状态码时，应先修复链接或访问权限，而不是修改 YAML。
第 1 步：保留旧配置，重新复制并检查订阅 URL
第一次导入失败时，先不要删除已经能用的 Profile，也不要直接重装客户端。保存三项信息：旧配置文件、订阅链接的来源位置、失败时的完整日志。订阅 URL 可能包含 Token、UUID 或其他访问凭据，复制日志或截图前应打码。
- 在服务后台重新复制：进入你所使用服务的账户或订阅页面，使用“复制订阅链接”一类按钮重新生成或复制。具体菜单名称以当前页面为准，无法核实的入口不要凭记忆填写。
- 检查字符：把链接粘贴到纯文本编辑器，确认没有前后空格、换行、中文引号、中文问号或被截断的参数。不要手动把 URL 中的字符替换成相似符号。
- 确认请求方式：浏览器地址栏访问只能用于观察响应，不代表客户端一定能用同样方式获取。浏览器可能已经带有登录 Cookie，而 Mihomo Provider 请求通常是独立请求。
- 记录状态码：在浏览器开发者工具的“网络”面板中查看请求状态；如果不方便使用开发者工具，也可以在终端执行以下命令，仅输出响应头：
curl -I -L --max-time 20 '你的订阅URL'
如果订阅 URL 含敏感凭据，不要把命令和完整结果公开。出现 401 时重点检查凭据是否仍有效；403 可能表示请求被拒绝；404 通常需要重新复制地址；429 则不要连续点击更新。以上判断基于 HTTP 状态语义，具体账户原因仍需以服务方后台或客服说明为准。
第 2 步：确认返回的是 Mihomo 配置，而不是错误页面或其他格式
“浏览器能打开”不等于“返回内容可被 Mihomo 导入”。打开后应观察页面原始内容，而不是只看浏览器是否显示下载成功。正常的 Mihomo 配置通常会出现 YAML 配置结构，例如 proxies:、proxy-groups:、proxy-providers: 或 rules: 等字段；但具体字段取决于服务方提供的配置。
如果返回内容以 <html>、登录表单、验证码提示、JSON 错误对象或普通文本说明开头，说明你拿到的不是可直接导入的 Mihomo 配置。此时不要把错误页面另存为 YAML 再导入，因为文件扩展名改变不会改变内容格式。
| 返回内容 | 能否直接作为 Mihomo YAML | 处理方式 |
|---|---|---|
| 包含 YAML 配置字段的文本 | 可能可以 | 保存为副本后，用 Mihomo 配置校验命令检查 |
| Base64 编码文本 | 不能直接当 YAML 解析 | 确认客户端或服务方是否提供 Mihomo/Clash YAML 格式 |
单条 vmess://、vless:// 等链接 | 不是完整配置 | 需要使用支持该格式的导入方式或转换功能，以当前客户端为准 |
| sing-box JSON | 不是 Mihomo YAML | 不要直接改扩展名，重新获取对应格式或使用明确支持的转换工具 |
| HTML、登录页、验证码页 | 不能 | 返回链接失效、需要登录或被访问控制拦截，重新获取订阅地址 |
Mihomo 的 Provider 文档明确区分了 http、file 和 inline 类型；HTTP Provider 需要配置 URL，且可以设置请求头、下载代理、过滤和健康检查等选项。可对照Mihomo 官方 Proxy Providers 文档检查当前配置到底是在导入远程 Provider，还是在导入一个本地 YAML 文件。
第 3 步：按错误类型处理格式、YAML 与 Provider
看到 YAML parse error 或 yaml: unmarshal
这表示程序已经拿到了一段内容，但无法按当前字段结构解析。先把返回内容保存为副本，再检查缩进、冒号、列表短横线和引号。YAML 对缩进敏感，不能把 Tab 和空格混用。不要直接把整个订阅粘贴到已有配置末尾，先用单独文件复现。
如果日志中出现把字符串解析成配置对象、Base64 或 provider 类型不匹配的提示，优先怀疑“订阅格式选错”。Mihomo 官方仓库曾记录过 Base64 订阅被当作 Provider 配置解析而失败的案例，具体可查看Mihomo Issue #1530：订阅 Base64 解码错误。这类问题不应靠随意替换字符修复，应重新获取与 Mihomo 兼容的格式。
看到 unsupported proxy type
这通常表示返回配置中包含当前内核或客户端不认识的代理类型，或者服务方生成了不适配 Mihomo 的节点字段。先记录完整错误中的代理类型名称，再核对当前客户端实际使用的 Mihomo 内核版本；版本号和支持范围以客户端显示及Mihomo 官方 Release 页面为准。不要仅凭文件名判断内核版本，也不要把其他内核配置直接改名为 YAML。
Provider 能更新但节点为空
这时要区分“Provider 下载成功但没有节点”和“节点下载失败”。检查配置中的 proxy-providers 是否引用了正确名称，path 是否有写入权限，filter 或 exclude-filter 是否把所有节点过滤掉，以及代理组是否通过 use 引用了该 Provider。官方文档说明 Provider 支持过滤、排除过滤、排除类型和健康检查等设置，因此这些字段都可能影响最终显示结果。
最短复现方法是暂时关闭 Merge、Script、过滤条件和额外覆写，只保留一个 Provider 与最小代理组；确认能看到节点后，再逐项恢复设置。每次只改一个变量，并记录修改前后的节点数量，这比一次性重装客户端更容易定位。
第 4 步：用 mihomo -t 校验配置，再确认是否启用
如果订阅内容看起来像 YAML，但客户端仍然导入失败，可以把配置保存为单独文件，使用 Mihomo 核心进行配置测试。命令格式通常为：
mihomo -t -f /配置文件路径/config.yaml
具体参数、工作目录和文件权限会因系统及客户端打包方式不同而变化；如果命令提示找不到程序或参数不支持，应以当前客户端提供的帮助信息为准。测试的目的，是把“客户端界面导入问题”与“核心无法解析配置”分开。
- 校验通过：配置结构至少通过核心检查，下一步查看当前 Profile 是否被选中、是否已经启用，以及客户端是否实际启动了该 Profile。
- 校验失败：根据报错行号回到对应字段，优先检查缩进、字段类型、引用名称和 Provider 内容。
- 校验时能读文件、运行时失败：检查 Provider URL 的访问、DNS、证书、权限和工作目录；远程 Provider 的下载问题不一定会在静态 YAML 校验中出现。
官方管理界面文档也将“激活 Profile、执行 mihomo -t、校验通过后再重启内核”作为配置流程的一部分，可参考MetaCubeXD 官方 README 中的配置校验说明。如果客户端没有暴露命令行入口，就在界面中寻找“配置校验”“日志”“核心日志”或类似功能，具体名称以当前版本为准。
第 5 步：导入成功但不能用，检查启用状态和代理接管方式
“订阅导入成功”只说明配置被保存或 Provider 被添加，不等于流量已经经过代理。先确认当前 Profile 已被选中并启用，再判断问题属于系统代理、TUN、规则模式还是节点连接。
| 现象 | 检查 | 处理 |
|---|---|---|
| 节点列表有内容，但浏览器不走代理 | 系统代理开关、HTTP/SOCKS 或 mixed-port、当前模式 | 确认客户端监听端口与系统代理端口一致；先用规则或全局模式做对比 |
| 系统代理有效，但部分程序不走 | 程序是否使用系统代理、是否需要 TUN | 先确认目标程序的代理支持，再按客户端说明启用 TUN；涉及权限时按系统提示授权 |
| 所有节点显示超时 | 节点连接、DNS、时间、网络出口 | 先测试单个节点和订阅域名；不要把节点超时误判为订阅导入失败 |
| 策略组为空 | Provider 名称、use 引用、过滤条件 | 关闭过滤与覆写后重新加载，检查引用名称是否完全一致 |
排障时建议临时把日志级别调到 debug，复现一次后恢复原设置。Mihomo 官方文档说明，debug 会输出更详细的运行日志；如果使用 Clash API，也可以通过日志接口查看 info、warning、error 和 debug 等级的日志。相关说明见Mihomo 官方通用配置文档和Mihomo 官方 API 文档。
不同环境的最短排查路径与回滚方法
Windows：先复制订阅 URL 到纯文本文件，再在客户端中查看 Profile、Provider 和核心日志。若使用命令行校验，确认 mihomo.exe 路径和配置文件路径；不要在未备份的情况下覆盖原配置。
macOS：优先检查客户端是否获得网络访问和相关系统权限，再查看当前 Profile 的更新日志。若核心无法启动，先保留旧 Profile，使用客户端提供的内核日志判断是配置错误还是程序权限问题。
Android：检查当前应用是否真的完成了配置更新，区分“节点列表为空”和“节点存在但连接失败”。移动网络与 Wi-Fi 可以各测试一次，但不要连续刷新订阅触发服务端限流。
OpenWrt 或 Linux：确认运行用户对 Mihomo 工作目录、Provider 缓存目录和配置文件有读写权限。使用服务管理器查看启动日志；官方服务文档示例中使用 journalctl -u mihomo 查看服务日志，但你的服务名和配置路径可能不同，应以实际部署文件为准。
回滚：如果修改后出现更多错误，停止更新动作，恢复此前可用的 Profile 或配置副本；删除失败的临时文件，不要删除订阅凭据记录。只有在旧配置也无法使用、且已保存日志与链接来源时，才考虑重装客户端。若同一 URL 在不同网络、不同客户端都返回相同的 401、403、404 或 HTML 错误页，应联系服务提供方核对订阅状态；如果只有一个客户端失败，则继续检查该客户端的格式选择、内核版本和覆写设置。
什么时候可以判断不是 Mihomo 本地问题
可以用三组对比缩小范围：第一，用同一 URL 在两个网络环境请求；第二，用同一 URL 在一个干净 Profile 中加载；第三，把一个确认有效的本地 YAML 用 mihomo -t 校验。如果订阅 URL 在多个环境都返回同一错误状态，问题更可能在链接、账户权限或服务端响应；如果 URL 返回正常配置，但只有某个客户端解析失败，问题更可能在客户端内核、格式选择或覆写配置。
最终判断标准是：下载层有正常响应，内容层确实是目标配置格式，核心校验通过，当前 Profile 已启用，且节点与策略组均有内容。缺少其中任一环节，都不能把问题简单归结为“节点坏了”或“客户端需要重装”。
常见问题
Mihomo 订阅链接在浏览器中能打开，为什么客户端仍然导入失败？
浏览器可能使用了登录 Cookie、缓存或不同的请求头，显示网页不代表返回的是 Mihomo 配置。应检查响应状态码和原始内容，确认不是登录页、验证码页、HTML 或 JSON 错误。
Mihomo 看到 401、403、404、429 分别该怎么办？
401 先检查认证凭据或订阅 Token；403 检查访问权限和账户限制；404 重新复制完整 URL；429 停止连续刷新并等待后再试。具体账户状态需以服务后台或服务提供方说明为准。
Base64 订阅可以直接粘贴到 Mihomo YAML 配置里吗？
通常不能直接粘贴。Base64 文本、单节点链接、sing-box JSON 和 Mihomo YAML 是不同格式，应先确认客户端支持的导入类型，或重新获取 Mihomo/Clash YAML 格式。不要只修改文件扩展名。
订阅导入成功但没有节点，应该先看哪里？
先检查 Provider 是否更新成功，再检查过滤条件、排除条件、Merge、Script 和代理组是否正确引用 Provider。关闭这些额外处理后用最小配置复现，能区分返回内容为空与本地规则过滤问题。
什么时候需要联系服务提供方，而不是继续改配置？
如果同一订阅 URL 在多个网络和客户端都返回相同的 401、403、404、HTML 错误页或账户提示，应提供脱敏后的状态码、时间和错误摘要，请对方核对订阅状态。不要公开完整订阅 URL、Token 或 UUID。