Clash 订阅更新失败、解析报错的常见原因与逐项自查

先区分订阅拉取、配置解析与内核加载

“更新失败”不等于节点失效。一次订阅更新通常包含三个环节：客户端向订阅地址发起请求，收到文本后解析配置，再把生成的配置交给内核检查或加载。任一环节失败，都可能在界面上表现为红色提示。排查的第一步，是保留完整错误，而不是连续点击更新。

桌面客户端通常在「订阅」或「配置」页面提供更新入口，在「日志」页面显示细节；具体名称随客户端版本变化。记录客户端版本、内核名称与版本、失败时间，以及手动更新还是定时更新。Clash、Clash Meta（现称 mihomo）的配置能力并不完全相同，只记录应用名称不足以判断兼容性。

订阅链接过期、授权失败与服务端限制

确认复制的是订阅地址，而不是管理页面

订阅地址通常带有令牌、查询参数或专用路径。账户后台的网址、登录页面、二维码图片地址都不能直接当作订阅使用。从提供方后台重新复制“Clash”或“mihomo”格式入口，检查开头和结尾是否多了空格、换行、中文引号。若从网页源码复制，还要注意 & 可能是 HTML 转义后的分隔符，并非原始链接中的字符。

• 401：通常与授权有关。检查令牌是否已重置、账户是否过期；具体含义以提供方说明为准。
• 403：可能是访问策略、来源 IP、User-Agent 或账户权限限制，不能直接认定为“链接已过期”。
• 404：检查接口路径是否变更、链接是否被截断，以及旧订阅是否已撤销。
• 429：停止重复更新，按响应中的 Retry-After 或提供方说明等待；多设备的定时刷新也可能累计触发限制。
• 502、503、504：优先考虑服务端或中间网关异常，保留发生时间，稍后重试。

浏览器能打开，不代表客户端拿到了相同内容

浏览器可能携带登录 Cookie，也可能通过网页验证后才显示内容；客户端通常不会共享这些会话。即使 HTTP 状态码是 200，正文也可能是登录页、验证码页面或“流量已用尽”的文字。应检查最终响应内容，而不只看状态码。不要把订阅地址贴到公开在线检测器，令牌通常足以访问账户对应的节点信息。

本地网络拦截：按 DNS、TLS、代理路径检查

订阅下载使用的网络路径与节点连接不一定相同。某些客户端由图形界面下载配置，另一些交给独立组件处理；系统代理、TUN 与客户端自己的“通过代理更新”设置，都可能影响结果。浏览器能访问网站，只能证明浏览器当前路径可用。

1. 检查系统时间。日期、时区或时钟明显错误时，TLS 证书验证可能失败。先恢复自动校时，再重试一次。
2. 检查域名解析。Windows 可运行 nslookup 后接订阅主机名；macOS、Linux 可使用 dig。这里只输入主机名，不要附带令牌路径。
3. 比较两种网络。在相同客户端、相同配置下改用手机热点。热点成功而当前网络失败时，优先排查路由器 DNS、企业网关、门户认证或防火墙。
4. 检查本地代理监听。如果更新依赖 127.0.0.1:7890，确认内核已启动且实际监听该端口。7890 只是常见示例，应以当前配置的 mixed-port 或 HTTP 代理端口为准。
5. 只切换一个变量。分别测试直连更新和通过可用代理更新，记录结果。不要同时更换 DNS、打开 TUN、修改规则，否则无法判断是哪项起作用。

connection refused 常见于目标端口没有进程监听，i/o timeout 则可能发生在连接或读取阶段；两者需要结合日志里的目标地址判断。若目标是本机代理端口，先修复本地服务；若目标是订阅服务器，再查外部链路。

User-Agent 限制与订阅输出格式

User-Agent 是 HTTP 请求头。订阅服务可能据此区分客户端，返回完整 Clash 配置、仅节点列表，或其他格式。浏览器与客户端请求同一地址时，收到不同内容并不罕见。部分服务还要求在链接参数中明确指定目标格式，不能仅靠修改请求头解决。

核对请求端，而不是只改 YAML

如果客户端提供“订阅 User-Agent”选项，按服务方文档填写，并记录原值。不要随意伪装成不相关客户端；服务方可能因此返回不兼容的字段。完整配置的首次下载发生在解析 YAML 之前，因此在该 YAML 内增加某个请求头字段，通常不能改变这次下载请求。

mihomo 的 proxy-providers 可在支持相应字段的版本中配置提供者请求参数，但那是内核拉取节点提供者的请求，与图形客户端更新整份订阅不是同一个入口。遇到更新失败时，先确认日志指的是配置订阅还是某个 provider。

