故障排查 预计阅读 12 分钟

Clash 订阅链接失效怎么办:解析失败与更新报错的自查步骤

订阅导入报错或节点列表为空,原因通常集中在链接过期、格式不兼容与网络被拦三类。按顺序自查订阅地址、User-Agent、转换服务与本地缓存,多数问题可自行定位解决。

先判断故障发生在哪一层

Clash 客户端更新订阅时，实际要连续完成几件事：访问订阅地址、跟随重定向、下载响应内容、识别配置格式、解析 YAML，最后把代理节点和策略组写入本地配置。界面上短短一句“更新失败”，可能对应其中任何一步。先定位层级，比反复点击更新更有效。

排查前先记录三项信息：错误出现的准确时间、客户端显示的完整报错、当前网络环境。若条件允许，再换一次网络，例如从家庭宽带切到手机热点。不要一开始就同时修改 DNS、系统代理、TUN 和订阅地址，否则即使恢复，也很难知道是哪一步起作用。

常见现象与对应方向

界面现象 优先检查 常见原因
HTTP 401 或 403 订阅权限、请求头 令牌失效、User-Agent 不符合服务端要求
HTTP 404 或 410 订阅地址 链接被撤销、套餐重置后旧地址作废
HTTP 429 更新频率 短时间请求过多，触发服务端限流
连接超时 网络、DNS、代理回环 域名不可达、更新请求走了失效代理
解析 YAML 失败 响应正文、格式 下载到网页、JSON 错误信息或缩进错误的配置
更新成功但节点为 0 订阅内容、过滤条件 返回空配置、格式不兼容、客户端筛选掉全部节点

检查订阅地址、状态码与返回内容

订阅链接往往带有一段访问令牌。令牌可能因为重置订阅、修改账户、服务到期或后台安全策略而变化。复制链接时也容易多带空格、换行或聊天软件附加的标点。应从服务提供方的控制面板重新复制完整地址，再粘贴到纯文本编辑器核对。

浏览器能打开，不等于客户端一定能更新

浏览器会自动处理 Cookie、页面登录和部分跳转，Clash 客户端通常只携带普通 HTTP 请求头。若打开链接后看到登录页、验证码页、套餐说明或一段 HTML，客户端拿到的也可能是这些页面，而不是代理配置。正确响应通常是 YAML 文本、Base64 编码文本，或对应客户端支持的订阅格式。

在 macOS、Linux 或已安装 curl 的 Windows 环境中，可以先查看响应头。下面使用的是示例域名，不要把真实订阅令牌发到公开聊天记录或截图中。

curl -I -L --max-redirs 5 "https://sub.example.net/api/client/abc123"

-I 只请求响应头，-L 允许跟随重定向，--max-redirs 5 把跳转次数限制为 5 次。重点观察最终状态码、content-type 和是否存在循环跳转。订阅服务常见的正常状态是 200；301、302、307 或 308 可以是正常迁移，但最终仍应落到 200。

状态码应该怎样处理

  • 401 Unauthorized：令牌无效或链接需要额外身份信息。重新生成订阅地址，不要连续尝试旧链接。
  • 403 Forbidden：服务端拒绝当前请求。可能限制了客户端类型、来源地区或请求频率，应检查 User-Agent 和账户状态。
  • 404 Not Found：路径不存在。常见于复制不完整、链接被截断或后台已经更换接口。
  • 410 Gone：资源被明确撤销，通常应重新生成链接。
  • 429 Too Many Requests：请求过密。暂停 10 至 30 分钟，再手动更新一次，不要设置一分钟级自动刷新。
  • 500、502、503、504：服务端或上游网关异常。换网络只能用于确认问题，通常需要等待服务恢复。

如需查看少量响应正文，可以限制下载大小，避免把完整节点信息打印到终端历史中。更稳妥的方式是下载到仅自己可访问的临时文件，再检查文件开头。

curl -L --max-time 20 \
  -A "Clash.Meta" \
  "https://sub.example.net/api/client/abc123" \
  -o subscription-check.txt

head -n 12 subscription-check.txt

如果开头出现 <!doctype html>、<html>、验证码文字或 JSON 错误对象，说明下载到的不是 Clash 配置。若正文只有一行很长的字母、数字、加号、斜杠和等号，它可能是 Base64 订阅，需要由兼容的客户端或转换流程处理。

