先区分下载失败与解析失败

订阅导入通常经过四步：请求链接、接收响应、解析配置、加载配置。界面上的“更新失败”可能覆盖其中任何一步。只有定位到失败阶段，才能判断应该更新链接、修改请求方式，还是检查配置结构。

先保留当前可用配置，再手动更新一次失败的订阅。打开客户端的“日志”页面，记录这次操作对应的时间、HTTP 状态码和首条错误。不同客户端的菜单名称并不统一，重点是找到订阅更新日志，而不是连接测速结果。

日志线索 所在阶段 优先检查
no such host 域名解析 订阅域名是否正确，当前 DNS 是否可用
timeout 或 connection refused 建立连接或读取响应 网络路径、代理端口、服务器可达性
HTTP 401、403、404、410 服务器响应 授权、访问限制、链接是否已被替换
yaml: 与行号 解析响应内容 响应是否为配置，以及缩进和数据类型
proxy not found 配置引用校验 策略组、节点和规则目标的名称是否对应

链接过期与账户状态

重新复制完整订阅地址

从服务提供方的账户页面重新复制适用于 Mihomo 的订阅地址。不要把账户登录页、购买页或浏览器地址栏里的控制台地址当成订阅。复制后检查是否混入空格、换行或中文标点，并确认 ? 后面的参数没有被聊天软件截断。

  • 401：通常表示缺少有效认证，先核对链接令牌和账户状态。
  • 403：可能是授权拒绝，也可能是请求头、地区、IP 或风控限制，不能仅凭状态码断定订阅到期。
  • 404 或 410：可能是入口迁移、链接被撤销或资源被移除，需要回到账户页面核对。
  • 429：表示请求过于频繁，应按响应中的 Retry-After 等待，不要连续点击更新。
  • 5xx：优先检查服务端状态，稍后重试，避免先大幅修改本地配置。

流量耗尽、套餐到期与令牌失效是不同情况。部分服务会返回空列表或说明文字，而不是明确的 401。需要同时查看响应正文与账户状态，不能只看“请求成功”。

浏览器验证的边界

在可信设备上直接打开订阅链接，可以初步识别登录页、错误页或文件下载。但浏览器可能携带登录 Cookie，也可能发送与客户端不同的 User-Agent。浏览器能下载，不代表客户端一定能获取相同内容；浏览器显示乱码，也不等于配置损坏。

如果链接返回登录表单或验证码页面，先确认复制的是专用订阅入口。不要把网页保存为 .yaml 再导入。浏览器测试会留下历史记录，在共享设备上尤其需要谨慎。

检查 HTTP 响应与实际正文

只看文件扩展名无法判断内容。名为 config.yaml 的响应可能是一段 HTML；HTTP 200 也可能对应“订阅已失效”的提示。应同时检查状态码、重定向和正文开头。

用 curl 留下可比对的结果

下面命令适用于安装了 curl 的 macOS 或 Linux Bash 终端。输入链接时不回显，也不会把链接直接写入命令历史；但请求执行期间，展开后的地址仍可能被本机具有相应权限的进程看到。输出文件同样可能包含凭据，应仅在本地保存。

read -r -s -p '订阅地址：' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --connect-timeout 10 --max-time 30 \
  --dump-header subscription-headers.txt \
  --output subscription-response.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

这里将连接超时设为 10 秒、整个请求上限设为 30 秒，最多跟随 5 次重定向。这些是排查参数，不是服务性能的实测结论。不要附加 -k 跳过证书验证，也不要使用 --location-trusted 将认证信息扩散到重定向目标。

  1. 查看终端中的 curl 错误和最终 HTTP 状态。连接尚未收到 HTTP 响应时，可能显示 000，它不是服务器状态码。
  2. 查看 subscription-headers.txt。跟随重定向时，文件中可能有多段响应头，应定位最后一段。
  3. 在本地文本编辑器里打开 subscription-response.txt，确认开头是配置字段、编码后的节点列表，还是 HTML 和错误说明。
  4. 检查重定向目标是否为提供方认可的域名。不要公开响应头，其中可能包含 Cookie 或带令牌的地址。

Content-Type 是线索，不是最终判据。部分服务把 YAML 标成 text/plain，仍能正常使用；相反，响应头标注 YAML，也不能保证正文语法和结构正确。

区分完整配置、节点集合与编码订阅

“返回内容是 YAML”只完成了一半检查。Mihomo 完整配置、proxy-providers 使用的节点集合，以及 URI 或 Base64 节点订阅，属于不同输入。客户端是否负责转换这些内容，取决于具体实现，不能认为所有客户端都支持自动转换。

内容特征 通常用途 常见误用
包含代理来源、策略组与规则 作为完整配置加载 引用不存在的节点或策略组
以 proxies: 为主体的节点集合 供 proxy-providers 引用 误认为包含全部策略和分流规则
多行 ss://、vmess:// 等链接，或其编码文本 交给支持该格式的导入器转换 直接当作内核 YAML 配置加载
<!DOCTYPE html> 或 <html> 网页或访问拦截响应 修改后缀为 YAML 试图修复

