1. 先区分下载失败、解析失败与启用失败

订阅更新至少经过三个环节：客户端请求订阅地址、读取并解析返回内容、把配置交给内核加载。“更新失败”可能发生在任何一层；节点无法连接则可能是配置已经成功加载之后的另一个问题。先找出失败阶段，再决定改网络、改文件还是检查内核，避免同时修改 DNS、端口和规则。

  1. 保留当前可用配置：在「配置」页确认当前选中的配置，先备份本地配置与覆写文件。不要为了测试删除唯一可用的订阅。
  2. 只手动更新一次：记录点击更新的时间，然后打开「日志」，查找同一时刻附近的第一条错误。最后出现的“更新失败”通常只是结果。
  3. 记录运行环境：从「设置」→「关于」或客户端的版本信息页记录客户端名称、版本和内核版本。界面菜单随客户端变化，图形客户端版本不等于 mihomo 内核版本。
  4. 确定失败范围：一条订阅失败、全部订阅失败，或者只有某个 proxy-providers 更新失败，排查方向并不相同。
日志线索优先检查暂时不要做
no such host订阅域名解析、网络 DNS修改 YAML 缩进
timeout、connection refused请求路径、代理入口、服务器可达性反复删除并导入
HTTP 401、403、429授权状态、访问限制、更新频率连续点击更新
yaml、unmarshal响应正文、字段类型、行号直接判断节点失效
unsupported、not found协议支持、策略名称、引用关系仅凭文件能打开就判定有效

2. 检查订阅链接与 HTTP 返回内容

从服务后台重新复制专用订阅地址

登录服务后台，在订阅区域选择 Clash 或 Mihomo 格式，重新复制完整链接。不要复制浏览器地址栏中的账户页面，也不要把二维码图片地址当作订阅地址。链接中 ? 后面的查询参数常包含授权信息，漏掉一段就可能返回登录页或权限错误。

如果后台刚执行过“重置订阅链接”或“重置令牌”，旧地址可能立即失效。应更新原配置的订阅地址，而不是继续请求旧地址。账户到期也可能返回说明页，具体以服务后台显示和 HTTP 响应为准，不能把每个 403 都解释成到期。

  • 401：通常与身份验证有关，核对令牌与服务端要求。
  • 403：可能是权限、访问来源限制或防护策略拒绝，结合响应正文判断。
  • 404：核对路径与链接是否已更换；部分服务也会用此状态隐藏无效地址。
  • 429：表示请求过密，停止重复更新，按服务端提示或 Retry-After 等待。
  • 5xx：优先考虑服务端或中间网关异常，保留现有配置并稍后重试。

HTTP 200 不代表返回了可用配置

成功状态码只说明服务器返回了响应。正文如果以 <!DOCTYPE html> 或 <html> 开头，通常是网页、登录页或验证页；如果只有 ss://、vmess:// 等分享链接，或一整段 Base64 文本，则未必是客户端当前导入方式所需的完整 YAML 配置。

浏览器能下载、客户端却失败时，还要考虑请求方式差异：浏览器可能带有登录 Cookie、使用另一条代理路径，服务端也可能根据客户端的 User-Agent 返回不同格式。优先使用服务后台提供的对应客户端入口，不要先随意伪装请求头。

3. 排查 DNS、代理路径与 TLS 错误

订阅请求可能由图形客户端发出，也可能由内核发出。配置文件中的 DNS 设置不一定控制图形客户端自己的更新请求；打开系统代理也不保证更新器一定使用该代理。应在订阅配置的菜单中查找更新方式，若提供“直接更新”与“通过代理更新”，分别进行一次对照测试。

先验证可用出口，避免更新依赖失效配置

如果更新必须经过代理，而当前配置已经不可用，就会形成循环依赖。先切回保留的可用配置，再尝试代理更新；或者在允许直连订阅域名的网络上测试直接更新。TUN 模式会改变流量接管路径，排查时可在记下原状态后暂时关闭 TUN，用已确认的系统代理或显式代理做单变量测试。

以下 PowerShell 命令通过交互输入地址，分别测试直连与本地 HTTP 代理。示例代理入口为 127.0.0.1:7890；只有客户端设置显示的 HTTP 或混合端口确实为 7890 时才直接使用。仅提供 SOCKS 的端口不能照搬为 HTTP 代理。

$subscription = Read-Host "粘贴订阅地址，仅在本机检查"
curl.exe --noproxy "*" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
curl.exe --proxy http://127.0.0.1:7890 --noproxy "" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
Remove-Variable subscription

这里的 10 秒为连接超时、30 秒为整次请求时间上限，并非测速结果。命令只显示最终 HTTP 状态，不打印响应正文；000 不是服务器状态码，应结合 curl 的错误信息判断。交互输入避免把真实链接直接写进命令历史，但本机进程检查仍可能看到运行时参数，不宜在共享设备上执行。

  • 直连失败、代理成功：检查订阅更新是否使用了预期代理路径。
  • 直连成功、代理失败：核对本地监听端口、当前出口和更新代理设置。
  • 两种方式都解析域名失败：先查系统 DNS 与订阅域名是否仍有效，不能只在配置里随意增加 DNS 服务器。
  • 出现 x509 或证书有效期错误：检查系统日期、时区、证书链与 HTTPS 检查软件；企业网络可交由管理员确认信任链。

