mihomo 配置文件入门：YAML 结构详解
用图形客户端时，配置文件是隐形的——导入订阅，一切自动完成。但只要你想改一条规则、加一个自定义节点、或者把内核跑在服务器上，就绕不开这份 config.yaml。好消息是它的结构相当规整：一份 mihomo 配置无非是「几个全局开关 + 三个列表」。
这篇文章带你把这份 YAML 拆开看：先讲最容易踩坑的语法规则，再过一遍顶层字段，然后给出一份能直接跑通的最小配置，最后讲怎么校验和定位报错。
YAML 语法的三条铁律
mihomo 配置写错，十次里有八次不是字段不对，而是 YAML 格式不对。记住三点就能避开绝大多数坑：
- 缩进只能用空格，不能用 Tab。同一层级的缩进量必须完全一致，通常用两个空格。很多编辑器默认按 Tab 键插入制表符，写配置前先把编辑器设成「Tab 转空格」。
- 冒号后面必须有一个空格。
mode: rule正确，mode:rule会被当成一整个字符串。 - 不能用中文全角符号。中文输入法下敲出的全角冒号「：」、全角逗号和全角引号，肉眼几乎看不出差别，解析器却完全不认。报错行看着毫无问题时，先怀疑这个。
技巧：用带 YAML 语法高亮的编辑器改配置。全角符号和错误缩进在高亮下颜色会明显不对，一眼就能看出来。
顶层字段总览
配置文件最外层的字段各管一摊，常用的这些先认全：
| 字段 | 作用 | 说明 |
|---|---|---|
mixed-port | 本地混合监听端口 | 同时接受 HTTP 与 SOCKS5，客户端和终端都连这里 |
allow-lan | 是否允许局域网设备连入 | 不需要共享给其他设备时保持 false 更安全 |
mode | 运行模式 | rule 按规则分流、global 全走代理、direct 全直连 |
log-level | 日志级别 | 常用 info，排错时可调到 debug |
external-controller | 外部控制接口地址 | 供面板和客户端调用，建议只绑定 127.0.0.1 |
dns | DNS 相关设置 | 接管域名解析，见 DNS 专文 |
proxies | 节点列表 | 每个节点的地址、端口、协议、密钥 |
proxy-groups | 代理组 | 把节点组织起来供规则引用和手动切换 |
rules | 分流规则 | 决定每个连接走哪个组或直连 |
一份可直接运行的最小配置
下面这份配置麻雀虽小五脏俱全，把节点信息换成你自己的就能跑：
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
proxies:
- name: "节点A"
type: ss
server: server.example.com
port: 8388
cipher: aes-128-gcm
password: "your-password"
proxy-groups:
- name: "PROXY"
type: select
proxies:
- "节点A"
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- GEOIP,CN,DIRECT
- MATCH,PROXY保存为 config.yaml，用 mihomo -d 指向它所在的目录启动，内核就会在 7890 端口上待命。完整的启动方式见 mihomo Linux 服务器部署教程。
proxies、proxy-groups、rules 的关系
这三个列表是逐层引用的关系，理解了这条链路，配置就不再是天书：
proxies定义节点：一台台真实的服务器，每个有唯一的name。proxy-groups定义代理组：按name把节点收进来，决定「这一组里到底用哪个节点」——手动选、自动测速、故障转移都在这层。组也有自己的name。rules定义分流：每条规则的末尾写的是一个组名或DIRECT/REJECT，表示匹配到的流量交给谁。
所以一个连接的完整路径是：规则匹配 → 命中某个代理组 → 组按自己的策略挑出一个节点 → 流量从这个节点出去。规则里写的名字必须在代理组或节点中真实存在，写错一个字内核就会启动失败。代理组的四种类型见 代理组详解，规则的写法见 分流规则入门。
校验配置与定位报错
改完别直接启动，先校验——这一步能省掉大量来回：
mihomo -t -f config.yaml-t 只做解析检查，不真正启动内核。没问题时静默通过，有问题会打印出错原因和行号。常见的几类报错这样理解：
- 提示某行
mapping values are not allowed之类的解析错误：这是 YAML 层面的问题，去看那一行及其上一行的缩进和冒号后的空格。 - 提示重复键：同一层级出现了两个同名字段，比如粘贴时不小心留下两个
dns段。 - 提示 proxy 或 group 不存在：规则里引用的名字和代理组的
name对不上，注意空格和大小写。 - 报错行号看着完全正常：真正的问题往往在它上面几行，YAML 解析器是读到出错处才报的。
配置跑通之后，下一步通常是调 DNS——这是影响连通性和分流准确度最大的一块，思路见 mihomo DNS 配置详解。