Mihomo 核心配置教程:从 config.yaml 到订阅、DNS、规则与 TUN 排错
简答:Mihomo 核心配置建议按“先启动、再导入订阅、最后开启 DNS 和 TUN”的顺序完成。先用最小 config.yaml 验证端口和代理组,再根据订阅格式补充 proxy-providers、rules 与 DNS;任何配置改动后,都应查看启动日志、确认端口监听,并逐项复测。
定义:Mihomo 核心配置是通过 YAML 文件定义监听端口、代理节点、代理组、DNS、规则和 TUN 入站行为的一组参数。
先用三步跑通:不要一开始就开启 TUN
如果你只是想让 Mihomo 先工作,建议先完成下面三步:第一,准备与当前核心版本匹配的配置文件;第二,只启用一个本地代理端口和一个代理组;第三,确认客户端或系统代理指向该端口后,再逐步加入订阅、DNS、规则和 TUN。Mihomo 官方文档将配置分为通用设置、入站、代理、代理组、DNS 和路由规则等模块,模块之间存在引用关系,一次加入太多字段会让排错变得困难。可先查看官方配置索引了解字段分类。
| 方案 | 适合场景 | 需要填写的内容 | 主要风险 |
|---|---|---|---|
| 手写节点 | 测试核心、验证单个协议 | proxies、proxy-groups、rules | 服务器地址、端口、密码或 TLS 参数填错 |
| proxy-providers 订阅 | 已有订阅链接,需要定期更新 | provider 的 url、path、proxy-groups 的 use | 订阅返回格式不兼容、链接无法访问或名称引用错误 |
| 客户端托管配置 | 使用图形客户端导入订阅 | 按客户端页面导入并选择配置 | 客户端可能覆盖端口、DNS 或 TUN 字段 |
| TUN 进阶配置 | 希望接管不支持系统代理的应用 | tun、dns-hijack、auto-route 等 | 权限、防火墙、路由冲突或 DNS 回环 |
重要:下文出现的域名、节点地址、订阅 URL、UUID、密码和路径均为占位符,不能直接使用。请替换为你自己确认过的参数,并以当前核心的官方 Schema 和启动日志为准。
Mihomo 核心、客户端和 config.yaml 的关系
Mihomo 是负责处理代理连接、监听本地端口、解析 DNS、匹配规则和建立 TUN 入站的核心程序;图形客户端主要负责下载核心、选择配置、切换系统代理、管理日志和提供界面。config.yaml 则是核心读取的配置文件,通常由客户端托管,也可以由用户通过命令行或服务方式启动。
因此,客户端页面里显示的“代理模式”“系统代理”“TUN”不一定等于配置文件中的单个字段。遇到连接问题时,应先判断是核心没有启动、配置没有被加载、客户端没有接管系统代理,还是规则把请求送到了错误的出口。官方启动文档提供了按系统选择二进制和运行方式的说明,配置目录则由启动参数中的工作目录决定,可参考官方启动文档。
在 Linux 服务场景中,官方示例使用 mihomo -d /etc/mihomo 指定工作目录;Windows、macOS 或图形客户端的路径可能不同,不能直接照搬 Linux 目录。启动参数、配置目录和客户端自己的配置目录必须对应,否则会出现“文件已经修改但运行效果没有变化”的假象。
最小 config.yaml:先验证端口、代理组和规则
下面是用于理解字段关系的最小结构示例。它没有提供真实代理节点,因此不能直接访问外部网络;你需要将 server.example、端口、密码和协议字段替换成自己已核实的节点参数。示例重点是让你看懂“代理节点名称—代理组引用—规则引用”的链路。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: "请替换为本地随机密钥"
proxies:
- name: "手写节点-示例"
type: ss
server: server.example
port: 443
cipher: chacha20-ietf-poly1305
password: "请替换为真实密码"
proxy-groups:
- name: "代理选择"
type: select
proxies:
- "手写节点-示例"
- DIRECT
rules:
- MATCH,代理选择
这里的 mixed-port 同时提供 HTTP 和 SOCKS 代理入口;mode: rule 表示按规则匹配;proxy-groups 中的名称必须与 rules 最后一列完全一致。代理组中的 proxies 可以引用节点或其他代理组,官方字段说明见代理组配置文档。
验证顺序:先启动核心并确认没有 YAML 解析错误;然后确认本机 7890 端口已监听;接着在客户端或系统代理中填写 HTTP 和 SOCKS 均使用的本地端口;最后在代理组中选择节点。若只看到配置加载成功,但没有任何请求记录,通常应先检查客户端是否真的指向了该端口。
proxies 与 proxy-providers:手写节点还是导入订阅
proxies 直接把节点写进主配置文件,适合测试单个节点或学习字段;proxy-providers 则把节点集合放在独立文件中,由 Mihomo 按 URL、文件或内联内容加载。官方文档列出了 http、file 和 inline 三类 provider,并说明了 path、interval、健康检查和代理组 use 的关系,可参考proxy-providers 配置文档。
订阅模板如下,仍然只是字段模板,不能直接运行:
proxy-providers:
provider-main:
type: http
url: "https://subscription.example/replace-me"
path: ./proxy_providers/provider-main.yaml
interval: 3600
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 300
timeout: 5000
expected-status: 204
proxy-groups:
- name: "自动选择"
type: url-test
use:
- provider-main
url: https://www.gstatic.com/generate_204
interval: 300
rules:
- MATCH,自动选择
最容易出错的地方有三个:一是订阅 URL 返回的不是 Mihomo 可识别的代理集合;二是 provider-main 在 use 中拼写不一致;三是 provider 文件路径不在核心允许的工作目录范围内。先单独确认订阅内容和文件落盘,再检查代理组是否真的加载出节点,不要直接把“订阅下载成功”当成“节点已经可用”。
端口、allow-lan、external-controller 和安全边界
本地单机使用时,通常先保持 allow-lan: false,并让监听端口绑定在本机。只有当其他设备需要通过当前设备共享代理时,才考虑开启局域网访问,同时限制绑定地址和允许网段。官方通用配置文档说明了 allow-lan、bind-address、允许或拒绝的 IP 范围以及代理认证字段,具体以通用配置文档为准。
external-controller 用于让控制面板或 API 管理运行中的核心。若将它绑定到局域网或公网地址,却没有设置强随机的 secret,可能导致未授权控制风险。建议初学者先使用 127.0.0.1,只让本机访问;确认客户端需要控制器后,再按照客户端要求填写地址和密钥。
| 现象 | 优先检查 | 处理动作 |
|---|---|---|
| 核心启动时报端口被占用 | 其他客户端或旧进程是否占用端口 | 换一个本地端口,或关闭旧进程后重启 |
| 客户端提示连接控制器失败 | external-controller 地址和 secret | 确认地址、端口和密钥完全一致 |
| 同一局域网设备无法连接 | allow-lan、bind-address、防火墙 | 只在可信局域网内开启,并限制访问范围 |
| 代理端口能连但网页不通 | 节点、代理组和规则 | 先手动选择节点,再暂时使用 MATCH 规则复测 |
DNS 配置:先保持简单,再处理分流和 fake-ip
Mihomo 的 DNS 配置包括默认 DNS、主 DNS、备用 DNS、域名策略、代理节点域名解析和直连域名解析。官方文档说明,enhanced-mode 可使用 fake-ip 或 redir-host;nameserver-policy 可按域名或规则集合指定解析器;proxy-server-nameserver 专门用于解析代理节点域名,可避免代理节点域名解析时产生循环依赖。详情见DNS 配置文档。
初学者可先采用较保守的结构,避免同时启用过多高级选项:
dns:
enable: true
ipv6: false
enhanced-mode: redir-host
nameserver:
- https://doh.pub/dns-query
proxy-server-nameserver:
- 223.5.5.5
如果遇到“节点域名无法解析”,先检查 proxy-server-nameserver;如果遇到“局域网设备或部分应用打不开”,先暂时关闭 TUN 和 fake-ip,确认普通系统代理是否正常;如果只有特定域名异常,再检查 nameserver-policy、规则集合和域名通配符。不要把 DNS 故障直接判断为节点故障。
规则与代理组:从上到下匹配,最后保留 MATCH
规则的作用是决定请求交给哪个代理组、节点或 DIRECT。常见结构是先写更具体的域名或 IP 规则,再用 MATCH 作为兜底。规则中引用的代理组名称必须存在,名称包含特殊字符时应按官方示例加引号。
proxy-groups:
- name: "代理选择"
type: select
use:
- provider-main
- provider-backup
proxies:
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,代理选择
- GEOIP,CN,DIRECT
- MATCH,代理选择
select 适合手动选择;url-test 可按健康检查结果选择节点;fallback 则按可用性选择备用出口。代理组官方文档列出了这些类型的通用字段、健康检查 URL、间隔、超时和 provider 引用方式,可结合代理组文档核对。
排错时可以暂时把规则缩减为一条 MATCH,代理选择。如果这样能访问,说明节点或端口大概率可用,问题集中在规则顺序、规则集合未加载或代理组名称不一致;如果仍不能访问,则继续查节点、DNS、系统代理和防火墙。
TUN 模式:最后开启,并准备回滚
TUN 适合接管不遵循系统代理的应用,但它会改变系统路由、DNS 处理和权限要求。官方文档说明,顶层 tun 配置适合一般用户,TUN listener 属于更进阶的用法;常见字段包括 auto-route、auto-redirect、auto-detect-interface、dns-hijack 和协议栈设置,具体见TUN 配置文档。
建议在普通代理已经可用后,再尝试下面的结构:
tun:
enable: true
stack: system
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
这段配置仍需结合系统、客户端权限和当前核心版本核对,不能保证适用于所有平台。开启后若网页全部无法访问,回滚顺序是:关闭 TUN;恢复系统代理;清理或恢复 DNS 设置;重启核心;再用最小配置验证。Windows、macOS、Linux、Android 对虚拟网卡、防火墙和权限的处理不同,不能把一个平台的 TUN 现象直接套到另一个平台。
启动失败与连接异常:按现象分流排查
| 现象 | 可能原因 | 验证方法 | 回滚或修复 |
|---|---|---|---|
| 启动立即退出 | YAML 缩进、Tab、字段类型或引号错误 | 查看启动日志,逐段删除最近新增配置 | 恢复到上一次能启动的版本,再逐项添加 |
| 没有请求记录 | 系统代理未指向 mixed-port,或客户端未启用代理 | 检查系统代理地址、端口和客户端开关 | 先关闭 TUN,仅验证普通 HTTP/SOCKS 代理 |
| 代理组为空 | provider 未加载、use 名称错误或订阅格式不兼容 | 检查 provider 文件、订阅返回内容和日志 | 改用一个已核实的手写节点测试 |
| 节点显示在线但网页打不开 | DNS、规则、TLS 参数或节点本身异常 | 临时使用 MATCH 规则,测试域名解析和直连端口 | 恢复简单 DNS,重新选择节点 |
| 开启 TUN 后断网 | 权限、防火墙、DNS 劫持或路由冲突 | 关闭 TUN 后复测,查看虚拟网卡和防火墙日志 | 关闭 auto-route 或完整回滚 TUN 配置 |
配置文件中的列表必须使用空格缩进,不要混用 Tab;节点名称、代理组名称和规则引用必须逐字一致。不要把多个网上模板直接拼接,因为字段是否支持、字段类型和默认行为可能随核心版本变化。官方配置页面会持续更新,发布前应逐项核对当前页面。
配置完成后的复测清单
- 核心复测:确认配置加载完成,没有 YAML、字段类型或端口错误。
- 端口复测:确认本地 mixed-port 或其他监听端口处于监听状态,且没有被其他程序占用。
- 代理组复测:确认代理组中出现节点,手动选择一个节点,不要一开始依赖自动选择。
- 请求复测:先访问一个普通网页,再测试需要代理的目标;观察日志中是否出现请求和出口。
- 规则复测:临时保留一条 MATCH 规则;确认可用后,再恢复域名、IP、规则集合等复杂分流。
- DNS 复测:只有在普通代理稳定后,再加入 fake-ip、nameserver-policy 或 DNS 劫持。
- TUN 复测:最后启用 TUN,确认系统权限、防火墙和路由正常,并保留可回滚的旧配置。
如果使用 Linux 服务运行,可参考官方的 systemd 示例查看服务状态和日志;如果使用图形客户端,则优先查看客户端内置日志和当前实际加载的配置,而不是只看磁盘中的原始文件。相关运行方式见官方服务启动文档。
常见问题
Mihomo 核心配置文件一般放在哪里?
没有一个适用于所有客户端的固定目录。核心通常根据启动时的工作目录参数读取 config.yaml,图形客户端也可能使用自己的配置目录。Linux 服务示例使用 -d 指定工作目录;Windows、macOS、Android 的目录和权限由客户端实现决定。排查时应先确认客户端显示的“当前配置路径”或启动日志,再修改对应文件,不要只在下载目录里寻找配置。
proxies 和 proxy-providers 应该选哪个?
只有一个节点、正在测试协议字段时,使用 proxies 更直观;已有订阅并且需要定期更新时,使用 proxy-providers 更合适。provider 需要配置类型、订阅地址或文件路径,代理组还要通过 use 引用 provider 名称。两者也可以同时存在,但名称必须唯一,且不能把订阅 URL 当作节点地址直接填入 proxies。
为什么配置启动成功,但代理组里没有节点?
常见原因是 provider 没有成功下载、订阅返回格式无法解析、provider 名称和代理组 use 不一致,或者 provider 文件路径不在核心允许的工作目录范围内。建议先查看日志,确认 provider 文件是否生成;再把代理组临时改为引用一个手写节点。如果手写节点能出现,问题通常集中在订阅加载或 provider 配置,而不是端口本身。
DNS 应该使用 fake-ip 还是 redir-host?
没有适合所有设备和应用的统一答案。redir-host 更适合作为初始排错方案,结构相对简单;fake-ip 可能改善部分分流场景,但会涉及 fake-ip 地址池、过滤列表、DNS 劫持和应用兼容性。建议先让普通代理和简单 DNS 工作,再根据具体应用的解析表现切换模式;出现局域网、登录或部分应用异常时,优先回滚到较简单的 DNS 配置。
Mihomo 开启 TUN 后无法上网怎么办?
先关闭 TUN,恢复普通系统代理,确认节点和 DNS 本身可用;然后检查核心权限、防火墙、虚拟网卡、auto-route 和 dns-hijack。不同系统对 TUN 的权限和路由处理不同,不能直接复制其他平台的配置。若关闭 TUN 后网络恢复,说明问题集中在 TUN 分支,应从最小 TUN 配置开始逐项增加字段。
规则中的 MATCH 为什么建议保留?
MATCH 是兜底规则,用于处理前面没有匹配到的请求。没有兜底规则时,部分请求可能没有明确出口,排错时也难以判断是节点问题还是规则未命中。建议先用 MATCH 指向一个明确的代理组验证链路,确认可用后,再加入更具体的域名、IP、规则集合和直连条件。