Clash 订阅失效与解析失败自查清单:从链接可达性到字段兼容逐项排查

先区分下载失败、解析失败与配置加载失败

客户端显示“更新失败”时，故障可能发生在三个不同阶段。第一阶段是通过 HTTPS 请求取得订阅内容；第二阶段是把响应内容识别为 YAML、Base64 节点列表或其他格式；第三阶段是将已解析配置交给 Clash Meta（mihomo）内核加载。三个阶段的界面提示经常相似，但检查方向完全不同。

故障阶段	常见现象	优先检查项
链接请求	超时、403、404、连接被重置	状态码、DNS、系统代理、订阅有效期
内容解析	unexpected token、invalid YAML、配置为空	响应正文、缩进、编码、订阅格式
内核加载	配置已下载，但切换时失败	字段兼容性、端口占用、规则集与内核版本

先记录完整错误文本、发生时间和当前客户端版本。随后打开客户端日志，将日志级别临时调至“信息”或“调试”。以 Clash Verge Rev 2.x 为例，可从「设置」→「日志」进入；不同客户端的名称略有差异，也可能位于「设置」→「诊断」。完成排查后再恢复常规日志级别，避免长期积累大量记录。

第一步：验证订阅链接是否能够取得内容

检查 HTTP 状态码与跳转结果

在浏览器隐私窗口中打开订阅链接，只能作为初步检查。浏览器可能自动携带 Cookie、跟随跳转或展示下载文件，而客户端使用的是独立网络请求。更可靠的方法是查看最终状态码和响应头。Windows 11 可在 PowerShell 中执行以下命令，macOS 与 Linux 可使用系统自带或本地安装的 curl。

curl -L --max-redirs 5 --connect-timeout 10 \
  --max-time 30 -D headers.txt \
  -o subscription.txt \
  "https://example.com/api/subscription?token=REDACTED"

-L 允许跟随 301、302、307 和 308 跳转，--max-redirs 5 限制跳转次数，连接超时设为 10 秒，总请求时间限制为 30 秒。命令会把响应头保存到 headers.txt，正文保存到 subscription.txt。测试时应在本地替换示例地址，不要把真实令牌写进共享脚本。

200：服务器返回了内容，继续检查正文是否真的是订阅配置。
301、302、307、308：存在跳转。若最终仍是跳转，可能形成循环；若跳到登录页，则客户端无法完成交互式登录。
401、403：令牌失效、权限不足、来源限制或请求策略拦截。
404、410：订阅路径已撤销、套餐迁移后旧地址停止使用，或 URL 在复制时被截断。
429：请求频率过高。暂停自动刷新，等待服务端限制窗口结束后再试。
500、502、503、504：服务端或其上游暂时异常，应结合服务状态与稍后重试结果判断。

检查 URL 是否在复制过程中变化

订阅地址常含 ?、&、=、% 等字符。聊天软件折行、富文本编辑器转义或手工删除末尾字符，都可能让令牌失效。地址前后也不应带引号、全角空格或换行。若服务商控制台提供“复制订阅”按钮，应重新复制完整地址并在客户端中新建配置，而不是继续编辑旧记录。

还要检查系统时间。HTTPS 证书校验依赖本机时钟；日期偏差数天时，日志可能出现证书尚未生效或已经过期。Windows 可在「设置」→「时间和语言」→「日期和时间」开启自动设置时间并立即同步；Android 通常位于「设置」→「系统」→「日期和时间」。

排除系统代理环路与当前节点故障

订阅请求可能走直连，也可能沿用系统代理。常见本地混合端口为 7890，部分客户端默认使用 7897；具体值应以「设置」→「端口设置」中的 Mixed Port 为准。如果客户端内核已经停止，而系统代理仍指向 127.0.0.1:7890，订阅请求就会连接到一个没有监听的本地端口。

关闭客户端中的“系统代理”，再尝试更新订阅。
若直连无法访问订阅域名，重新启动内核，选择一个确认可用的节点后再更新。
若启用了 TUN 模式，先从「设置」→「网络设置」关闭 TUN，建立一次普通请求用于对照。
检查日志是否出现 connection refused 127.0.0.1、i/o timeout 或重复转发到本机端口。

TUN 模式本身不参与 YAML 语法解析，但它会改变订阅请求的路由路径。只有关闭 TUN 后更新成功，才需要继续核对路由排除项、系统代理状态与当前节点可用性；不应直接修改订阅正文。

