Mihomo 核心配置 YAML 文件怎么写？从最小配置到订阅、规则与 DNS

更新于 2026-11-11 · man.christmas

简答：照着完整模板复制后启动报错、代理组为空或配置通过却没有代理效果？先把 Mihomo 配置拆成五层：最小运行、节点来源、代理组、规则、DNS/TUN。保存为 YAML 后，用 <code>mihomo -t</code> 校验；其中 <code>MATCH,DIRECT</code> 只表示内核能启动并直连，不会自动使用代理节点。

定义：Mihomo 核心配置 YAML 文件，是用 YAML 语法描述监听端口、节点、代理组、规则、DNS 和 TUN 等运行参数的配置文件。

先复制最小配置：确认 YAML、端口和内核都能运行

如果你是从空白文件开始，不要先复制包含订阅、规则集、fake-ip 和 TUN 的完整模板。先新建 config.yaml，确认当前内核能够读取配置并监听端口。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

这份配置只做启动验证：mixed-port: 7890 创建 HTTP 与 SOCKS 混合端口，allow-lan: false 不对局域网开放，MATCH,DIRECT 把未命中的请求直连。它没有任何代理节点，因此访问网站时应与未启用代理时基本一致。

在配置文件所在目录执行：

mihomo -t -d . -f ./config.yaml

如果二进制文件不在当前目录，把 mihomo 换成实际路径。命令行可用 -d 指定数据目录、-f 指定配置文件；图形客户端的激活配置目录和重载入口需以当前版本界面为准。端口配置可参考 Mihomo 入站配置文档。

五层配置速查卡

层级	主要增加内容	校验方法	出错时回滚
1. 最小运行	`mixed-port`、模式、规则兜底	`mihomo -t`	恢复空节点模板
2. 节点来源	`proxies` 或 `proxy-providers`	校验后查看节点列表和日志	删除最近加入的节点或提供器
3. 代理组	`proxy-groups`、`select`、`url-test`	确认引用名称存在	恢复只含节点的配置
4. 规则	`rules`、`rule-providers`	先用少量明确规则测试	保留 `MATCH,DIRECT`
5. DNS/TUN	`dns`、`tun`	逐个模块加入并校验	删除最近加入的 DNS 或 TUN 段

YAML 写法：空格、大小写、冒号和列表不能错

只使用空格缩进：不要使用 Tab，同一层级的键必须左对齐。
冒号后留空格：写成 port: 7890，不要写成 port:7890。
键名区分大小写：proxy-groups、proxy-providers 和 rules 必须按文档拼写。
列表使用短横线：例如 rules: 下一层写成 - MATCH,DIRECT。
特殊字符加引号：URL、包含冒号或井号的文本，以及域名通配符，出现解析歧义时应使用引号。
注释使用井号：# 后面的内容通常是注释，但 URL、密码或字符串中的井号需要按字符串处理。

出现 did not find expected key、mapping values are not allowed 或错误行号指向下一行时，先检查上一行的缩进、冒号和引号。Mihomo 的语法说明可查看 Mihomo YAML 语法文档。

节点怎么写：手写 proxies 与订阅 proxy-providers 的区别

proxies、proxy-providers 和 proxy-groups 不是同一层字段：

字段	作用	代理组如何引用
`proxies`	直接写入节点列表	在代理组的 `proxies` 中写节点名称
`proxy-providers`	从 URL 或文件加载节点集合	在代理组的 `use` 中写提供器键名
`proxy-groups`	把节点或提供器组合成选择、测速或回退策略	在规则中写代理组名称

手写节点时，name 应保持唯一，type、server 和 port 等字段需要与协议页面匹配。不要把一种协议的字段复制到另一种协议。

proxies:
  - name: "vless-example"
    type: vless
    server: example.com
    port: 443
    uuid: "替换为真实 UUID"
    tls: true
    servername: example.com
    network: tcp

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - vless-example
      - DIRECT

rules:
  - MATCH,PROXY

上面只是 VLESS 字段骨架，域名、端口、UUID、TLS、SNI、传输层以及其他安全参数必须以服务端提供的参数为准。字段可核对 Mihomo VLESS 配置文档。

如果你要手写其他协议，先按对应官方子页面核对专属字段：

协议	常见专属字段方向	核对资料
Shadowsocks	加密方法、密码及可选插件参数	Shadowsocks 配置文档
VMess	UUID、加密方式、TLS 和传输层	VMess 配置文档
VLESS	UUID、TLS、SNI、传输层和安全参数	VLESS 配置文档
Trojan	密码、TLS、SNI 和传输层	Trojan 配置文档
Hysteria2	密码、TLS、端口跳跃等协议字段	Hysteria2 配置文档

表格只用于定位字段，不代表这些协议可以使用同一份模板。当前内核是否支持某个字段，应以对应官方页面和 mihomo -t 的结果为准。

