Clash 订阅导入解析失败:链接格式、YAML 缩进与请求头自查清单

先区分下载失败、解析失败与节点为空

Clash 订阅导入包含几个不同环节：客户端请求订阅地址，取得响应正文，将内容转换或解析为配置，再交给内核加载。界面上的“更新失败”可能把这些环节合在一起显示。先打开客户端的日志页，记录失败发生的时间和原始错误，再决定检查链接还是配置。

Windows 客户端的菜单名称并不统一。订阅入口可能叫“订阅”或“配置”，日志通常位于“日志”页面。找到报错的那条订阅执行一次更新，然后立即查看相同时间附近的日志，避免把节点测速失败误当成导入失败。

第一步：核对订阅链接与 HTTP 响应

复制订阅地址，不是账户页面地址

1. 回到服务提供方的订阅页面，选择明确标注为 Clash 或 Clash Meta／mihomo 的订阅入口。
2. 重新复制完整链接，确认开头为 https:// 或服务明确提供的 http://，末尾没有换行、中文标点或多余空格。
3. 检查查询参数是否完整。含有 & 的地址被截断后，可能只留下第一个参数；从网页源代码复制时，还要留意是否误带了字面文本 &。
4. 如果最近重置过订阅令牌，应在客户端替换地址。旧链接不会因为再次点击更新而恢复。

地址没有 .yaml 后缀不代表格式错误。反过来，地址以 .yaml 结尾，也可能返回登录页或错误提示。真正需要检查的是服务器返回的状态和正文。

在 Windows 上保存一次实际返回内容

下面的命令在 Windows PowerShell 中运行，使用系统中的 curl.exe，避免与部分 PowerShell 版本的命令别名混淆。先进入一个仅自己使用的临时目录，再执行。链接通过输入提示读取，不必把含令牌的地址直接写进命令历史。

$url = Read-Host '粘贴订阅地址'
curl.exe --location --max-time 30 --dump-header response-headers.txt --output subscription-response.txt -- "$url"
Get-Content .\response-headers.txt
Get-Content .\subscription-response.txt -TotalCount 12
Remove-Variable url

--location 允许跟随重定向，--max-time 30 将总请求时间限制为 30 秒。出现多组响应头时，应看最后一组状态。命令成功保存文件，只说明拿到了响应，不说明它一定是有效订阅。响应头也可能包含敏感的跳转地址，排查结束后应清理这些文件。

• 200：继续看正文；登录页和业务错误也可能返回 200。
• 301、302：确认最终跳转到了订阅内容，而非登录或验证页面。
• 401、403：检查令牌和访问策略，也可能是服务端防护拒绝了请求。
• 404、410：核对订阅入口是否变更，向提供方确认链接状态。
• 429：停止连续更新，按服务端提示等待，避免进一步触发限流。

浏览器能打开，并不等于客户端能下载。浏览器可能携带登录 Cookie，使用不同的代理路径，或者已经完成网页验证。不要把浏览器里显示“正常”的账户页面作为订阅有效的依据。

第二步：辨认返回的是 YAML、节点列表还是网页

查看响应文件的前几行，通常能缩小范围。Content-Type 可作参考，但有些服务会把 YAML 标为普通文本，因此不能只凭响应头下结论。

“节点提供者文件”和“完整配置”也不是一回事。前者常常只有 proxies 列表，需要由主配置中的 proxy-providers 引用。它不一定包含策略组与规则，不能期待把它作为完整配置导入后就自动生成所有分流选项。

如果必须转换格式，优先使用客户端内置且说明清楚的转换功能，或提供方自己的格式入口。不要把带令牌的订阅链接提交给不明在线转换站；转换服务能够读取链接及其返回的节点凭据。

第三步：检查 YAML 缩进、引号与字段类型

先看报错行，再看它的上一层

错误提示里的行号通常是解析器发现问题的位置，不一定是错误最早发生的位置。例如上一行缺少引号或缩进层级错误，可能到下一行才报错。用本地文本编辑器打开文件，开启行号和空白字符显示，查看报错行及前后各 5 行。

• 层级缩进使用空格，不要使用 Tab。统一每层 2 个空格更便于阅读，但关键是同一层对齐。
• 字段名后的冒号使用半角 :，映射值前通常需要空格，例如 mode: rule。
• 列表项使用半角连字符加空格，例如 - DIRECT；全角破折号不能替代它。
• 字符串包含冒号加空格、特殊符号或容易混淆的内容时，使用成对引号。例如 name: "香港: 01"。
• 同一个映射层级不要重复写 dns、rules 等键；不同解析器对重复键的处理可能不同。

下面是用于理解层级关系的直连测试配置。它没有远程节点，不能用来验证订阅恢复或代理连通性。只有在本地测试副本中使用，不要拿它覆盖正常订阅。

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

proxy-groups:
  - name: "本地测试"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,本地测试

proxy-groups 是列表，其中每个策略组是一个映射；组内的 proxies 又是一个列表。rules 与 proxy-groups 同属顶层，不能缩进到某个策略组里。这里的 7890 只是示例监听端口，实际端口应以客户端显示为准。

