Clash 订阅导入失败：按链接、网络、格式逐层排查
简答：粘贴订阅链接后提示 Failed to fetch、Timeout 或 YAML 错误，先不要重装客户端：先确认 URL 没有被截断，再用浏览器或 curl 查看 HTTP 状态和返回内容，最后检查 DNS、连接、读取超时及配置格式。导入失败通常要区分链接认证、网络可达性、返回内容和客户端兼容性四层，按顺序排查比反复点击更新更快定位问题。
定义：Clash 订阅导入失败，是指客户端无法从远程订阅 URL 下载、保存或解析配置，可能发生在 HTTP 请求、认证、内容格式或本地客户端解析阶段。
先做这一项：确认订阅 URL 和返回内容
最快判断方法是：把完整订阅 URL 放入浏览器地址栏，或在终端使用 curl 查看状态码和响应头；不要只根据页面是否显示乱码判断链接失效。复制前先粘贴到纯文本编辑器，检查 URL 是否被换行、截断、替换了字符，尤其不要漏掉 token、问号、等号和参数。
命令行检查只读取响应头，适合判断 DNS、TLS、重定向和 HTTP 状态；请把示例地址替换成自己的订阅地址，不要把包含 token 的完整命令发到公开位置。
curl -I -L --max-time 20 "https://example.com/subscribe?token=REPLACE_ME"
curl 的 -I 用于只获取 HTTP 响应头，-L 跟随重定向，--max-time 20 设置本次请求的最长时间；参数含义可参考 curl 官方命令行手册。
| 现象 | 优先判断 | 下一步 |
|---|---|---|
| 200，返回 YAML、Base64 或可下载文件 | 服务器已返回内容，链接不一定失效 | 保存返回内容，继续检查格式、客户端和 User-Agent 差异 |
| 301/302 | 订阅地址发生重定向 | 用 -L 重试，并查看客户端是否支持重定向 |
| 401/403 | 认证、权限或 token 状态异常 | 回到服务商用户中心重新复制链接，必要时重置 token |
| 404 | 路径错误、链接被撤销或接口已变化 | 不要修改路径猜测，重新获取完整订阅地址 |
| 5xx | 服务端、反向代理或上游接口异常 | 稍后重试并保留状态码；若持续出现，联系订阅提供方 |
| Could not resolve host / no such host | DNS 解析阶段失败 | 检查域名、DNS 和当前网络，不要先改 YAML |
| Connection timed out | 已开始连接但未在期限内建立连接 | 切换网络或使用已有可用代理再次请求 |
| 读取过程中超时 | 连接建立后，服务器或链路迟迟没有返回完整内容 | 检查服务端响应、代理链路和内容大小 |
浏览器可能直接下载文件，也可能把 Base64 显示成难以阅读的一行字符；这两种现象都不能单独证明链接失效。部分服务端还会根据 User-Agent、请求头或重定向行为返回不同内容，因此“浏览器能打开”不等于客户端一定拿到相同配置。
按三层区分 Timeout：DNS、连接和读取
Timeout 不是单一故障，先看它发生在哪一层：DNS 失败处理域名解析，连接超时处理到服务器的 TCP/TLS 建连，读取超时处理已连接但没有及时返回完整内容。
- DNS 解析失败：如果日志或命令行出现
Could not resolve host、no such host，先检查订阅域名拼写、系统 DNS 和当前网络。Mihomo 文档说明，DNS 请求可按规则处理；需要通过代理完成 DNS 时，应配置相应的代理 DNS，避免出现“先解析域名、但代理本身又依赖该域名”的循环问题，具体字段见 Mihomo DNS 配置文档。 - 连接超时：如果域名能解析，但 TCP 或 TLS 一直建立不了连接，先切换 Wi-Fi 与手机热点，再用一个已经确认可用的节点作为订阅下载代理。Mihomo 的代理集合配置支持为 HTTP provider 指定
proxy，也支持header、interval和size-limit等字段，见 Mihomo proxy-providers 文档。 - 读取超时：如果连接已经建立，但下载配置迟迟没有完成，可能是服务端生成配置慢、返回内容过大、代理链路中断或客户端等待时间太短。先保存命令行输出和时间点，再检查同一 URL 在不同网络下是否返回一致内容。
如果关闭当前代理后浏览器反而能打开订阅地址，本文判断是当前规则、节点或代理链路影响了订阅请求；此时优先尝试让订阅域名直连，或在客户端的“更新代理”选项中改用已确认可用的节点。不要把直连规则直接写进每次更新都会覆盖的订阅正文；应使用客户端提供的覆写、Merge 或脚本机制，并以当前客户端文档为准。
返回内容能打开，但 Clash 仍然导入失败
看到内容不代表内容就是当前客户端能解析的配置，先确认返回的是目标客户端支持的格式，再判断是否需要转换。常见返回内容可以按下面方式处理。
- Clash/Mihomo YAML：通常能看到类似
proxies:、proxy-groups:或其他配置字段。YAML 对缩进、冒号、引号和特殊字符敏感，可参考 YAML 官方规范索引理解语法边界。 - Base64 编码文本：可能是编码后的节点列表，也可能是服务端为某类客户端提供的订阅。不能仅凭“看起来像乱码”判定无效；先确认当前 Clash 客户端是否支持该订阅类型，或者回到订阅面板选择明确标注的 Clash/Mihomo 格式。
- JSON：可能属于其他客户端或转换接口的格式。若当前客户端日志提示解析失败，应重新获取与客户端匹配的配置格式，不要只改文件扩展名。
- HTML 登录页、验证码页或错误页：客户端拿到的不是配置，而是网页。常见原因包括 token 失效、权限不足、服务端拦截非浏览器请求或订阅地址复制错误。
- 空白内容或只有空节点：导入可能已经完成，但服务端返回的配置没有有效节点，或者客户端的过滤、策略组引用把节点隐藏了。此时应把“导入失败”和“导入成功但无节点”分开处理。
如果使用 Mihomo 的 HTTP provider，官方配置要求 type: http 时提供 url；path 用于保存文件，未填写时会按 URL 生成文件名，相关字段见 Mihomo proxy-providers 文档。示例配置如下，URL 请替换为自己的地址：
proxy-providers:
provider1:
type: http
url: "https://example.com/subscribe?token=REPLACE_ME"
interval: 86400
如果配置文件本身有 YAML 语法错误，先修复缩进和字段结构；如果 YAML 语法正确但出现 unsupported proxy type，则更像是内核或客户端不认识返回配置中的协议字段。两者不要混为同一种错误。
查看客户端日志：只抓导入时间点的错误
日志排查的目标不是收集整份文件，而是找到导入操作前后几秒内的第一条失败原因。不同客户端、系统和安装方式的日志目录可能不同，因此不再把某一个路径当作所有 Clash 客户端的通用路径。
- 在客户端设置、帮助或诊断页面打开日志；菜单名称以当前界面为准。
- 重新执行一次导入或更新，记下准确时间。
- 搜索
fetch、timeout、resolve、tls、parse、yaml、401、403或404。 - 只复制错误行和前后少量上下文，先遮住订阅 URL、token、用户名和节点密码。
如果使用 Mihomo 内核，也可以把日志级别暂时调到 debug，再复现一次；官方文档说明 debug 会输出尽可能多的运行时信息，error 只输出错误和不可用日志，字段说明见 Mihomo 通用配置文档。排查完成后可恢复为 info，避免长期产生过多日志。
| 日志信号 | 所在层 | 处理顺序 |
|---|---|---|
no such host | DNS | 检查域名、DNS 和网络切换 |
connection refused | 目标端口主动拒绝 | 核对地址和端口，确认服务端是否在线 |
context deadline exceeded 或 timeout | 连接或读取未完成 | 结合 curl、网络切换和代理下载分别验证 |
401、403 | 认证或权限 | 重新获取订阅链接并检查账号状态 |
404 | 地址不存在 | 不要反复刷新，回到订阅面板重新复制 |
yaml、parse、mapping values | 内容解析 | 保存返回内容，检查格式、缩进和字段兼容性 |
unsupported proxy type | 字段或协议兼容性 | 确认客户端内核支持该协议，必要时更新到可信发布页中的版本 |
Clash Verge Rev 的官方文档说明其发布地址为 GitHub Release；需要更新客户端时，应从 官方发布页核对版本和文件，不要把搜索结果中的第三方下载页当成发布来源。本文不把某个版本号视为所有客户端的“最新版”。
导入成功但节点为空：先核对数量和策略组
配置已保存但节点为空，优先检查服务端返回内容、过滤条件和策略组引用，不要立刻重装客户端。先把用户中心显示的可用节点数量与客户端实际载入数量进行对照；这里没有统一的“至少多少个节点”标准，应以你的订阅页面和返回配置为准。
- 再次更新订阅并保存返回时间。
- 确认返回内容不是登录页、错误页或空配置。
- 确认客户端使用的是匹配的 Clash/Mihomo 配置格式。
- 检查是否启用了过滤、排除类型或节点名称筛选。
- 如果全局节点存在、只有某个策略组为空，转到本站的 Clash 代理组为空排查，重点检查策略组引用和过滤规则。
Mihomo 文档说明，代理集合可以使用 filter、exclude-filter 和 exclude-type 过滤节点；因此“返回配置有节点”和“某个策略组显示节点”不是同一个判断。若客户端支持 API，可通过 /proxies 查看当前代理对象及其 provider 来源，接口字段见 Mihomo API 文档。
如果只有部分节点全红或延迟测试失败，说明问题已经从“订阅是否导入”进入“节点连接或测速”阶段，可继续查看本站的 Clash 节点全红排查；不要把节点连通性问题和订阅下载失败混在一起。
安全检查和不同平台的处理边界
订阅 URL 等同于凭证，排查时只在本机使用完整链接；一旦公开粘贴到论坛、工单、截图或代码仓库，应立即在服务商后台重置订阅 token。第三方转换或检测服务如果要求提交完整 URL，意味着 token 可能被该服务接收；能在本机完成检查时，优先使用浏览器、curl 或本地文本工具。
Windows、macOS 和 Linux 桌面客户端的设置入口、日志目录和内核打包方式可能不同。Clash Verge Rev 文档列明其桌面应用面向 Windows、macOS 和 Linux，并通过项目发布页提供安装包；安装来源和当前版本应以 Clash Verge Rev 安装文档及发布页为准。
iOS 和 Android 客户端也不能共用一套菜单名称。先确认客户端是否支持远程配置、Clash/Mihomo YAML 或 provider，再选择对应格式；如果客户端只有导入文件、二维码或特定订阅格式，就按该应用当前帮助说明操作。本文不把某个移动端应用的入口名称泛化到所有客户端。
安全软件或企业网络策略可能拦截客户端联网。建议检查安全软件的联网记录、系统代理和企业网关策略，而不是直接关闭防火墙或跳过 TLS 证书校验；关闭保护措施会扩大风险，也不能证明订阅服务本身可用。
常见问题
Clash 订阅导入失败，需要先重装客户端吗？
通常不应把重装作为第一步。先验证 URL、HTTP 状态、返回内容和日志；只有在链接、网络、格式都排除后，且日志显示客户端或内核本身崩溃，才考虑重新安装。
浏览器能打开订阅链接，为什么 Clash 还是更新失败？
浏览器和客户端可能使用不同的 User-Agent、代理路径或请求头，服务端返回内容也可能不同。先用 curl 查看响应，再检查客户端是否启用了更新代理、是否被系统代理或安全软件拦截。
浏览器打开订阅链接是一串乱码，说明链接失效了吗？
不一定。它可能是 Base64 编码的节点列表，也可能是当前客户端不直接使用的格式；先确认 HTTP 状态为成功，再确认客户端支持的订阅类型，不要仅凭显示效果判定失效。
Clash 返回 401、403、404 分别怎么办？
401 和 403 优先检查 token、账号状态和访问权限；404 优先检查路径或链接是否已被撤销。最稳妥的做法是从订阅服务商用户中心重新复制完整 URL，而不是手工修改地址。
Clash 订阅出现 Timeout，应该改 DNS 还是换节点？
先看日志属于 DNS 解析、连接建立还是读取阶段。DNS 错误先查域名和 DNS；连接超时可切换网络或使用已有可用节点下载；读取超时则检查服务端生成配置、内容大小和代理链路。
导入成功但节点数量为 0，怎么判断是哪一层的问题？
先查看返回内容是否为空、是否为错误页，再对比用户中心显示的节点数量；随后检查过滤条件和策略组引用。若全局节点存在但某个策略组为空，应按策略组配置排查，而不是继续重复导入。
把完整订阅链接交给在线检测或转换工具安全吗？
完整订阅 URL 通常包含 token，应视为凭证。能本机检查就不要上传；如果已经公开或提交给不明服务，立即在服务商后台重置 token，并在所有设备中替换旧链接。
Clash Verge Rev 应该从哪里更新？
以项目文档指向的 GitHub Release 页面为准，核对系统架构、安装包名称和发布说明。不要根据搜索结果中的第三方打包页判断版本，也不要把某个客户端的版本号套用到其他客户端。