处理 User-Agent 与格式不兼容

部分订阅接口会根据 User-Agent 返回不同格式。例如同一个地址，对浏览器返回网页，对 Clash 返回 YAML，对其他客户端返回另一种编码。客户端升级、迁移到 mihomo 内核或更换图形界面后，请求头可能发生变化，因此会出现“旧客户端能更新，新客户端报错”的情况。

先使用服务方提供的客户端类型

若订阅控制面板提供 Clash、Clash Meta、Mihomo 等导出选项，应优先重新生成对应类型的链接。不同导出项可能不仅修改 User-Agent，还会改变策略组、节点字段和规则结构。只在客户端里手工改名称，未必等同于重新选择订阅格式。

部分客户端可以在订阅编辑页设置 User-Agent。菜单名称因软件而异，常见路径是「订阅」→「编辑」→「高级设置」→「User-Agent」，或「设置」→「参数设置」→「订阅请求头」。可依次尝试服务方明确支持的值，例如：

Clash
Clash.Meta
mihomo

不要一次填写多个值，也不要凭空增加浏览器 Cookie。修改后先保存，再手动更新一次。若服务器返回 403，而切换为服务方指定的 User-Agent 后恢复 200，基本可以确认是请求头识别问题。

Clash 配置需要完整结构

标准的完整配置通常包含代理、策略组和规则等部分。最小结构可能类似下面这样：

mixed-port: 7890
mode: rule

proxies:
  - name: Example
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Example
      - DIRECT

rules:
  - MATCH,PROXY

如果下载内容只有若干 ss://、vmess:// 或其他分享链接，它属于通用节点订阅，不一定能被只接受 Clash YAML 的导入入口直接读取。反过来，包含 proxy-providers 的完整配置也不能简单当成单个 provider 文件使用。导入前要确认入口需要的是“完整配置”“节点订阅”还是“代理集合”。

YAML 解析错误的几个细节

  • YAML 缩进应使用空格，Tab 可能导致解析失败。
  • 冒号后通常需要空格，例如 mode: rule。
  • 节点名称包含冒号、井号或特殊符号时，服务端应正确加引号。
  • proxy-groups 引用的节点名必须与 proxies 中的名称一致。
  • 旧版 Clash 不认识的 mihomo 扩展字段，可能触发字段校验错误；升级客户端或选择兼容导出格式更合适。

排查网络被拦、DNS 与代理回环

当状态显示连接超时、TLS 握手失败或域名解析失败时，问题通常发生在配置下载之前。此时继续调整 YAML 没有意义，应先确认订阅域名能否解析和建立 HTTPS 连接。

用两个网络做交叉测试

  1. 在当前 Wi-Fi 下关闭 Clash 的系统代理和 TUN，直接更新一次。
  2. 切换到手机热点，再更新一次。
  3. 如果热点正常、原网络失败，重点检查原网络的 DNS、网关过滤和 IPv6 路径。
  4. 如果两个网络都返回同一个 403 或 404，问题更可能在链接或服务端，而不是本机网络。

检查域名解析时，可以使用系统自带工具。若普通域名可以解析，只有订阅域名失败，可临时把 DNS 调整为网络环境中稳定可用的解析服务器后重试。修改前记录原值，测试完成后再决定是否保留。

nslookup sub.example.net

curl -v --connect-timeout 10 \
  "https://sub.example.net/api/client/abc123" \
  -o subscription-check.txt

curl -v 会显示解析到的 IP、TCP 连接和 TLS 过程，但也可能输出请求路径，因此日志不要公开转发。若停在域名解析阶段，检查 DNS；若停在连接阶段，检查网络路径；若 TLS 报证书域名不匹配或过期，应停止更新并等待服务端修复，不应在客户端长期关闭证书验证。

避免订阅更新走进失效代理

一些客户端允许订阅下载“使用代理”。当当前节点已经失效，而更新请求又被强制送入该节点，就会形成一个小死结：想更新节点，更新请求却依赖旧节点。可在订阅设置中关闭“通过代理更新”，或临时退出系统代理后直连更新。

本地常见监听端口包括 HTTP 端口 7890、SOCKS 端口 7891、混合端口 7890，以及外部控制端口 9090，但这些都可以被用户修改。若终端环境设置了 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY，即使客户端界面已关闭系统代理，curl 仍可能继续走本地端口。

