Mihomo 配置文件怎么校验？YAML 格式错误与启动失败处理
简答：Mihomo 核心在启动时若因配置文件格式错误而崩溃，通常会在日志中输出类似 yaml 解析的报错。最快的校验方法是通过终端运行核心自带的测试参数（如 `./mihomo -t -d .`），定位具体行数并修正缩进或非法字符。注意语法校验通过仅代表 YAML 结构合规，仍需结合日志排查字段或逻辑问题。
定义：Mihomo 配置文件校验是指通过核心自带的测试参数，在启动服务前检查 YAML 语法及字段结构是否合规的过程。
一、 先试这一步：使用命令行快速校验配置
当你修改或导入 Mihomo 配置文件后遇到内核闪退、面板提示核心未运行，应优先通过命令行测试配置文件的语法有效性，避免盲目猜测。
- 打开终端/命令行：在存放 Mihomo 核心二进制文件（如
mihomo或mihomo.exe）以及配置文件的目录打开终端。 - 运行测试命令：输入核心测试命令并指定配置目录：
./mihomo -t -d .（macOS / Linux）.\mihomo.exe -t -d .（Windows PowerShell） - 判断输出结果：
- 若输出包含失败提示并附带具体错误行号（例如yaml: line XX），说明 YAML 存在语法错误。
- 若输出提示成功，则代表基本语法合规（但仍需注意字段和逻辑需符合配置文件规范）。
二、 常见的 YAML 格式错误与修复方法
Mihomo 配置文件对格式较为敏感。以下是排查时最常遇到的几类格式与结构问题：
- 缩进与制表符（Tab）问题：YAML 语法对缩进层级要求严格，若混用了 Tab 键可能导致解析异常，建议在编辑器中将缩进统一设置为 2 个或 4 个空格。
- 冒号与键值对写法：在映射键值场景中，冒号后通常需要加空格（如
port: 7890），避免因紧凑写法引起解析歧义。 - 特殊字符处理：当代理名称、密码或 URL 包含可能被 YAML 解释器误判的特殊符号（如某些特定花括号或标点）时，建议为字符串加上引号，并注意转义。
- 隐私与安全提示：若使用在线 YAML 校验工具排查，切勿将包含真实订阅链接、代理密码和私密节点的完整配置文件上传至不受信任的第三方网站，优先在本地通过命令行或受信任的本地编辑器进行检查。
三、 启动失败速查与进阶排查
如果通过了基础语法测试，但核心依然无法正常工作，可参考以下排查方向：
- 端口占用检查：若日志提示监听端口冲突（例如
7890或外部控制端口被占用），需修改配置文件中的对应端口或关闭冲突进程。 - 配置逻辑核对：检查策略组（
proxy-groups）中的代理名称引用是否与实际定义的节点名称完全一致。 - 重载方式确认：当配置文件调整后，建议通过控制面板或官方支持的 API 触发重载，或完全重启进程以应用新配置。
Mihomo 常见启动报错与排查对照表
| 错误现象 / 日志提示 | 可能原因 | 推荐排查与修复步骤 |
|---|---|---|
| yaml: line XX: mapping values are not allowed | 当前行缩进错位或在不该出现映射的地方使用了冒号 | 检查报错行上方是否有多余的冒号或缩进混乱 |
| found character that cannot start any token | 文件中可能包含了全角空格、不可见控制字符或非法编码 | 使用纯文本编辑器检查文件编码与不可见字符 |
| configuration file test failed | 语法校验未通过，核心拒绝加载 | 运行带 <code>-t</code> 参数的命令查看具体报错行数并修复 |
| 面板提示连接失败但核心进程存活 | YAML 语法正确，但外部控制 API 端口被占用或密钥不匹配 | 检查配置文件根目录下的监听端口与控制设置 |
常见问题
Mihomo 配置文件修改后，不重启核心能直接生效吗？
部分动态规则或策略调整支持通过控制面板或外部 API 触发重载；若修改了基础网络监听端口或核心结构，通常需要完全重启核心或按官方支持的重载方式操作以确保生效。
Windows 系统下双击 mihomo.exe 闪退怎么看报错？
不要直接双击运行。应当在核心所在文件夹打开 PowerShell 或终端窗口，手动输入 `.\mihomo.exe -t -d .` 回车，这样才能在窗口中看到完整的错误日志与行号提示。
YAML 文件可以用普通记事本编辑吗？
可以，但普通记事本对缩进和空格的展示不够直观。建议使用 VS Code、Sublime Text 或 Notepad++ 等专业代码编辑器，并将缩进设置为 2 个空格，以减少格式错位。