典型报错：
mapping values are not allowed here/did not find expected key/invalid character/ Clash 启动后规则不生效。90% 来自缩进、冒号、列表或字符转义错误。
🧱 基础规则
- 只允许使用空格，禁止 Tab。（Tab 会被解释为不同宽度）
- 缩进层级通常为 2 空格或 4 空格，项目内保持统一。
key: value冒号后必须至少 1 个空格。- 列表使用
-后跟空格：- name。 - 需要字符串原样保留时加引号：端口前导 0、布尔字样、含特殊字符。
🧪 常见错误对照
| 错误示例 | 问题 | 修正 |
|---|---|---|
port: 08 |
被解析为 8（八进制风险） | "08" |
mixed-port:7890 |
缺少冒号后空格 | mixed-port: 7890 |
- - name: test |
多余 - |
- name: test |
cipher: [aes-128-gcm,aes-256-gcm] |
缺空格/逗号后空格 | cipher: [aes-128-gcm, aes-256-gcm] |
| `rules: | ||
| -DOMAIN,example.com,DIRECT` | - 后缺空格 |
- DOMAIN,example.com,DIRECT |
password: abc:123 |
冒号截断 | "abc:123" |
#注释紧贴 |
注释最好前留空格 | # 注释 |
🧩 列表与字典
正确：
proxies:
- name: node1
type: vmess
server: x.x.x.x
port: 443
uuid: 1111-2222
- name: node2
type: hysteria2
server: y.y.y.y
port: 8443
错误（缩进错位）：
proxies:
- name: node1
type: vmess # 与上一行不对齐
🔐 引号策略
| 场景 | 是否建议加引号 | 示例 |
|---|---|---|
| 含冒号 / # / & / * | 必须 | "abc:123" |
| 前导 0 / 全数字串 | 建议 | "00123" |
| 布尔字面量 true/false | 可避免误解析 | "false" |
| IPv6 地址 | 建议 | "2606:4700::1111" |
| 纯域名/普通词 | 可不加 | example.com |
🏷 锚点与引用
common-proxy: &base
type: socks5
server: 127.0.0.1
port: 7890
proxies:
- { name: local, <<: *base }
注意：<<: 合并只在字典层有效；列表不支持直接合并。
📜 多行与折叠
| 语法 | 行为 | 示例 |
|---|---|---|
| ` | ` | 保留换行 |
> |
换行折叠为空格 | 文本描述类字段 |
🛠 快速校验工具
- 命令行：
yamllint config.yaml（需安装）。 - Clash 本身：查看启动日志第一屏是否报错。
- 在线验证：粘贴到 yamllint.com / codebeautify.org（注意脱敏）。
🧪 最小化测试法
怀疑错在某一段 → 复制文件 → 仅保留 port / proxies(1条) / rules(1条) → 若可启动，逐段恢复定位。
最小示例模板
port: 7890
socks-port: 7891
allow-lan: true
mode: rule
proxies:
- name: test
type: direct
udp: true
proxy-groups:
- name: 🚀 节点选择
type: select
proxies: [test]
rules:
- MATCH,🚀 节点选择
🔁 终极排查 Checklist
- 查找 Tab：编辑器显示不可见字符 → 全部替换为空格。
- 逐层对齐：同级键垂直对齐。
- 注释行前留一个空格增强可读性。
- 复杂行（带逗号、冒号）先用引号包裹。
- 使用最小化测试法验证核心逻辑后再扩展。
遇到仍无法定位：附上报错信息 + 相关 20 行上下文（脱敏）求助，效率最高。