YAML 行号与字段类型

日志指向第 18 行，不一定表示第 18 行本身有问题；上一行缺少冒号、引号未闭合，也会让解析器在下一行报错。检查报错行前后至少 3 行，并使用空格缩进，避免混入 Tab。

# 结构示意，不是可直接联网的完整配置
proxies: []
proxy-groups:
  - name: 手动选择
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,手动选择

这个示例用于核对列表和缩进结构，不含代理节点。真实配置还要保证规则目标、策略组名称、节点名称逐字对应。中文标点、尾随空格和大小写差异，都可能导致引用找不到。

区分语法通过与内核支持

YAML 语法正确，不代表当前内核支持其中的协议、传输方式或字段。先在客户端“关于”或内核信息页记录实际内核版本，再对照该版本支持范围。客户端版本与内核版本不是同一个概念。

需要进一步定位时，可以在受限目录中保存完整配置，使用本机 Mihomo 的 mihomo -t -f config.yaml 进行配置测试。该操作不等同于联网可用性测试；涉及外部资源时，还要检查资源加载日志。不要对未经审查的配置直接启用服务。

User-Agent 与订阅返回格式

部分订阅服务通过 User-Agent 判断返回哪种配置。同一个地址在浏览器中返回说明页面，在客户端中返回 YAML，或反过来，可能与这个机制有关。应优先选择提供方明确标注的 Mihomo 订阅入口，而不是先随机修改请求头。

  1. 保持同一地址、同一网络和相近测试时间，只改变 User-Agent，避免多个变量同时变化。
  2. 先记录客户端日志中能确认的请求信息，再查提供方文档要求的 User-Agent 值。
  3. 用 curl 的 --user-agent 做对照，将两次结果分别保存，比较状态码和正文结构。
  4. 确认结果后，再检查客户端是否允许为订阅请求单独设置该请求头。不要只修改浏览器设置。

例如，在提供方明确支持该标识时，可以测试 --user-agent 'clash.meta'。这不是所有订阅服务通用的修复值，也不保证返回当前内核兼容的配置。若响应依然是登录页或 403，应继续检查授权与网络限制，而不是不断更换标识。

网络、DNS 与代理更新路径

浏览器能访问，客户端却超时

先核对请求是否走同一条路径。浏览器可能使用系统代理，订阅更新组件可能使用直连、内置代理或单独配置的下载路径。开启系统代理，也不代表每个进程都会自动使用它。

如果客户端提供“通过代理更新订阅”之类的选项，应先确认现有代理可用。订阅已失效且节点也无法连接时，强制通过旧节点更新可能形成依赖循环。保留一份可用配置，再按服务提供方支持的方式尝试另一条网络路径。

  • DNS：no such host 先查域名拼写与系统解析；不要直接把不固定的服务 IP 写死。
  • 代理端口：若本地 HTTP 代理配置为 127.0.0.1:7890，需确认客户端实际监听该端口。7890 只是示例，不是所有客户端的默认值。
  • TUN：TUN 可能改变进程的流量路径，但不能修复错误的 YAML。切换前记录当前开关，测试后恢复，避免把两类故障混在一起。
  • TLS：证书报错时检查系统日期、时区、订阅域名与网络认证页面，不要直接关闭证书验证。

用独立网络做一次对照

在条件允许时，用手机热点与原网络各请求一次。保持链接和 User-Agent 不变。如果仅一个网络返回 HTML 拦截页或连接超时，排查重点转向网络路径；如果两边都稳定返回同样的格式错误，则应回到订阅内容与客户端兼容性。

curl 的 --noproxy '*' 可以排除 curl 层的显式代理使用，但不能绕过系统 TUN、路由规则或网络出口设备。因此，“使用该参数后仍失败”不能直接证明直连路径存在问题。

恢复导入与最小反馈信息

修改后先执行一次手动更新，确认配置已经通过解析，再切换到新配置测试连接。订阅更新成功只表示内容被接收和处理，不代表全部节点可用，也不代表 DNS、系统代理和规则分流已经配置完成。

  1. 核对订阅更新时间、节点数量，以及是否存在预期策略组。
  2. 查看加载日志，确认没有节点类型不支持、提供器下载失败或规则目标缺失等错误。
  3. 访问一个已知可达的测试目标，观察连接日志中的匹配规则、策略组和出口。
  4. 保持旧配置可恢复，确认新配置稳定后再清理临时响应文件。

仍然失败时提交哪些信息

向客户端维护者或订阅提供方反馈时，附上操作系统、客户端版本、内核版本、失败时间、HTTP 状态码、脱敏后的首条错误，以及直连与代理更新的对照结果。格式问题可提供保留缩进的最小片段，不要提交完整订阅链接和节点凭据。

排查顺序可以收束为：先确认链接与授权，再看响应正文，然后核对格式和内核支持，最后比较请求头与网络路径。每次只调整一个变量，能够减少“偶尔成功”带来的误判，也便于在后续订阅更新时复现和修复同类问题。