本文目录
导入订阅出现一长串错误时，不必马上编辑文件。请求可能没有取得配置，也可能拿到了内容却不能加载；两种情况的下一步完全不同。先保存完整报错和可用副本，再判断返回内容与当前内核是否匹配，修复时也更容易恢复原状态。
订阅失败在下载阶段，还是配置解析阶段？
保存错误原文、HTTP 状态和具体行号，用下表区分下载问题与配置解析问题。链接失效或返回登录页时查订阅来源；缩进错误或字段不受内核支持时，才检查已下载的内容。
两类失败的证据
| 表现 | 说明 | 先做什么 |
|---|---|---|
| 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。截图和日志遮住完整地址中的凭据，不能判断时遮住整个 URL；curl 命令不要贴进公开工单。链接已暴露时，先在服务面板重置，再继续排查。
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | head服务可能按请求的 User-Agent 返回不同内容；以客户端实际更新时的响应为准。curl 结果只作对照，不能单凭它判定订阅链接失效。
缩进错误与内核字段不兼容的处理
YAML 用缩进表达层级，Tab、漏掉的冒号、未闭合引号和错误的列表横线都可能让解析器在下一行才报错。看到 line 48 column 7，不只看第 48 行，还要向上检查它属于哪个键、上一项是否结束。
代理名含冒号、井号或特殊字符时应使用引号；同一层不要混用不同数量的空格。编辑副本并保留原文件，每次只修一个报错，重新测试后再看下一条。
# 正确：proxies 是列表
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
# 错误：proxies 被写成普通字符串
proxy-groups:
- name: PROXY
type: select
proxies: DIRECT通用 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 或服务方重新生成的干净订阅，让网络恢复。不要在日常使用的唯一配置上连续手改，也不要把解析失败的文件设为开机自动加载。
修复记录至少保留失败阶段、原始错误、客户端与内核版本、解决动作。下一次同一订阅更新后再次出现时，这些信息能判断是服务端生成变化、客户端升级还是本地覆写重新引入了错误。