第二步：确认返回内容确实是可用订阅

查看正文开头，而不是只看文件扩展名

订阅 URL 末尾没有 .yaml 很常见，判断依据应是响应内容。使用文本编辑器打开刚才保存的 subscription.txt，查看前 20 行。一个面向 Clash 或 mihomo 的完整 YAML 配置通常会出现 proxies、proxy-groups、rules、proxy-providers 等顶层字段。

mixed-port: 7890
mode: rule

proxies:
  - name: "Example Node"
    type: ss
    server: 203.0.113.10
    port: 443

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "Example Node"

rules:
  - MATCH,PROXY

如果正文以 <!doctype html>、<html> 或登录表单开头，实际取得的是网页。JSON 错误对象如 {"code":403,"message":"expired"} 也不是 Clash 配置。此时应处理授权或服务端问题，修改 YAML 文件没有作用。

识别 Base64 节点列表与分享链接

一长段仅含字母、数字、加号、斜杠和等号的文本，可能是 Base64 编码的通用订阅。解码后常见内容是逐行排列的 ss://、trojan://、vmess:// 或 hysteria2:// 分享链接。部分客户端能导入这些链接，但将其作为完整 Clash YAML 加载时会报顶层类型错误或找不到 proxies。

优先回到订阅提供方的控制台，选择标注为 Clash、Clash Meta 或 mihomo 的输出格式。格式转换会接触节点凭据，应使用自己控制的本地工具或可信服务端接口。转换完成后仍需检查策略组、规则和 DNS 配置，因为节点列表只描述连接参数，并不等于完整的分流配置。

检查字符编码和文件开头

YAML 文件建议保存为 UTF-8。若文本编辑器显示大量乱码，或者日志出现控制字符相关错误，应重新以 UTF-8 导出。文件开头的 UTF-8 BOM 通常能被现代解析器处理，但某些旧客户端或外层转换脚本可能把它当成字段的一部分。排查时可将文件另存为“UTF-8”并保留原始副本用于对照。

第三步：按行定位 YAML 语法与结构错误

先看日志给出的行号和列号

典型错误包括 did not find expected key、mapping values are not allowed、cannot unmarshal 和 duplicate key。日志中的行号通常指向解析器最终失去结构的位置，真正错误可能位于它前面一至三行。应同时检查报错行、上一项的缩进以及引号是否成对。

使用空格缩进，避免 Tab 与空格混用。
同一层级保持一致缩进，常见写法为每级两个空格。
列表项前的连字符后要保留空格，例如 - name: node-a。
名称包含冒号、井号、花括号或首尾空格时，用引号包裹。
端口应写成整数，例如 port: 443，不要写成包含额外文字的值。

# 错误：proxy-groups 被缩进到 proxies 项内部
proxies:
  - name: node-a
    type: ss
  proxy-groups:
    - name: PROXY

# 正确：两个字段都位于顶层
proxies:
  - name: node-a
    type: ss

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - node-a

区分语法正确与字段类型正确

通过 YAML 语法检查并不代表内核能接受所有字段。例如 port: "443" 在 YAML 中是字符串，而协议配置通常需要整数；udp: "true" 是字符串，规范值应为布尔值 true。日志出现 cannot unmarshal string into Go value 时，应重点核对值类型。

字段	常见正确类型	容易写错的形式
`port`	整数	`"443 tcp"`
`udp`	布尔值	`"true"`
`proxies`	列表	单个逗号分隔字符串
`nameserver`	列表	缩进错误的映射对象
`interval`	秒数整数	`24h`

核对策略组引用和规则目标

语法解析完成后，内核还会校验引用关系。规则末尾的策略名称必须对应已有策略组、代理名称或内置动作。比如规则写成 DOMAIN-SUFFIX,example.com,Proxy，配置中却只有名为 PROXY 的组，大小写差异就会造成目标不存在。策略组中的节点名称同样需要与 proxies 或 use 引用一致。

使用 RULE-SET 时，还要确认相应名称已经在 rule-providers 中定义。provider 的 behavior 应与内容匹配：域名集合通常使用 domain，IP 网段集合使用 ipcidr，包含完整规则语句的集合使用 classical。远程规则集下载失败时，主订阅可能已经解析成功，日志会单独显示 provider 的 URL、状态码或超时信息。

第四步：核对 Clash Meta 内核版本与字段兼容性