确认响应属于哪一种数据

需要转换格式时，优先使用订阅提供方支持的导出方式或可信的本地工具。第三方在线转换服务能够看到原始链接和节点凭据，应将其视为具有账户访问能力的服务，而不是普通文本编辑器。

YAML 解析报错：先看正文，再看行号

出现 mapping values are not allowed、did not find expected key 或 cannot unmarshal 时，先用本地文本编辑器打开下载结果。若开头是 <!DOCTYPE html>，应回到授权和网络环节排查；继续调整 YAML 缩进没有意义。

逐项检查缩进、类型与引用

• 缩进：使用空格，不用 Tab；同一层级保持一致。错误行号可能只是解析器无法继续的位置，真正问题可能在前一行。
• 冒号与引号：包含“冒号后接空格”的名称应使用引号包裹，例如 name: "香港: 01"。不要用中文弯引号替代 YAML 引号。
• 字段类型：端口通常是数字，布尔值通常是 true 或 false；proxies、rules 等列表需要正确的短横线结构。
• 重复键：不要在同一级写两段 dns: 或 rules:。不同解析器对重复键的处理可能不同，合并后再验证。
• 名称引用：策略组引用的节点、规则指向的策略组必须存在，并且名称一致。订阅更新后节点改名，旧的手动引用也会失效。

以下配置只用于检查本地解析与加载链路，所有连接直连，不包含远程节点。将它另存为独立测试文件，不要覆盖已有订阅：

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: "出口选择"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出口选择

该示例能通过而订阅不能通过，说明问题更接近订阅内容、合并脚本或字段兼容性；它不能证明外部订阅地址可访问，也不能用于测试代理节点连通性。若提示端口占用，先停止已有实例，或换一个未占用端口再加载。

使用 mihomo 命令行时，可在独立目录执行下面的配置检查。文件名 subscription-test.yaml 指刚保存的测试文件；如果配置包含远程提供者，检查过程仍可能涉及文件或网络依赖，并非纯 YAML 语法检查。

mihomo -t -f subscription-test.yaml

内核不兼容、配置合并与更新后的加载失败

YAML 能解析，不代表内核能够使用。订阅中的节点协议、传输选项、规则类型可能超出当前内核支持范围。出现 unsupported proxy type 或未知规则类型时，先记录客户端“关于”或内核信息页中的实际版本，再对照对应内核的文档判断。应用版本与内核版本是两套信息。

按原始配置、增强配置、运行配置分层定位

1. 保留订阅下载得到的原始文件，确认它能否在匹配的内核中通过检查。
2. 暂时停用该配置绑定的覆写、合并或脚本功能；具体入口以客户端的配置编辑界面为准。
3. 原始文件正常时，逐项恢复本地扩展，检查是否覆盖了 proxy-groups、rules 或提供者名称。
4. 若是 provider 失败，检查它自己的 url、保存路径、响应结构与更新日志，不要只刷新顶层配置。

不要为了让错误消失就删除所有未知字段。某些字段决定协议握手或传输行为，删掉后即使加载成功，节点也可能无法连接。正确做法是选择提供方明确支持的目标格式，或使用能够处理该配置的维护中客户端与内核。

恢复更新后的验证与报障清单

完成修复后，手动更新一次，检查更新时间、节点数量与内核加载日志。节点数量正常只是第一层验证；还应选择一个节点，访问一个常用站点，确认连接记录中的策略组和出口符合预期。延迟测试成功不代表所有业务流量都可用，规则错误仍可能让特定域名走错出口。

• 拉取成功：日志没有 HTTP、DNS 或 TLS 错误，收到的是预期格式而非网页。
• 解析成功：不存在 YAML 行号错误、字段类型错误或缺失引用。
• 加载成功：当前运行配置确实切换为更新后的内容，内核没有回退或继续使用旧配置。
• 实际连接成功：观察一条新建连接，核对命中的规则与策略组，避免仅凭缓存页面判断。

提交足够信息，但隐藏访问凭据

向客户端维护者或订阅提供方报障时，附上操作系统、客户端版本、内核版本、错误时间、HTTP 状态码和相关日志片段。说明直连与代理更新、当前网络与热点测试的差异。截图前遮住完整订阅链接、令牌、节点密码及账户资料；只截掉域名而保留查询参数，仍可能泄露授权。

排查顺序可以收敛为：先确认链接与授权，再检查响应内容和网络路径，随后处理格式、YAML 与内核兼容，最后检查本地覆写。每次只改一项，记录前后结果，比反复重装客户端更容易定位订阅更新失败的具体环节。