订阅节点可以通过提供器加载：

proxy-providers:
  provider1:
    type: http
    url: "https://example.com/subscription"
    path: ./proxy_providers/provider1.yaml
    interval: 3600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300

proxy-groups:
  - name: "PROXY"
    type: select
    use:
      - provider1
    proxies:
      - DIRECT

use 引用的是 proxy-providers 下的键名，不是某个节点名称；path 是提供器文件保存路径，运行用户需要有写入权限。提供器字段可查看 proxy-providers 配置文档。

代理组怎么写：proxies、use、include-all 分别代表什么

proxies 直接列出节点或其他代理组，适合手写并精确控制；use 引用一个或多个提供器，适合订阅节点；include-all 用于纳入所有出站节点和提供器，具体行为需以当前文档为准。代理组名称必须与规则中使用的名称完全一致。

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "vless-example"
      - DIRECT

  - name: "AUTO"
    type: url-test
    use:
      - provider1
    url: "https://www.gstatic.com/generate_204"
    interval: 300

select 便于手动选择，url-test 会根据测试 URL 比较延迟；延迟结果不等于下载速度或长期可用性。代理组字段可对照 Mihomo 代理组配置文档。

规则怎么写：从具体条件开始，MATCH 放在最后

规则通常按从上到下的顺序匹配，前面的规则优先；MATCH 会匹配尚未命中的请求，因此应作为最后兜底。

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,DIRECT

首次使用 GEOIP 时，应确认当前内核能够取得所需 GeoIP 数据库。若运行环境无法下载数据库，可能出现启动失败、规则不可用或初始化等待。排查顺序是：先查看日志中是否出现 GeoIP 数据库相关错误；能提供本地数据库时预置到当前数据目录；需要远程下载时核对当前版本的 geox-url 配置；如果只是验证基础代理流程，先删除 GEOIP,CN,DIRECT，临时保留具体域名规则和 MATCH,DIRECT。

DOMAIN 匹配完整域名，DOMAIN-SUFFIX 匹配域名后缀，RULE-SET 引用规则集合。规则类型和优先级可查看 Mihomo 路由规则文档。

加入大型规则集前，先用两三条明确规则确认代理组名称和动作都能生效，再增加 rule-providers。规则集合的行为、格式和文件内容要相互匹配，可参考 Mihomo rule-providers 配置文档。

DNS 怎么写：新手先用简单配置，fallback 要同时看过滤逻辑

建议第一次启动时不要同时启用 fake-ip、fallback、respect-rules 和 TUN。确认端口、节点和规则正常后，再一次增加一个 DNS 功能。

dns:
  enable: true
  ipv6: false
  enhanced-mode: redir-host
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query

enhanced-mode 可使用 fake-ip 或 redir-host。如果切换到 fake-ip 后局域网域名、设备发现或某些应用异常，先回滚到 redir-host，再根据日志和实际域名补充 fake-ip-filter。

fallback 在官方文档中被定义为备用域名解析服务器；配置后，fallback-filter 默认启用，geoip-code 默认值为 CN。过滤条件会影响是否采用 fallback 的结果，而不是简单等同于“主 DNS 失败后才切换”。官方文档还说明，fallback-lazy-query 默认值为 false；设置为 true 时，会先判断 nameserver 结果是否满足过滤条件，再发起 fallback 查询。因此这个字段可以使用，但不建议新手一开始加入。

dns:
  enable: true
  ipv6: false
  enhanced-mode: redir-host
  nameserver:
    - https://doh.pub/dns-query
  fallback:
    - tls://8.8.4.4
    - tls://1.1.1.1
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 0.0.0.0/32
      - 127.0.0.1/32
    domain:
      - "+.example.com"

nameserver-policy 的优先级高于普通 nameserver/fallback 查询。启用 respect-rules 时，官方要求配置 proxy-server-nameserver；它用于解析代理节点域名，避免节点域名本身无法解析。DNS 字段和解析流程可查看 Mihomo DNS 配置文档。

最小 TUN 配置：确认端口和规则后再启用

TUN 会接管系统流量，涉及系统权限、路由、DNS 劫持和防火墙。它不应与最小端口配置一起作为第一次验证内容。确认普通代理端口和节点可用后，再尝试下面这个最小片段：

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-route 用于自动设置全局路由，dns-hijack 把匹配的 DNS 请求导入内部 DNS 模块。不同系统对权限、路由和防火墙的要求不同；Windows、macOS、Linux 和 Android 的行为不能只凭同一份 YAML 推断。官方 TUN 文档列出了 stack、auto-route、dns-mode、dns-hijack 和 strict-route 等字段，启用前应按当前平台核对 Mihomo TUN 配置文档。

如果加入 TUN 后断网，先删除整个 tun 段，恢复到 mixed-port 加系统代理的工作状态，再逐个恢复选项。不要同时修改 MTU、DNS、路由和防火墙设置。