env | grep -i proxy

curl --noproxy "*" -I -L \
  "https://sub.example.net/api/client/abc123"

如果普通 curl 失败，而加上 --noproxy "*" 后成功，说明问题在代理链路，不在订阅链接本身。Windows PowerShell 用户还应检查当前会话中的代理环境变量，以及「设置」→「网络和 Internet」→「代理」里是否保留了手动代理。

清理本地缓存并重建订阅记录

链接和网络都正常，客户端仍显示旧节点、空列表或固定时间的错误，可能是本地缓存没有替换成功。常见原因包括配置文件正被占用、磁盘权限异常、客户端崩溃后留下半写入文件，或订阅记录保存了旧请求头。

采用可回退的处理顺序

  1. 导出当前可用配置，并记下自定义规则、覆写设置和策略组选择。
  2. 完全退出客户端，确认菜单栏、系统托盘和后台进程都已结束。
  3. 重新启动客户端，以普通方式手动更新一次。
  4. 仍失败时，新建一条订阅记录，不覆盖旧记录，粘贴重新生成的地址。
  5. 新记录更新成功后，再迁移自定义覆写并删除旧记录。

不建议直接删除整个应用数据目录。许多图形客户端会把订阅缓存、运行配置、日志、覆写脚本和界面设置放在同一位置，一次清空会扩大恢复成本。更稳妥的方法是使用客户端提供的「配置」→「订阅」→「删除缓存」或「重建配置」功能；若没有该选项，再依据对应客户端文档定位单个订阅缓存文件。

更新成功但仍没有节点

先确认界面显示的更新时间确实发生变化，再检查订阅正文是否包含节点。若原始响应有节点，而客户端显示 0 个，继续查看以下设置：

  • 节点名称过滤器是否设置了过窄的包含条件。
  • 排除正则是否误匹配所有节点，例如过于宽泛的 .*。
  • 订阅覆写是否删除了 proxies 或替换了策略组。
  • 客户端是否只载入了 provider，但主配置没有引用该 provider。
  • 配置切换是否仍停留在旧文件，而不是刚更新的新配置。

mihomo 的 provider 配置还需要由策略组引用。例如已经定义 proxy-providers，但任何策略组都没有写入对应的 use，节点就不会出现在该策略组中。

proxy-providers:
  airport:
    type: http
    url: "https://sub.example.net/provider.yaml"
    interval: 3600
    path: ./providers/airport.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - airport
    proxies:
      - DIRECT

interval: 3600 表示每 3600 秒检查一次。实际更新间隔应结合服务端限制设置，通常没必要每隔几分钟刷新。更新太频繁既不会让节点更快，也更容易遇到 429 限流。

按顺序完成一次完整自查

如果报错信息不明确，可以按下面的固定流程操作。每完成一步只改一个变量，并记录结果。这样即使最后需要联系服务提供方，也能给出足够清楚的证据。

  1. 保存旧配置：导出仍可工作的配置和自定义规则。
  2. 重新复制地址：从账户控制面板生成适用于 Clash 或 mihomo 的订阅。
  3. 查看 HTTP 状态：确认最终响应是 200，而不是登录页、错误页或循环重定向。
  4. 核对响应格式：区分完整 YAML、provider 文件、Base64 文本和网页内容。
  5. 调整 User-Agent：使用服务方明确支持的 Clash、Clash.Meta 或 mihomo 标识。
  6. 绕过旧代理：关闭“通过代理更新”，检查 7890、7891 等本地端口与环境变量。
  7. 更换网络测试：用手机热点区分本地网络故障与服务端故障。
  8. 新建订阅记录：避免旧缓存、旧请求头或旧覆写继续影响结果。
  9. 检查过滤与引用：确认节点没有被正则过滤，provider 已被策略组引用。
  10. 控制更新频率：遇到 429 后暂停请求，自动更新建议按小时设置。

需要反馈给服务提供方时，建议附上发生时间、最终 HTTP 状态码、客户端名称与版本、所用 User-Agent、是否能在其他网络复现。订阅地址只保留域名和接口类型，令牌部分应遮盖。清楚的信息通常比一句“Clash 更新不了”更容易得到有效处理。

Clash 客户端下载 查看各平台安装包