4. 按行号修复 YAML 语法与字段类型

当日志进入 yaml: line 12 这类解析阶段时，说明已经拿到了某些内容，但还不能确认它就是配置。先确认不是 HTML 错误页，再用本地文本编辑器查看报错行及其前后各 3 至 5 行。解析器指出的行号可能是“无法继续读取”的位置，真正缺失的冒号或引号可能在上一行。

优先检查四类常见格式错误

  1. 缩进混用：YAML 缩进使用空格，不使用 Tab；同一层级保持一致。列表项的 - 与子字段必须对齐。
  2. 中文标点：把字段名后的全角冒号改为半角 :，并检查逗号、引号是否被输入法替换。
  3. 值类型不符：allow-lan 应为布尔值，mixed-port 应为端口数值；不要把对象、列表和字符串互相替代。
  4. 特殊字符未正确引用：包含“冒号后接空格”或“空格后接井号”的字符串需要特别注意；地址与名称可用匹配的引号包围。

下面是用于说明结构的最小配置，仅提供本地混合代理入口，并将流量交给 DIRECT。它没有远程代理节点，不可拿来替代订阅后期待访问路径保持不变；若启用后测试，流量将直连。

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

proxies: []

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

rules:
  - "MATCH,手动选择"

如果本地文件可以加载，而订阅文件不能加载，继续定位订阅内容、合并脚本或覆写设置。远程订阅的手工修改通常会在下次更新时被覆盖；先在副本上验证修复，再决定通过客户端的持久化覆写功能调整，或请订阅提供方修正源文件。

5. 核对内核兼容性与配置引用

合法 YAML 只代表语法可读，并不代表内核能运行。Clash、Clash Meta（现称 mihomo）及不同版本支持的协议和字段存在差异。旧内核遇到不支持的代理类型可能报 unsupported proxy type；部分未知字段也可能被忽略，因此“没有解析错误”不等于相关功能已经生效。

根据具体报错检查引用链

  • 代理类型不支持：核对订阅导出目标与实际运行内核，使用与内核兼容的配置，或通过客户端支持的方式更新内核。
  • 策略或代理不存在：检查 proxy-groups 中引用的节点、组名，以及规则末尾的策略名。名称必须一致，注意大小写与尾部空格。
  • 规则集不存在：规则中的 RULE-SET 名称应在 rule-providers 中有对应定义，不能只复制引用而遗漏定义。
  • 启动时报端口占用：address already in use 属于加载或监听问题。检查是否同时运行两个客户端，不要继续修改订阅令牌。

还要区分完整配置与提供者文件：完整配置可以包含 proxies、proxy-groups、rules 等部分；代理提供者文件通常提供 proxies 列表，由主配置的 proxy-providers 引用。规则提供者则根据声明的格式提供规则内容，YAML 格式常使用 payload。它们的用途不同，不能只因为扩展名都是 .yaml 就放到同一个导入入口。

如果错误只指向某个提供者，先检查该项的 URL、格式和更新日志。主订阅更新成功，不代表所有提供者也成功刷新。客户端的覆写、合并与脚本还可能改动最终配置；在副本上暂时停用相关处理，对照原始配置与最终运行配置，有助于定位是哪一步引入错误。

6. 更新成功后，检查是否真正切换到新配置

“下载完成”与“当前已启用”是两回事。返回「配置」页检查当前选中的卡片、更新时间和节点数量，再到「代理」页确认策略组内容是否变化。如果下载成功但内核校验失败，客户端可能继续运行旧配置，应以加载日志为准，不能只看更新提示。

  1. 确认更新的是正在使用的订阅，而不是列表中同名的另一张卡片。
  2. 查看更新后的加载日志，确认没有回退、端口占用或引用缺失。
  3. 在「代理」页选择有效策略组，按需测试单个节点，避免把所有节点测速当作订阅下载测试。
  4. 若浏览器仍不通，再检查系统代理、TUN 和规则命中；这已属于流量接管或出站排查，不再是订阅解析问题。

不要通过不停重启或把自动更新间隔改得很短来验证结果。短时间重复请求可能触发 429，掩盖原来的故障。确认一次完整的“请求成功 → 校验成功 → 加载成功”，比多次点击更新更有判断价值。

7. 提交问题前的最小信息清单

本地排查仍无法解决时，把问题交给订阅提供方或客户端维护者。只提供“导入失败”通常不足以复现；下面这些信息可以帮助对方区分服务端响应、客户端请求与内核校验问题。

  • 环境：操作系统、客户端完整版本、实际内核名称及版本。
  • 时间与动作：失败发生的日期和时区，是首次导入、手动更新还是自动更新。
  • 错误：第一条相关日志、HTTP 状态码、解析行号及已脱敏的上下文。
  • 对照：直接更新与代理更新的结果，其他订阅是否正常。
  • 配置处理：是否启用了覆写、合并脚本、代理提供者或规则提供者。