排错表：按现象、检查、处理和回滚定位

Mihomo YAML 常见问题排查

现象	检查	判断与处理	回滚方式
YAML 解析失败	检查报错行及上一行的 Tab、缩进、冒号、引号和列表层级	修正语法后重新执行 `mihomo -t -d 配置目录 -f 配置文件`	恢复最近一次通过校验的备份
代理组提示节点不存在	逐字比较节点 `name` 与代理组的 `proxies`	名称必须完全一致；使用订阅时确认 `use` 写的是提供器键名	暂时删除代理组，只保留节点
代理组为空	检查订阅返回内容、`path` 权限、数据目录和提供器日志	确认 URL 返回的是内核可识别内容；必要时先改用手写节点验证	删除 `proxy-providers` 和 `use`
端口启动失败	检查 `7890` 是否被其他程序占用	更换未占用的 `mixed-port`，并让系统代理指向新端口	恢复原端口或关闭占用进程
校验通过但没有代理效果	检查规则是否仍是 `MATCH,DIRECT`，系统代理是否指向混合端口	校验只说明配置能解析；使用真实代理组后，再用 `curl -x http://127.0.0.1:7890 https://example.com` 测试	先回到最小直连配置，分别验证端口和节点
GEOIP 规则导致启动或初始化异常	查看日志中的 GeoIP 数据库错误，确认数据目录和下载地址	预置数据库、核对当前版本的 `geox-url`，或暂时删除 GEOIP 规则	改为具体域名规则加 `MATCH,DIRECT`
DNS 或 TUN 加入后断网	删除最近加入的 `dns`、`fake-ip` 或 `tun` 段逐项测试	确认普通端口、系统代理、DNS 和 TUN 的边界，不要一次改多个模块	恢复上一个能启动的完整配置

最终判断标准是：mihomo -t 通过，只代表当前内核可以解析配置；节点认证、远端端口、TLS 参数、DNS 连通性和网页访问仍需通过运行日志及实际请求分别验证。

保存、启动和回滚：每次只改一个模块

把当前能启动的文件复制为 config.yaml.bak。
只增加一个模块，例如先增加 proxies，不要同时增加订阅、DNS、规则集和 TUN。
保存后执行 mihomo -t -d 配置目录 -f 配置文件。
校验通过后，再重启核心或使用客户端的“应用配置”“重载配置”功能；具体按钮名称以当前版本界面为准。
启动失败时恢复备份，确认核心重新启动，再定位最近一次改动。

“文件保存成功”不等于“当前运行实例已经加载”。图形客户端可能使用单独的配置目录、激活配置和数据目录，因此需要在客户端日志或启动参数中确认实际加载的文件。

常见问题

Mihomo 配置文件必须叫 config.yaml 吗？

不一定。命令行可以用 <code>-f</code> 指定其他 YAML 文件，用 <code>-d</code> 指定数据目录。图形客户端可能只加载自己的激活配置，实际文件名和路径需要在当前客户端的配置管理、启动参数或日志中核实。

为什么 mihomo -t 通过了，但还是不能上网？

<code>-t</code> 主要验证当前内核能否解析配置，不代表节点认证、DNS、远端端口和网页访问都正常。先确认规则没有仍然指向 <code>DIRECT</code>，再确认系统代理指向 <code>mixed-port</code>，最后查看运行日志和节点连接错误。

proxy-groups 里的 proxies 和 use 有什么区别？

<code>proxies</code> 直接引用节点或其他代理组名称；<code>use</code> 引用 <code>proxy-providers</code> 下的提供器键名。手写节点通常用前者，订阅或文件加载的节点通常用后者。

fallback 是不是只有主 DNS 失败后才会使用？

不能只按普通备用服务器理解。配置 <code>fallback</code> 后，<code>fallback-filter</code> 会根据 <code>geoip</code>、<code>geoip-code</code>、<code>ipcidr</code> 和 <code>domain</code> 等条件判断是否采用 fallback 结果；官方文档还说明 <code>fallback-lazy-query</code> 默认值为 <code>false</code>。新手可以先不配置 fallback，或同时明确写出过滤条件。

为什么加入 GEOIP,CN,DIRECT 后启动变慢或失败？

GEOIP 规则需要对应的 GeoIP 数据。先查看日志是否有数据库下载或读取错误；可以预置数据库并核对当前版本的 <code>geox-url</code>，也可以暂时删除 GEOIP 规则，只用具体域名规则和 <code>MATCH,DIRECT</code> 验证基础配置。

加入 TUN 后断网，应该先改哪个字段？

先回滚整个 <code>tun</code> 段，确认普通 <code>mixed-port</code> 和系统代理可以工作，再按平台逐项恢复 <code>auto-route</code>、<code>dns-hijack</code> 等设置。TUN 还涉及系统权限、路由和防火墙，不能只凭 YAML 语法判断。