确认客户端界面版本和内核版本是两项数据

桌面客户端、移动客户端与 mihomo 内核各有独立版本。界面升级后，内核未必同步切换；同一个订阅在两台设备上表现不同，也经常源于内核版本差异。应从「设置」→「关于」或「设置」→「内核」记录完整版本信息。排查时至少写明客户端名称、客户端版本、内核类型和内核版本，例如“Clash Verge Rev 2.x，mihomo 1.19.x”。

较新的协议与传输字段依赖对应内核支持。配置包含 type: hysteria2、type: tuic、VLESS Reality、WireGuard 或新的 DNS 字段时，旧版 Clash 内核可能返回未知类型或未知字段。解决方向是切换到订阅目标所需的 mihomo 内核，或让订阅服务输出与现有内核兼容的格式，而不是随机删除认证、TLS 或传输参数。

用最小配置确认问题属于节点还是全局配置

保留原始文件副本后，可以制作一份最小测试配置：只保留一个已知节点、一个策略组和一条 MATCH 规则。若最小配置能够加载，再逐段加入 DNS、TUN、rule-providers 与高级协议配置，就能定位具体区块。若单个节点仍报错，重点检查该节点的 type、地址、端口、认证字段和 TLS 参数。

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: test-node
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - test-node
      - DIRECT

rules:
  - MATCH,PROXY

这份示例只用于验证结构能否被加载，127.0.0.1:1080 必须确有 SOCKS5 服务才能建立连接。结构测试通过而网络测试失败，说明 YAML 框架可被内核接受，后续应转向节点可达性和认证参数。

检查端口占用与残留内核进程

配置解析成功后，如果日志显示 address already in use，故障点是监听端口而非订阅格式。常见冲突包括旧内核仍占用 7890、控制器端口 9090 被其他实例占用，或多个客户端同时开启系统代理。完全退出其他代理客户端与残留内核，再重新加载配置；也可临时把 Mixed Port 改为 7897 做对照。

Windows 可执行 netstat -ano | findstr :7890 查看占用进程编号，macOS 与 Linux 可执行 lsof -iTCP:7890 -sTCP:LISTEN。确认进程身份后再结束进程，不要仅凭端口号处理系统服务。

第五步：按结果采取处理办法

链接失效或授权失败

从服务控制台重新生成订阅地址，确认套餐状态和设备限制。
在客户端删除失败记录并新建订阅，避免继续使用缓存 URL。
将自动更新间隔设为合理值，例如 1440 分钟；短时间连续刷新可能触发 429。
若新链接仍返回 401 或 403，保留状态码、时间和已遮盖令牌的日志联系服务提供方。

返回网页、JSON 错误或通用节点列表

确认复制的是订阅接口，而不是用户中心页面地址。
选择 Clash Meta 或 mihomo 格式，重新下载配置。
若只能取得分享链接列表，使用本地转换流程生成 YAML，并自行补充策略组和规则。
转换后先以新配置导入，不覆盖仍可工作的旧配置。

YAML 字段或内核不兼容

根据日志行号检查缩进、引号和字段类型。
对照当前 mihomo 版本支持的配置结构，确认协议类型与 DNS 字段。
使用最小配置逐段恢复，定位到单个节点、规则集或 DNS 区块。
更新内核后重新启动客户端，建立新连接再测试，不沿用旧连接的结果。

完成修复后的验证记录

一次完整验证应覆盖四项结果：订阅请求返回 200；正文是预期格式；配置被 mihomo 内核加载；实际连接按规则进入对应策略组。仅看到节点数量增加，不能证明规则集、DNS 或 TUN 已正常工作。

手动刷新一次，记录耗时。例如在同一网络下连续三次分别为 1.2 秒、1.4 秒和 1.3 秒，结果应较稳定。
打开日志访问一个直连域名和一个代理域名，确认规则命中目标符合预期。
切换策略组后新建连接，旧的 TCP 连接可能继续沿用原出口。
重新启动客户端，再加载一次配置，排除只存在于内存中的临时状态。
恢复合适的自动更新间隔，并确认系统代理与 TUN 状态符合日常使用方案。

排查顺序应保持固定：先看 HTTP 状态和响应正文，再查 YAML 语法与引用关系，最后处理内核版本、端口和运行状态。这样可以避免在链接已经过期时反复编辑配置，也能避免把端口冲突误判为订阅解析错误。