本文目录
Clash 订阅导入失败，先分清链接失效还是格式读不懂
客户端常把“更新失败”显示成一条通知，但链接失效、Invalid YAML 和 unsupported field 需要完全不同的处理。保留错误原文、HTTP 状态和行号，先判断失败阶段，才不会拿 YAML 编辑器修一份实际是登录页面的文件。
两类失败的证据
| 表现 | 说明 | 先做什么 |
|---|---|---|
| HTTP 401、403、404、超时 | 远程请求还没得到可用配置 | 检查 token、地址、网络和服务端状态 |
| 返回 HTML、登录页或套餐提示 | URL 能访问，但内容不是 YAML | 确认复制的是订阅接口而非网页地址 |
| mapping values are not allowed | YAML 结构或缩进错误 | 按报错行和上一层缩进定位 |
| unknown field、cannot unmarshal | 语法可能成立，但字段或数据类型不被当前内核接受 | 核对内核版本和官方字段 |
查看返回头和开头内容，不公开完整订阅地址
在自己控制的终端或浏览器开发工具中查看订阅响应。状态应成功，正文开头应像 YAML 配置或 provider 数据，而不是 <!DOCTYPE html>、登录表单、JSON 错误或“流量已用完”的提示。
订阅 URL 常含可直接拉取配置的 token。截图时遮掉查询参数，curl 命令不要粘进公开工单；如果链接已经暴露，先到服务面板重置，再继续排查旧响应。
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | headYAML 报错行常常只是上一层结构已经坏了
YAML 用缩进表达层级，Tab、漏掉的冒号、未闭合引号和错误的列表横线都可能让解析器在下一行才报错。看到 line 48 column 7，不只看第 48 行，还要向上检查它属于哪个键、上一项是否结束。
代理名含冒号、井号或特殊字符时应使用引号；同一层不要混用不同数量的空格。编辑副本并保留原文件，每次只修一个报错，重新测试后再看下一条。
# 正确：proxies 是列表
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
# 错误：proxies 被写成普通字符串
proxy-groups:
- name: PROXY
type: select
proxies: DIRECTYAML 能解析，不代表 Mihomo 接受这些字段
通用 YAML 检查器只验证文本结构，不知道 Mihomo 的字段、类型和引用关系。unknown field、proxy not found、group not found 或不支持的协议，说明要回到当前内核文档与版本，而不是继续调整缩进。
客户端自带的内核版本可能落后于订阅生成器，也可能因合并覆写把字段移到错误位置。先在“关于”或启动日志中确认实际内核，再对照当前 Mihomo 文档；升级前保留可用配置，避免把协议兼容问题变成新的迁移问题。
完整配置、节点 Provider 和规则集不能互相顶替
完整配置通常包含端口、代理组和 rules；proxy-provider 文件主要提供节点；rule-provider 文件则按 domain、ipcidr 或 classical 等行为提供规则内容。
如果把 provider URL 当成完整订阅导入，即使文件本身是合法 YAML，客户端仍会提示缺少完整配置所需的字段。
反过来，把完整配置填进 proxy-providers，也可能在解析列表时失败。先看返回顶层键和服务方提供的导入方式，再决定它应放在 Profile、proxy-providers 还是 rule-providers。
- 完整 Profile
- 通常能独立加载，含 proxy-groups 与 rules 等运行配置。
- Proxy Provider
- 供主配置的 proxy-providers 引用，内容重点是节点列表。
- Rule Provider
- 供 RULE-SET 使用，behavior 与 payload 结构必须对应。
在副本里测试，还要看客户端合并后的最终文件
先保存原始响应副本，把 token 与节点凭据遮蔽后再编辑。Mihomo 命令行可用配置测试功能检查指定目录，图形客户端也通常在加载前运行校验；以当前实际内核输出的第一条错误为准。
若原文件能通过、客户端仍失败，查看 Merge、Mixin、覆写脚本或全局设置生成的最终配置。常见问题不是订阅本身坏了，而是覆写引用了已经删除的策略组，或把同一个顶层键生成了两份不兼容内容。
原始订阅可读，最终配置报 group not found
常见原因：覆写或旧规则引用已不存在的策略组
处理方法：在最终配置搜索组名，暂时停用相关覆写。
订阅是 HTML
常见原因：复制了网站页面、登录已过期或 token 失效
处理方法：重新取得专用订阅地址，不编辑 HTML。
Provider 单独更新失败
常见原因：URL、path、behavior 或写入权限问题
处理方法：按 provider 类型检查，不重做整个 Profile。
先恢复一份能加载的配置，再整理错误原因
正在使用的配置损坏时，先切回上一份可用 Profile 或服务方重新生成的干净订阅，让网络恢复。不要在唯一的生产配置上连续手改，也不要把解析失败文件设为开机自动加载。
修复记录至少保留失败阶段、原始错误、客户端与内核版本、解决动作。下一次同一订阅更新后再次出现时，这些信息能判断是服务端生成变化、客户端升级还是本地覆写重新引入了错误。