Mihomo 语法报错排查：缩进层级、特殊字符与格式校验

1. 常见报错信息译码与核心诱因

YAML 是一种对格式要求极度严苛的语言。以下是最具代表性的编译报错： ### 报错 1：`mapping values are not allowed here` - **原因**：冒号后缺少空格，或者在同一行连续使用了两个未加引号的冒号； - **错误示范**：`server:https://example.com` 或 `name: HK:01`； - **修正规范**：`server: "https://example.com"` 与 `name: "HK: 01"`。 ### 报错 2：`did not find expected key` - **原因**：缩进层级出现错位，或者混用了 Tab 制表符与空格； - **排查**：在代码编辑器（如 VS Code）中开启「显示所有空格与制表符（Render Whitespace）」，统一缩进为 2 个半角空格。 ### 报错 3：`found unexpected ':'` - **原因**：在非映射字段中意外出现了冒号，通常发生在密码或正则表达式过滤条件中。

💡 在 VS Code 中安装「YAML」扩展插件，可以在保存文件时实时进行语法纠错与高亮提示。

2. 特殊字符与标点符号防踩坑规范

代理配置中经常涉及复杂的加密密钥、URL 与特殊字符，遵循以下规则可杜绝 95% 的语法异常： 1. **必须加双引号的情景**： - 字符串中包含 `#`（YAML 将其视为注释符，未加引号会导致后面的内容被直接丢弃）； - 包含 `*` 或 `&`（YAML 将其视为锚点引用操作符）； - 包含 `:`（冒号后跟空格会被误判为键值映射）； - 包含布尔字面量（如节点名为 `true` 或 `false`，必须加引号 `"true"`，否则会被解析为布尔类型）。 2. **数组列表语法规范**： - 短横线 `-` 后必须紧跟一个空格； - 列表元素内部的缩进必须保持垂直对齐。

yaml

# 正确与错误对比范例

# 错误示范（将引发内核解析闪退）:
proxies:
- name: 香港 01 # 专线:测试
  type: ss
  password: Pass&Word#123:456

# 正确规范写法:
proxies:
  - name: "香港 01 # 专线:测试"
    type: ss
    password: "Pass&Word#123:456"

3. 本地命令行静态语法校验工作流

在将配置文件推送到远程软路由或守护服务之前，使用本地 CLI 校验是标准工程习惯：

bash

# 使用 -t 参数执行静默语法检查
mihomo -t -f ./config.yaml

# 若语法完全合法，输出:
# configuration file ./config.yaml test is successful

# 若语法存在错误，输出示例:
# fatal error: config file parse error: yaml: line 42: did not find expected key

4. 在线与本地格式化工具使用建议

对于超过上千行的庞大配置文件，肉眼排查极其低效： - **本地工具**：使用 `yq` 命令行工具（YAML 领域的 jq）进行结构转换：`yq eval config.yaml > /dev/null`； - **安全警告**：切勿将包含真实节点信息、账号密码与订阅链接的配置文件直接粘贴到不知名的公共在线「YAML 校验网站」，谨防节点订阅被恶意爬虫窃取盗刷。

❓ 常见疑问与排查步骤

用 Windows 自带的记事本编辑 config.yaml 可以吗？

极不推荐。Windows 记事本可能会在文件首部插入 UTF-8 BOM 标记，导致 Go 语言解析器抛出 `illegal character U+FEFF` 异常。推荐使用 VS Code、Sublime Text 或 Notepad++。

为什么更新订阅后原有配置中的自定义规则全没了？

因为机场下发的远程订阅通常会直接覆盖整个本地配置文件。如果需要持久化保留自定义规则，应使用 Clash Verge 的「扩展配置/预处理脚本（Merge/Script）」功能。

YAML 中多行注释应该怎么写？

YAML 不支持类似 C 语言的 /* */ 多行块注释，每一行都必须在行首添加 `#` 号进行注释。