先区分订阅下载失败与配置加载失败

“订阅导入失败”可能发生在不同环节：客户端没有取得响应、服务器返回了错误页面、配置文本无法解析，或者配置中的协议不被当前内核支持。只有最后一种情况才需要重点检查内核兼容性。反复切换节点，通常不能解决前三类问题。

FlClash 使用 mihomo 内核。客户端负责订阅管理、界面与配置处理，内核负责配置校验和流量转发。界面出现一条“更新失败”提示时，应同时查看此次更新的错误详情，以及随后是否出现内核加载错误。不同版本的菜单名称可能变化，以下以功能名称定位，不把某一版的界面路径当作所有平台的固定路径。

错误线索优先检查下一步
timeout、no such host链接可达性与域名解析测试下载请求，检查请求使用的网络出口
HTTP 401、403、404授权、访问限制或地址变化进入服务商账户页核对订阅状态和最新地址
yaml:、unmarshal返回内容和 YAML 数据类型先确认不是 HTML，再检查对应行及其上文
unsupported proxy type节点协议与内核能力核对实际运行的内核版本和节点字段
proxy … not found策略组和节点引用检查名称、过滤条件及覆写后的最终配置

排查前保留三份信息

  1. 记录 FlClash 版本、操作系统和实际内核版本。内核更新与客户端更新不一定同步，不能只写“最新版”。
  2. 保留失败时间附近的日志，例如触发更新前后各 30 秒，区分下载、解析、加载三个阶段。
  3. 备份仍可使用的配置。新建一个测试配置进行导入，不立即覆盖唯一可用的配置文件。

订阅 URL 通常含访问令牌。提交截图、日志或配置前，删除 URL 查询参数中的凭据，并清理节点密码、UUID、认证头和个人路径。仅遮住域名不能保护订阅权限。

第一层：检查链接可达性与 HTTP 状态

先核对地址，再检查网络

从服务商账户页重新复制面向 Clash 或 mihomo 的订阅地址。检查开头是否为 https://，结尾是否混入空格、换行、引号或中文标点。账户登录页、套餐详情页和二维码图片地址，都不是配置订阅地址。二维码应先解码为实际链接，而不是把图片文件导入客户端。

浏览器可以打开链接，只能证明浏览器当时的请求成功。浏览器可能携带登录 Cookie，也可能使用与客户端不同的代理出口。订阅后台任务通常不会继承浏览器登录状态。因此，应分别测试客户端更新和独立下载，不将两者视为同一条网络路径。

用一次受限下载检查响应

在 macOS 或 Linux 的 Bash 终端，可使用下面的命令。地址通过隐藏输入读取，避免直接写入命令历史。命令不会把订阅正文打印到终端，而是保存到当前目录；该目录应为个人可访问的临时工作目录。

read -r -s -p '输入订阅地址：' SUB_URL
printf '\n'
curl --location --max-redirs 3 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --output subscription-response.txt \
  --write-out 'HTTP %{http_code}\n类型 %{content_type}\n字节 %{size_download}\n' \
  "$SUB_URL"
unset SUB_URL

这里的连接超时为 10 秒，总时限为 30 秒，最多跟随 3 次跳转，并限制为 HTTPS。这些是本次诊断参数，不是 FlClash 的默认设置。Windows PowerShell 可调用 curl.exe 使用同名参数；不要直接照抄 Bash 的 read 与续行写法。

  • HTTP 200：说明收到正常状态响应，仍需检查正文；登录页和错误提示页也可能返回 200。
  • HTTP 301/302：检查跳转后的地址是否仍属于预期服务。不要把含令牌的完整跳转地址公开粘贴。
  • HTTP 401/403：检查令牌是否重置、套餐是否有效，以及账户是否存在访问限制。403 也可能来自防护服务。
  • HTTP 404/410：优先核对链接是否过期或接口是否迁移，不要靠修改随机路径尝试恢复。
  • HTTP 429：停止连续刷新，按服务端提示等待。自动化重试可能延长限流时间。
  • HTTP 5xx：记录时间和状态码，稍后重试并向服务商反馈；修改本地 YAML 无法修复服务端异常。

若结果显示 HTTP 000，表示没有取得可报告的 HTTP 状态，不是服务器真的返回了“000”。结合 curl 的错误信息检查 DNS、连接超时或 TLS 证书。证书错误应先核对设备时间、证书有效期及网络拦截情况，不应通过关闭证书验证长期绕过。

避免订阅更新形成依赖环

如果订阅域名必须通过代理访问，而当前没有可用配置，首次更新可能无法完成。反过来，代理出口被订阅服务拒绝时，直接连接可能更合适。应检查客户端是否提供订阅更新的代理设置或下载策略，每次只改变一种路径并记录结果。TUN 模式不是解析错误的修复开关，不要同时切换 TUN、DNS 和订阅地址。

第二层：确认返回的是配置，而不是网页或其他订阅格式

用本地文本编辑器打开 subscription-response.txt，只在自己的设备上查看。Content-Type 可作线索，但服务端可能统一使用 text/plain 或下载类型，不能仅凭响应头断定内容有效。

