Clash 订阅更新失败与解析报错:从链接到 YAML 的逐项自查

先区分下载失败、解析失败与节点不可用

先保留当前可用配置，再查看更新日志。订阅更新涉及下载响应、解析配置、加载内核三个阶段；节点连通测试是后续步骤。把这些问题混在一起处理，容易在链接已经失效时反复改规则，或者在 YAML 格式错误时反复切换节点。

ClashX 与使用 mihomo 内核的客户端，菜单名称和报错措辞可能不同。记录客户端名称、客户端版本、内核名称与内核版本，不要只记录窗口标题。外壳更新到新版本，并不一定表示实际运行的内核也已切换。

第一步：确认复制的是有效订阅地址

检查入口、令牌与套餐状态

1. 在服务商账户页打开“订阅”或“导入”入口，选择明确标注适用于 Clash 或 mihomo 的配置格式。账户登录页、付款页和节点介绍页不是订阅地址。
2. 重新复制一次地址，检查开头是否为 https://，末尾是否混入空格、换行或中文标点。不要删除查询字符串；其中的参数可能决定账户身份与输出格式。
3. 确认套餐未到期、流量未耗尽，且订阅令牌没有被重置。令牌重置后，客户端中保存的旧地址需要同步替换。
4. 如果得到的是二维码或一键导入链接，确认客户端是否支持对应的导入协议。用于唤起应用的链接，与直接返回配置文件的 HTTPS 地址不是同一种入口。

HTTP 401 常见于身份验证失败，403 可能来自账户权限、访问策略或安全验证，404 可能表示路径已经变更。状态码只能缩小范围，不能单凭 403 就断定套餐到期。应结合响应正文与服务商账户状态判断。

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

浏览器可能带有登录 Cookie，或使用了与订阅下载不同的网络路径。若打开链接后出现登录表单、验证码或“请启用 JavaScript”，客户端通常不能把它当作配置解析。此时应寻找可供客户端直接读取的订阅入口，而不是复制网页源码。

第二步：检查订阅下载的网络路径

先看错误发生在域名解析、TCP 连接还是 TLS 握手。no such host 指向解析环节；connection refused 表示连接被拒绝；certificate has expired 或主机名不匹配属于证书问题；context deadline exceeded 则需要结合前后日志确认超时位置。

• 域名解析失败：先确认系统能够解析订阅域名，再检查客户端是否使用独立 DNS。浏览器启用安全 DNS 时，其结果不一定代表系统解析正常。
• 直连超时：若当前仍有可用节点，可在客户端支持的情况下选择通过该节点更新订阅；保留旧配置，避免先删除后失去更新路径。
• 代理更新超时：确认当前代理节点可用。若更新必须依赖已经失效的节点，就会形成“先更新才能连接、先连接才能更新”的循环。
• TLS 报错：检查系统日期、时间与时区，确认订阅域名证书有效。不要把跳过证书验证当作长期修复方案。

系统代理、TUN 模式与订阅下载不一定走同一条路径。有些客户端由应用层下载订阅，有些由内核处理提供器更新。开启 TUN 后问题消失，只能说明路径发生变化，不能证明 YAML 已经正确，也不能据此要求所有用户开启 TUN。

用本机代理做可复现测试

下面适用于 macOS 或 Linux 的 Bash。地址通过交互输入，避免直接写进命令历史；执行时仍可能出现在本机进程参数中，应只在可信设备上操作。响应文件也含敏感信息，不要上传。先测试直连，再用已经确认可用的本机混合端口对照。

umask 077
read -r -s -p '输入订阅地址：' SUB_URL
printf '\n'
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"

curl --noproxy '' --proxy http://127.0.0.1:7890 \
  --location --connect-timeout 10 --max-time 30 \
  --output subscription-proxy.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

7890 只是常用混合端口，需替换为客户端当前实际监听端口。若客户端没有监听该端口，第二条命令报连接拒绝并不能说明订阅服务器有问题。这里没有使用 --fail，因此收到 HTTP 403 时也可能成功保存正文；必须同时检查 HTTP 状态与文件内容。

第三步：确认服务器返回的是哪种内容

HTTP 200 只表示请求获得了成功响应，不表示响应一定是 Clash 配置。用本地文本编辑器打开刚保存的文件，先看开头几行和顶层字段，不要直接运行其中的任何内容。

完整配置与节点提供器不能混用

完整配置通常包含代理、策略组与规则，也可以通过 proxy-providers 引用外部节点。节点提供器文件则常以 proxies: 开头，只负责提供节点。把只含节点的文件作为主配置导入，可能得到节点却没有预期的策略组；把完整配置当作提供器读取，也可能触发格式错误。

使用提供器时，要分别查看主配置加载结果和提供器下载日志。主配置语法通过，不代表远程提供器已更新成功。如果只有某个策略组为空，优先查看该组的 use、提供器状态和过滤表达式，而不是立刻重置全部配置。

第四步：按报错行号检查 YAML 与引用名称

YAML 对缩进敏感。使用空格，不使用 Tab；同一层级保持一致，常用每层 2 个空格。出现 mapping values are not allowed 或 did not find expected key 时，从报错行往上检查 3～5 行：真正的问题可能是上一行的引号未闭合，或列表项缩进错位。