语法能解析，不代表字段类型正确

把列表误写成字符串，仍可能是合法 YAML，却不符合内核要求。例如 proxies: "DIRECT" 与上述列表写法不是同一种数据类型。看到 cannot unmarshal 时，应同时检查字段期望的是字符串、数字、布尔值、列表还是映射，而不是只调整空格。

若原始订阅可以加载，加入覆写后才报错，应先停用该订阅关联的覆写、合并或脚本处理，再逐项恢复。客户端保存的原始订阅与最终交给内核的配置可能不同，检查对象应包含最终生效配置。更多字段说明可查阅规则语法手册和DNS 配置参考。

第四步：对照 User-Agent 与 mihomo 内核支持

同一链接可能返回不同格式

部分订阅接口根据请求头中的 User-Agent 判断客户端类型。浏览器、命令行工具与客户端可能拿到不同内容，因此前面的命令行结果只是一次取样，不一定与客户端实际响应完全一致。

如果客户端提供“订阅请求头”或“User-Agent”设置，先记录原值，再核对提供方文档。下面的命令把请求头设为 mihomo，仅用于对比响应；它不是所有订阅服务通用的修复值，也不会把旧客户端变成 mihomo 内核。

$url = Read-Host '粘贴订阅地址'
curl.exe --location --max-time 30 --user-agent "mihomo" --output response-mihomo.txt -- "$url"
Get-Content .\response-mihomo.txt -TotalCount 12
Remove-Variable url

如果默认请求返回节点链接列表，指定请求头后返回 YAML，说明服务端存在格式分发逻辑。应采用提供方明确支持的入口或请求头，不要连续尝试大量身份字符串。若两次都返回验证网页，修改 YAML 或更换请求头通常不能解决服务端访问限制。

界面版本与内核版本分别记录

Clash、Clash Premium 与 Clash Meta（现称 mihomo）的能力范围不同。配置中出现 type: hysteria2、type: vless 等节点类型时，需要确认当前内核支持相应协议及具体参数。仅更新客户端界面，不一定意味着正在运行的内核已经切换。

1. 在客户端“关于”或版本信息页记录客户端版本。
2. 在内核信息或启动日志里记录内核名称与完整版本号。
3. 对照该版本的配置文档检查报错字段，尤其是协议类型与传输参数。
4. 选择匹配内核的订阅格式，或通过客户端正式提供的更新入口更新内核。

不要通过删除 type、改写协议名来绕过错误。协议类型决定连接方式，随意修改即使通过结构检查，也通常无法建立连接。

第五步：导入成功但节点为空，检查引用链

节点列表为空时，先看订阅原文里有没有实际节点，再看客户端最终配置是否仍保留这些节点。还要区分“节点没有下载下来”和“节点存在，但当前策略组没有引用”。

• 直接节点：检查 proxies 是否为空列表。若响应本身就是 proxies: []，应先核对账户可用状态和订阅过滤条件。
• 远程节点提供者：检查 proxy-providers 的下载日志。主配置下载成功，不代表每个提供者也更新成功。
• 策略组引用：通过 use 引用提供者时，名称必须与 proxy-providers 中的键一致。通过 proxies 引用节点时，节点名称也必须对应。
• 筛选条件：暂时停用自己添加的名称过滤规则。正则表达式、大小写或地区命名变化，都可能让结果变成零个节点。
• 合并顺序：检查覆写是否用一个空列表替换了原订阅的节点或策略组。不同客户端的合并机制不同，不能假定列表总会自动追加。

例如策略组写了 use: [机场节点]，提供者却命名为 订阅节点，两者不会自动匹配。修正引用关系后，再更新对应提供者并观察日志。不要只对主订阅连续点击更新。

复测顺序与问题反馈清单

一次只改变一个条件，才能知道哪项调整有效。先确认订阅响应正确，再确认 YAML 与内核兼容，最后恢复覆写和网络接管功能。按下面顺序复测，通常比同时修改 DNS、端口和 TUN 更容易定位问题。

1. 在测试订阅中导入原始链接，停用个人覆写，执行一次更新。
2. 确认日志没有下载或解析错误，检查节点数量与策略组内容。
3. 选择一个真实节点，再进行延迟测试；测试失败属于后续连接排查，不等于订阅解析失败。
4. 按需恢复系统代理，验证浏览器访问；需要 TUN 时，再单独启用并验证目标应用。
5. 逐个恢复自定义规则、覆写和过滤设置，每次保存后观察内核是否成功加载。

向服务提供方或客户端项目反馈时，附上 Windows 版本、客户端版本、内核名称与版本、失败时间、HTTP 状态、完整错误类型，以及“原始订阅是否能单独加载”。涉及 YAML 的问题，可提供保留层级关系的脱敏片段和原始行号。

不要公开订阅令牌、服务器密码、UUID、完整节点地址或完整响应文件。如果链接已经泄露，应先在提供方处重置令牌，再替换客户端订阅地址。导入成功后的检查步骤，可继续参考订阅导入教程与连接验证说明。