Clash 配置报错速查：常见 YAML 错误与内核报错对照

改完配置点保存，客户端弹一句英文报错就没了下文。这篇把常见报错整理成对照表。

先做一次配置检查

改配置之后、导入之前，用内核自己验一遍：

mihomo -t -d /path/to/config/dir

-t 是 test 模式，只检查不运行。它给出的错误信息比客户端弹窗详细得多，通常直接告诉你第几行有问题。

Clash Verge 用户可以在配置目录下对 config.yaml 执行这条命令。配置目录位置：

一、YAML 语法错误

这类错误在配置解析阶段就失败了，通常报错里带行号。

found character that cannot start any token

原因：用了 Tab 缩进。YAML 只接受空格。

定位：编辑器里打开「显示空白字符」，Tab 会显示成箭头。

修复：全部替换成空格。VS Code 里 Ctrl+Shift+P → 「Convert Indentation to Spaces」。

mapping values are not allowed in this context

原因：冒号后面缺空格，或者值里有未加引号的冒号。

# 错误
port:7890
name: HK: 01

# 正确
port: 7890
name: "HK: 01"

did not find expected key / could not find expected ':'

原因：缩进层级不一致。

# 错误：两个键缩进不同
proxies:
  - name: "A"
    type: trojan
     server: a.com      # ← 多了一个空格

# 正确
proxies:
  - name: "A"
    type: trojan
    server: a.com

found unexpected end of stream

原因：引号没闭合，或者文件被截断。

检查所有引号是否成对；如果配置是下载来的，可能没下完整。

密码里的特殊字符

# 危险：# 会被当成注释，@ 和 : 也可能出问题
password: p@ss#word

# 正确
password: "p@ss#word"

二、字段与结构错误

语法没问题，但内核不认识你写的内容。

unmarshal error / cannot unmarshal !!str into int

原因：类型不对，比如端口写成了字符串。

# 错误
port: "443"      # 有些字段严格要求数字

# 正确
port: 443

反过来，UUID、密码这类必须是字符串：

uuid: 12345678-1234-1234-1234-123456789012      # 可能被解析成奇怪的类型
uuid: "12345678-1234-1234-1234-123456789012"    # 稳妥

unsupported proxy type: xxx

原因：订阅里用了当前内核版本不支持的协议。

修复：更新 Mihomo 内核。Clash Verge 里：设置 → Clash 内核 → 更新。

如果更新后还是不支持，说明这个协议确实还没被 Mihomo 实现，只能在服务商那边换个协议的节点。

proxy 'xxx' not found

原因：策略组里引用了不存在的节点名。

常见触发：

• 手写节点名时拼错了
• 订阅更新后节点改名了
• 扩展配置里引用的策略组名和订阅里不一致（emoji、空格差异）

修复：打开订阅原文件，复制粘贴准确的名字。或者改用 include-all + filter 自动收编，见节点分组正则。

rule 'xxx' error: invalid domain

原因：规则写法有误。

# 错误
- DOMAIN-SUFFIX,https://google.com,PROXY   # 不要写协议
- DOMAIN-SUFFIX,*.google.com,PROXY         # 不要写通配符
- IP-CIDR,8.8.8.8,DIRECT                   # IP-CIDR 必须带掩码

# 正确
- DOMAIN-SUFFIX,google.com,PROXY
- IP-CIDR,8.8.8.8/32,DIRECT,no-resolve

rules[N] [xxx] error: unsupported rule type

原因：规则类型名写错，或者内核版本不支持。

检查拼写：DOMAIN-SUFFIX 不是 DOMAIN_SUFFIX，IP-CIDR 不是 IPCIDR。

策略组循环引用

报错：配置加载卡住或提示 recursive。

原因：A 组的 proxies 里有 B，B 组的 proxies 里有 A。

修复：理清层级，保证引用是单向的（上层组引用下层组，下层不反向引用）。

三、DNS 相关

default-nameserver 里填了域名

# 错误
default-nameserver:
  - https://doh.pub/dns-query

# 正确：必须是纯 IP
default-nameserver:
  - 223.5.5.5
  - 119.29.29.29

default-nameserver 的用途就是解析其他 DNS 服务器的域名，所以它自己不能是域名。

解析不出内网域名

不是报错，是行为不对。原因是 fake-ip 拦截了。

dns:
  fake-ip-filter:
    - "+.mycompany.com"
    - "*.lan"
    - "*.local"

详见 DNS 配置详解。

四、规则集与 provider

provider xxx: initial failed

原因：规则集或订阅下载失败。

排查：

规则集加载了但不生效

原因：behavior 和文件内容不匹配。这个不会报错，只是静默失效。

rule-set xxx not found

规则集名在 rules 里引用了，但 rule-providers 里没定义，或者名字拼错了。

五、TUN 与权限

operation not permitted / TUN 开关点了没反应

原因：权限不足，虚拟网卡创建失败。

修复：

• Windows / macOS：安装「服务模式」
• Linux：sudo setcap cap_net_admin,cap_net_bind_service=+ep /path/to/mihomo

address already in use

端口被占用。

# Windows
netstat -ano | findstr :7897
tasklist | findstr <PID>

# Linux / macOS
lsof -i :7897

改端口或停掉占用的进程。

六、一个快速定位法

配置很长、报错又没给行号时，用二分法：

一个最小可用配置模板，用来做对照基线：

mixed-port: 7897
mode: rule
log-level: info
proxies:
  - name: "TEST"
    type: trojan
    server: example.com
    port: 443
    password: "pwd"
proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["TEST", DIRECT]
rules:
  - MATCH,PROXY

这份能加载，说明环境没问题，问题在你的配置内容里。

七、报错速查表

八、预防措施

小结

• mihomo -t -d 目录 是最有用的一条命令，报错比客户端详细
• YAML 三大坑：Tab 缩进、冒号后缺空格、引号没闭合
• proxy not found 通常是名字对不上，从订阅里复制
• 规则集不生效但不报错 = behavior 写错了
• 定位不了就用二分法砍配置

相关：YAML 结构详解、Merge 扩展配置。

相关文档

配置基础 Clash 配置文件 YAML 结构详解：八个顶层字段各管什么

把一份 Clash / Mihomo 配置从头到尾拆开讲：端口、模式、DNS、proxies、proxy-groups、rules、rule-providers 的作用与写法，附一份可直接使用的最小配置。

2026-08-021769 字约 4 分钟

配置基础 proxy-groups 五种类型详解：select、url-test、fallback、load-balance、relay

每种策略组的实际行为、适用场景和关键参数，附带一套可直接抄的分组结构，以及 Mihomo 特有的 include-all 与 filter 用法。

2026-07-291938 字约 5 分钟

配置基础 用 Merge 扩展订阅配置，改了也不会被更新覆盖

直接编辑订阅文件会在下次更新时前功尽弃。这篇讲 Clash Verge 的扩展配置机制：prepend/append/override 的写法、合并顺序，以及几个实用的扩展片段。

2026-07-091688 字约 4 分钟