正文特征可能含义处理方式
<!DOCTYPE html>、<html>登录页、防护验证或错误网页重新取得直接订阅地址，联系服务商处理验证
{"error": 等 JSON 内容接口错误或非配置接口阅读错误字段，核对授权和账户状态
ss://、vmess:// 等逐行 URI节点链接集合确认客户端是否支持此导入格式，优先选择 Clash/mihomo 输出
连续的 Base64 文本可能是编码后的节点列表核对订阅格式，不把它直接当 YAML 加载
proxies:、proxy-groups:可能是 Clash 配置继续校验缩进、字段类型与引用关系

完整配置与节点提供者文件也不同。一个只含 proxies: 的文件可能用于 proxy-providers，它不一定包含客户端所需的策略组和规则；只含 payload: 的文件通常是规则集，不是节点订阅。具体导入行为取决于客户端是否会补充模板，不能将“能读成 YAML”等同于“能作为完整配置运行”。

部分服务会按请求的 User-Agent 返回不同格式。如果同一地址在浏览器和客户端中返回不同内容，应向服务商确认正确入口与目标格式，不要盲目伪造请求头。需要格式转换时，优先选择服务商提供的出口或自己可控的转换工具；把完整订阅交给公共转换站，意味着同时交出订阅中的凭据。

第三层：检查 YAML 语法、字段类型与名称引用

行号指向发现错误的位置，不一定是起点

yaml: line 12 表示解析器在第 12 行附近发现异常。真正的问题可能在上一行，例如引号没有闭合，或父级缩进被改变。先检查报错行前后各 5 行，不要直接删除整段节点列表。

  • 缩进使用空格，不使用 Tab。同一层级保持一致，例如每层 2 个空格。
  • 映射字段使用半角冒号，冒号后通常需要空格，例如 mode: rule。
  • 列表项使用半角 -，并确认它位于对应字段之下。
  • 含 : 、 # 或复杂符号的名称、密码和 URL，使用合适的引号包裹。引号内仍需遵守对应的转义规则。
  • 端口字段应为整数，proxies 应为列表；语法合法但类型错误，仍会在配置解码时失败。

用最小配置隔离语法问题

下面是用于隔离问题的最小直连配置，不含代理节点。混合端口指定为 17890，仅为本例取值；使用前确认没有其他进程占用。它不会提供代理节点出站能力。

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

proxies: []

proxy-groups:
  - name: "诊断出口"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,诊断出口

如果最小配置能够校验，而原订阅不能，排查重点就落在原文件和配置合并过程。若仍报端口占用或权限错误，说明已进入运行环境问题，不应继续按 YAML 语法错误处理。此配置的直连行为也不能证明代理节点可用。

本机已有 mihomo 可执行文件时，可在终端使用 mihomo -t -f ./subscription-response.txt 检查配置。该命令使用当前终端找到的内核，不一定是 FlClash 内置的版本。部分提供者配置的检查还可能涉及外部资源，因此测试应在本地受控环境进行，且通过检查不代表所有节点连通。

检查策略组、规则和覆写后的最终内容

若报错指向找不到代理名称，逐字比较节点名与策略组引用，包括空格和大小写。规则末尾的出站名称必须指向已存在的节点、策略组或内置出站。通过 use 引用的名称应对应 proxy-providers 中的键，不能拿提供者名称直接替代普通节点引用。

订阅原文通过校验而客户端加载失败时，应检查客户端的覆写、合并配置和节点过滤条件。过滤表达式可能删掉所有候选节点，重命名操作可能留下旧引用。先在测试配置中停用自定义处理，再逐项恢复；直接修改订阅缓存通常会在下次更新时被覆盖。

第四层：核对节点协议与实际运行的内核

Clash 配置格式并不意味着所有 Clash 系客户端具备相同协议能力。传统 Clash、mihomo，以及不同年代的内核版本，对协议和字段的支持范围可能不同。遇到 unsupported proxy type，先记录报错的 type 值，再核对内核版本与发布说明。

  1. 核对协议名。例如节点写成 type: hysteria2 时，需要支持该协议的内核；不能通过把类型改成 ss 让它工作。
  2. 核对必填项和数据类型。检查 server、port、密码或 UUID 等字段，具体要求随协议而定。
  3. 核对传输与 TLS 参数。连接地址、SNI、WebSocket 路径及相关选项必须与服务端一致。配置可解析，不代表握手参数正确。
  4. 核对字段是否被识别。某些未知字段可能被忽略而非直接报错。仅凭“导入成功”，不能证明所有选项已经生效。
  5. 使用兼容的订阅出口。服务商若提供面向 mihomo 的格式，应优先选择该格式；需要升级时，先备份配置，再更换客户端或内核。

导入成功后出现 dial timeout、认证失败或 TLS 握手失败，说明问题已经转到节点连接阶段。此时应检查节点可达性、凭据与服务端配置，而不是继续修订 YAML 缩进。解析成功、内核启动、节点连通和业务访问，是四个不同的验收结果。

修复后的验收顺序与反馈信息

每次只验证一个环节

  1. 手动更新一次订阅，确认返回内容非空，且不再出现 HTTP 或下载错误。
  2. 加载测试配置，确认日志没有 YAML、协议类型或名称引用错误。
  3. 确认内核持续运行，没有端口占用、权限不足或提供者资源加载失败。
  4. 选择一个已确认存在的节点测试连接，再通过实际应用验证规则选择的出站。
  5. 恢复需要的覆写和过滤设置，逐项观察，最后才恢复定时更新。

向服务商或项目反馈时，提供操作系统、客户端版本、内核版本、失败时间、HTTP 状态码和脱敏后的首条关键错误。若是 YAML 问题，附上报错行附近的最小片段；若是下载问题，说明直连与现有代理路径分别得到什么结果。不要提交整份带凭据的订阅文件。

如果订阅地址已在公开截图、工单或转换服务中泄露，应在服务商账户中重置订阅令牌，再更新各设备。清除本地记录不能撤销已经暴露的访问权限。

排查顺序保持为“链接可达 → 返回格式 → YAML 与引用 → 内核兼容”。这一顺序能避免在服务器返回登录页面时反复调整端口，也能避免把节点连接超时误判为订阅格式错误。常用字段的含义可继续查阅配置字段参考，首次启用系统代理和 TUN 的步骤见入门指南。