先区分：请求失败还是配置解析失败
Clash 订阅更新通常包含三个步骤：客户端请求订阅地址，读取返回内容，再交给配置处理流程和内核检查。任何一步失败，界面都可能显示“更新失败”。因此，第一步不是重新安装，而是打开客户端的订阅详情和日志，记录完整错误、发生时间以及当前使用的内核。
同一个订阅地址，在浏览器、客户端和命令行里可能收到不同内容。浏览器能打开，只能证明该次请求有响应，不能证明返回的是 Clash 可用配置。已经导入的节点仍能连接，也只说明旧配置可用，不代表订阅接口正常。
| 日志或响应 | 通常意味着什么 | 优先检查 |
|---|---|---|
timeout、connection refused | 请求未正常完成 | 网络路径、代理端口与服务状态 |
401、403 | 认证或访问策略拒绝 | 订阅令牌、账户状态、请求头 |
404、410 | 地址不存在或资源已撤销 | 当前订阅入口与链接是否重置 |
429 | 请求频率受限 | 自动更新周期和重试次数 |
yaml: line … | 正文无法按预期解析 | 返回格式、缩进、特殊字符 |
unsupported proxy type | 内核不支持某节点类型 | 内核版本和订阅输出目标 |
链接过期、账户异常与 HTTP 状态码
重新复制当前订阅地址
进入订阅提供方的账户页面，确认套餐状态、有效期和剩余流量，再从当前入口复制适配 Clash 或 mihomo 的地址。套餐到期、令牌重置、接口迁移和流量耗尽都可能影响响应；具体行为由提供方决定，不能仅凭一个状态码判定账户过期。
- 复制时检查开头和结尾，避免带入换行、空格、引号或聊天软件追加的标点。
- 完整保留查询参数。不要为了“简化链接”删除问号之后的内容。
- 如果地址从网页源码复制而来，注意
&是 HTML 表示，实际链接中的参数分隔符应为&。 - 账户刚重置过订阅令牌时，旧地址可能立即失效。先修改现有订阅项，避免留下多个相同名称的配置。
按状态码处理，而不是连续点击更新
401 常见于认证缺失或失效；403 还可能来自访问限制、风控或请求头策略；404 也可能是接口路径变化。遇到 429，按服务端的 Retry-After 提示等待，没有提示时先暂停自动更新，再咨询提供方。持续重试会增加请求量，不能修复令牌。
500、502、503 更应关注服务端或网关状态。保留错误时间，间隔一段时间再尝试。304 则可能是缓存协商的正常结果，并非天然属于失败，需要结合客户端是否正确保留旧内容判断。
请求超时：检查订阅下载走哪条网络路径
系统代理、TUN 与订阅下载是三个相关但不等同的环节。有的客户端自行下载配置，有的会提供“通过代理更新”的选项；内核中的节点提供器又可能使用独立的更新设置。界面更新失败时，不能直接假定它与浏览器使用同一条路径。
- 在同一网络下记录一次失败日志，区分 DNS 解析失败、TCP 连接失败、TLS 失败和读取超时。
- 确认客户端里实际监听的本地代理端口，不要照抄旧教程。本文命令使用
127.0.0.1:7890，仅适用于该端口确实是 HTTP 或混合代理入口的情况。 - 保留可用旧配置，分别测试直连和通过旧配置代理请求。每次只改变一个条件。
- 如果切换网络后恢复，继续检查原网络的 DNS、网关限制和安全软件，而不是修改节点密码。
用 curl 对照响应
下面命令用于 Linux 或 macOS 的 Bash。地址通过隐藏输入读取，避免直接写入 shell 历史；输入过程中仍应注意设备环境安全。示例限制连接等待为 10 秒、整体请求为 30 秒，并把响应头与正文分别存到本机文件。Windows 环境可使用 curl.exe，但变量输入语法需按所用终端调整。
read -r -s -p '订阅地址：' SUB_URL
printf '\n'
curl --noproxy '*' --connect-timeout 10 --max-time 30 \
-D subscription.headers -o subscription.body "$SUB_URL"
curl --noproxy '' --proxy http://127.0.0.1:7890 \
--connect-timeout 10 --max-time 30 \
-D subscription-proxy.headers -o subscription-proxy.body "$SUB_URL"
unset SUB_URL这里的“直连”是指不使用 curl 的显式代理；如果系统启用了 TUN，连接仍可能被 TUN 接管。需要对照时，在确认不会影响其他任务的情况下临时关闭 TUN，再重复测试。遇到 301 或 302，先检查 Location 指向的域名，确认可信后再考虑用 -L 跟随重定向。
User-Agent：同一地址为什么返回不同格式
User-Agent 是 HTTP 请求头，用于描述请求程序。部分订阅服务根据它选择输出格式，例如向浏览器返回说明页，向特定客户端返回 YAML，或者拒绝未识别的请求。另一些服务完全不依赖这个字段，而是使用专用地址或查询参数。
先确认服务要求，再修改请求头
- 查看订阅提供方的格式说明，确认该地址面向 Clash、Clash Meta（mihomo）还是其他客户端。
- 记录客户端名称、客户端版本和内核版本。客户端版本与内核版本是两组信息，更新界面不一定同步更新内核。
- 比较客户端日志与命令行响应。不要把浏览器里的登录页当作订阅正文。
- 只有提供方明确要求某个 User-Agent 时，才在客户端支持的订阅请求设置里填写该值；菜单名称因客户端而异。
例如，提供方明确要求使用 clash.meta 时，可在前面的 curl 请求中增加 -A 'clash.meta' 做一次对照。这个字符串只是特定服务可能接受的值，不是所有 mihomo 客户端的固定请求头，也不是通用修复口令。伪装请求头无法绕过真实的账户到期或权限限制。
不要把 User-Agent 随意加到配置顶层，期待它改变客户端的订阅请求。客户端下载整份配置和内核更新 proxy-providers 属于不同流程，只有对应组件支持的设置才会生效。如果换请求头后得到 YAML，但客户端仍失败，应进入格式与内核兼容性检查。
HTTP 200 仍解析失败：检查返回正文
200 OK 只说明 HTTP 请求成功，不说明内容适合 Clash。响应正文可能是登录页、验证码页面、JSON 错误对象、Base64 编码的节点列表，或者面向另一种内核的配置。先看响应头的 Content-Type，再在本机检查正文开头；响应头也可能标注不准确，最终仍要以内容为准。
| 正文特征 | 处理方向 |
|---|---|
以 <!DOCTYPE html> 或 <html 开头 | 检查登录页、拦截页或入口选错 |
| JSON 中包含错误码或错误消息 | 先处理接口错误，不能当作 YAML 配置导入 |
多行 ss://、vmess:// 等 URI | 确认客户端是否支持转换，或重新选择 Clash 输出 |
包含 proxies:、proxy-groups: 等结构 | 继续检查 YAML 与字段兼容性 |
只有 proxies: 和节点列表 | 可能是节点提供器文件，确认导入入口 |
完整配置与节点提供器不能混用
完整配置通常还定义代理组、规则及运行参数；proxy-providers 的远程文件主要提供节点集合。把完整配置填入仅接收节点集合的提供器地址，或把节点集合当作完整配置使用，都可能导致解析失败或缺少策略。rule-providers 又是规则集来源，不是节点订阅入口。
Clash Meta 后续更名为 mihomo，它与原版 Clash 的协议和配置能力并不完全相同。比如 Hysteria2、VLESS 等节点需要相应内核支持。日志出现不支持的类型或字段时，先确认实际运行的是哪个内核，再依据提供方要求选择输出格式。改掉 type 的名字并不能把一种协议转换成另一种协议。
YAML 缩进与配置引用错误
看到 yaml: line 12、did not find expected key 或 cannot unmarshal 时，先查看指定行及其前后几行。解析器指出的位置往往是发现问题的地方，真正原因可能在上一行：少了引号、列表缩进不齐，或把应为列表的字段写成字符串。
空格、列表和特殊字符
- 缩进使用空格，不用 Tab。同一级键保持对齐；两空格缩进是常用约定，不是唯一合法宽度。
rules应是列表，每条规则前有-。中文冒号不能替代 YAML 的英文冒号。- 含有冒号加空格、井号等特殊内容的名称建议加引号，并保持前后引用完全一致。
- 检查重复键和意外合并的段落，尤其是手动粘贴节点、覆写规则或合并订阅之后。
下面是一个可用于理解列表与缩进的直连配置，不包含远程订阅，也不是恢复节点的替代方案。它的规则引用了已经定义的代理组，适合与有错误的结构做局部对照。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-groups:
- name: "默认策略"
type: select
proxies:
- DIRECT
rules:
- MATCH,默认策略用当前内核检查，而不是只看 YAML 是否有效
通用 YAML 解析器只能检查语法，不能保证内核接受字段、协议和策略引用。使用本机实际运行的 mihomo 二进制，可先查看版本，再测试临时配置：
mihomo -v
mihomo -t -f ./subscription.yaml这里的 subscription.yaml 必须是保存到本机的配置文件；若客户端内置内核不在命令搜索路径中，应使用该二进制的实际路径。测试外部提供器配置时，还需考虑路径和网络依赖。出现 proxy not found 一类错误，检查代理组引用的节点是否存在、名称是否一致，以及节点提供器是否加载成功。
最终自查清单：按顺序恢复更新
- 保留现场：保存可用旧配置，记录报错原文、时间、客户端版本与内核版本。
- 确认账户：检查有效期、流量与令牌状态，从账户页面重新复制正确的订阅地址。
- 验证请求：查看 HTTP 状态、重定向和响应正文，分别对照直连与代理请求。
- 确认格式：区分 HTML、JSON、URI 列表、完整 YAML 和节点提供器文件。
- 核对请求头：按提供方说明检查 User-Agent，避免凭猜测不断更换。
- 检查配置：排查 YAML 缩进、字段类型、节点协议和代理组引用。
- 恢复自动更新：手动更新成功一次后，再开启合理的更新周期，避免多个相同订阅同时重试。
如果新建订阅项可以更新，而原订阅项持续失败，优先检查原项保存的地址、请求选项、覆写脚本与本地缓存。不要立即清空全部配置；先备份，再按客户端文档处理单个订阅项。若多个设备同时收到相同服务端错误，联系提供方时附上脱敏后的状态码、时间和正文错误信息，比只说“无法更新”更容易定位。
更新成功的确认标准应同时包含：订阅内容已获取、配置通过检查、代理组能正常加载。节点连通性是下一步测试；订阅获取成功但节点无法连接，应转向线路、节点参数和本机代理设置。相关概念可查阅术语表，后续连接问题可按故障排查页面继续诊断。