先用最小配置验证加载链路

下面是一份不含远程节点的最小配置，用于区分“客户端无法加载任何配置”和“订阅内容有问题”。它只提供直连选择，不会建立远程代理连接。保存为单独的测试文件，不要覆盖原订阅。

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

proxies: []

proxy-groups:
  - name: "手动选择"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,手动选择

若测试文件提示端口占用，先退出另一个代理进程，或换用空闲端口并同步调整测试命令。端口监听失败属于运行问题，不是 YAML 语法错误。若测试配置能够正常加载，再回到原订阅定位差异。

重点检查四类结构问题

• 字段缺少空格：写成 mixed-port: 7890，不要写成 mixed-port:7890 并期待它仍是相同的键值结构。
• 名称未加引号：节点名含有 : 或 # 等特殊组合时，使用引号保护整个名称；字符串内部的引号也要正确处理。
• 引用名称不一致：策略组中的节点名必须与定义完全一致，包括大小写、空格和符号。重命名节点后，应同步修改引用。
• 顶层字段重复：不要把两份配置直接拼接成两个 proxies: 或两个 rules:。不同解析器可能拒绝重复键或采用不同处理方式，不能依赖覆盖行为。

不要仅凭扩展名判断格式。一个命名为 config.yaml 的 HTML 错误页仍然不是配置。也不要对不理解的字段批量删除：删掉认证信息、传输层参数或 TLS 设置，可能让文件通过语法检查，却使节点无法连接。

第五步：核对实际内核与协议兼容性

Clash 配置属于一组相关但不完全相同的配置格式。mihomo 内核支持的部分协议和字段，旧版 Clash 内核未必支持。例如订阅包含 type: hysteria2 时，需要确认实际运行内核支持该节点类型，而不是把类型名称改成另一个协议。

1. 从客户端的“关于”页面或启动日志记录版本；若界面没有显示内核信息，查看日志中的内核名称与版本行。
2. 核对下载包的平台与架构，确认更新的是正在运行的客户端，而不是另一个安装目录中的副本。
3. 若日志明确提示未知代理类型或不支持的字段，选择服务商提供的兼容格式，或换用支持相应功能的客户端及内核。
4. 不要仅为消除报错而删除 reality-opts、tls 等连接参数。配置被接受与节点能正确握手是两件事。

使用 mihomo 自带检查命令

如果本机已安装命令行版 mihomo，可在终端检查保存的配置。以下命令假定可执行文件在 PATH 中，且测试文件位于当前目录；先核对版本，再执行配置测试。

mihomo -v
mihomo -t -f ./subscription-direct.yaml

测试结果只对应这份文件和这个内核。图形客户端可能还会执行覆写、合并配置或脚本处理，因此终端测试通过后，仍应检查客户端实际生成的运行配置。涉及外部资源的配置也可能在测试或后续加载时需要网络访问，不能把测试通过理解为全部节点在线。

更新成功但节点为空：检查筛选与配置激活状态

先确认当前选中的是刚更新的配置。更新订阅卡片与切换活动配置，在部分客户端中是两个独立动作。节点列表未变化时，检查更新时间、活动配置标识与加载日志，不要连续点击更新造成请求频率限制。

• 节点原文就为空：本地文件为 proxies: []，且没有其他有效节点来源时，向服务商确认账户与输出条件。
• 原文有节点，界面没有：检查是否启用了名称搜索、地区筛选、正则过滤或排除条件，先清空筛选再比较。
• 只有提供器组为空：确认策略组通过 use 引用了正确的提供器名称，并查看该提供器最后一次下载是否成功。
• 导入后才出现错误：临时停用自定义覆写或合并规则进行对照，保留备份；主订阅与附加配置可能分别正确，但合并后发生名称冲突。

如果节点已经列出，只是延迟测试显示超时，应转入连接排查。测试目标不可达、节点出口故障和本地网络阻断都可能产生超时；这些现象不能反推订阅解析错误。此时继续重排 YAML 缩进通常没有帮助。

修复后的验证与可提交的排障记录

每次只改一项，然后重新更新并观察同一处日志。一次更换 DNS、内核、订阅地址与规则，会丢失判断依据。修复完成后，按下面的顺序验收，确认不是仅消除了弹窗。

1. 手动更新一次订阅，确认 HTTP 请求成功，更新时间发生变化。
2. 确认配置解析与内核加载成功，没有缺失节点、策略组或提供器的报错。
3. 选择一个节点，通过实际代理路径访问 HTTPS 页面，再测试需要的应用。浏览器正常不代表所有应用都已走代理。
4. 重新启动客户端，确认活动配置仍然正确；如果使用定时更新，再观察一次计划任务是否成功。
5. 删除排查时生成的敏感响应文件，并清理不再需要的临时配置。

排查顺序保持不变：先确认链接有效，再确认网络能取回响应，然后核对返回格式、YAML 结构与内核兼容。更多端口和规则基础可查阅使用文档；账户链接与自动更新问题可结合订阅常见问题继续检查。