Mihomo启动失败怎么办？先看日志再修复端口、配置与TUN

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

简答：Mihomo启动失败，先不要删除整个配置目录：关闭客户端并备份配置，复制启动阶段最早出现的第一条 error、fatal 或 failed。30 秒判断：客户端没打开就先看客户端日志并备份自身配置；客户端打开但内核没起，执行配置校验并查端口；内核已起但代理不可用，则转查系统代理、DNS、规则或节点连接。

定义：Mihomo启动失败，是指图形客户端无法打开、客户端无法拉起Mihomo内核，或内核在配置初始化、端口监听、外部资源加载阶段立即退出。

先看这张速查卡：复制第一条错误，再执行对应动作

先完全退出客户端并重新启动，只记录启动阶段最早出现的第一条 error、fatal 或 failed。后续错误可能是连锁结果，先处理第一条，再重启验证。

Mihomo的监听器包括代理端口、TUN和其他入站，实际可用性还会受到监听地址、系统路由与防火墙影响。Mihomo Inbound Configuration

第一步：确认是客户端、内核还是代理连接出了问题

1. 客户端完全打不开：先从任务管理器、活动监视器或系统进程列表确认是否有残留进程；重新启动前备份客户端自身配置目录。若仍无法打开，查看客户端自己的日志位置，必要时重新安装同一来源的客户端，不要先删除全部配置。
2. 客户端能打开，但内核状态失败或反复退出：进入客户端的内核日志、运行日志或控制面板日志，复制第一条启动错误，然后执行后文的配置校验。
3. 内核已运行，但网页打不开：这通常已经不属于“内核启动失败”。先确认混合端口或系统代理是否指向当前监听端口，再检查规则、DNS和节点连接。

如果客户端提供控制面板，可通过日志接口查看实时日志；Mihomo API文档列出了日志、当前配置、版本和代理状态等接口。Mihomo APIs

本文是第三方使用指南，不代表任何客户端或内核项目的官方支持；客户端菜单名和日志路径以当前版本界面为准。

第二步：备份配置，并用工作目录校验实际读取的文件

先复制当前 config.yaml、代理集合、规则集合、Geo数据和客户端自定义文件。不要直接清空整个配置目录，因为 Provider缓存、规则文件和客户端状态可能也在其中。

1. 确认实际路径：以客户端设置页、配置管理页、启动命令或服务文件显示的路径为准。不要只检查下载目录里同名的 config.yaml。
2. 确认参数：先运行 mihomo -h，查看当前二进制是否支持 -d、-f 和 -t。-d指定工作目录，配置中 Provider缓存、Geo文件等相对路径会依赖它。
3. 执行校验：Linux/macOS 示例为 mihomo -d /etc/mihomo -f /etc/mihomo/config.yaml -t；Windows 示例为 mihomo.exe -d "C:\mihomo" -f "C:\mihomo\config.yaml" -t。
4. 判断结果：输出包含 test is successful 字样时，表示配置测试通过；如果出现行号、字段名或类型错误，只修改对应位置后再次校验。实际输出可能带配置路径，不能要求逐字一致。

Mihomo服务示例使用工作目录启动，并通过服务日志查看运行结果；命令参数和服务封装仍应以当前二进制帮助信息为准。创建运行服务 Mihomo main.go

第三步：分别处理端口、DNS监听和配置引用错误

1. TCP端口冲突

看到 address already in use 或 bind: listen 时，先从日志确认具体端口。它可能来自 mixed-port、socks-port、external-controller 或其他入站配置。

• Windows：Get-NetTCPConnection -LocalPort 7890 -ErrorAction SilentlyContinue，再用 Get-Process -Id 1234 查看进程。
• macOS：lsof -nP -iTCP:7890 -sTCP:LISTEN，再用 ps -p 1234 -o pid,command 确认命令。
• Linux：sudo ss -ltnp | grep ':7890 ' 或 sudo lsof -nP -iTCP:7890 -sTCP:LISTEN。

确认是无用的旧进程后再结束它；如果不能结束进程，把 mixed-port: 7890 改为未占用端口，例如 17890，并同步检查系统代理和客户端端口设置。

2. DNS的UDP端口冲突

如果配置了 dns.listen: 0.0.0.0:53，冲突可能发生在 UDP，而不是TCP。Windows执行 Get-NetUDPEndpoint -LocalPort 53 -ErrorAction SilentlyContinue；Linux执行 sudo ss -lunp | grep ':53 '；macOS可执行 sudo lsof -nP -iUDP:53。

如果系统DNS服务已占用53端口，不要强行结束系统服务。可以把 Mihomo DNS监听改为未占用端口，例如 127.0.0.1:1053，再按客户端或TUN配置把DNS流量指向新端口。Mihomo DNS文档明确说明 listen 支持UDP和TCP，端口需结合系统环境选择。Mihomo DNS configuration

3. 代理组与规则引用错误

proxy group xxx not found、规则目标不存在或策略组为空，不等同于YAML语法错误。检查规则最后一列、代理组 proxies 列表和实际节点名称，确认大小写、空格和标点完全一致。Mihomo文档将代理组的 proxies 定义为对代理节点或其他代理组的引用。Mihomo Proxy Groups configuration Mihomo Route Rules

第四步：修复 YAML、字段兼容、Geo数据和订阅返回内容

YAML与字段错误

出现 yaml、unmarshal 或 field not found 时，按日志行号检查缩进、冒号、引号、列表符号和字段类型。端口通常应写数字，开关应写 true 或 false。如果字段来自其他客户端、旧配置或不同内核实现，不要只改成相近名称，应对照当前 Mihomo 配置文档逐项确认。Mihomo Configuration

GeoIP、GeoSite、MMDB或ASN加载失败

出现 can't initial GeoIP、MMDB invalid 或类似数据文件错误时，先检查工作目录中对应文件是否存在、大小是否异常，并确认文件没有被下载成HTML错误页。若当前配置依赖远程下载，可使用 geox-url 指定 GeoIP、GeoSite、MMDB 和 ASN 数据地址；具体文件类型和地址以官方文档为准。

geodata-mode: true
geox-url:
  geoip: "https://example.invalid/geoip.dat"
  geosite: "https://example.invalid/geosite.dat"
  mmdb: "https://example.invalid/country.mmdb"
  asn: "https://example.invalid/GeoLite2-ASN.mmdb"

上面使用的是占位地址，不能直接作为下载地址。Mihomo官方配置说明列出了 geox-url、Geo数据模式和自动更新相关字段。Mihomo General configuration

订阅返回的不是合法配置

不要只用浏览器打开订阅地址判断结果。部分服务端可能根据 User-Agent 返回不同内容，建议用客户端相同的 UA 查看响应前几行，例如：

curl -L -A "clash.meta" --max-time 20 "https://example.invalid/subscription" | head -n 20

将示例地址替换为自己的订阅地址，并先脱敏；不要把完整订阅链接、Token或密码发到公开位置。如果返回内容以 <html、登录提示、JSON错误或空内容开头，不要直接保存为 YAML，应回到提供方核实授权、有效期和访问条件。代理集合的 URL、文件和内联内容有不同配置方式，不能把一种格式直接粘贴到另一种入口。Mihomo Proxy-Providers configuration Mihomo Proxy-Providers contents

第五步：用最小配置隔离原配置、TUN和内核文件问题

当原配置包含大量节点、规则集、Provider、DNS和TUN时，先新建临时目录，不覆盖原文件。下面是用于判断核心能否解析和启动的最小示例：

mode: direct
allow-lan: false
mixed-port: 17890
tun:
  enable: false
proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

1. 将内容保存为临时目录中的 config.yaml。
2. 执行 mihomo -d /path/to/test-dir -f /path/to/test-dir/config.yaml -t。
3. 如果校验通过，再执行 mihomo -d /path/to/test-dir -f /path/to/test-dir/config.yaml，确认端口能否监听。
4. 若最小配置正常，按“基础端口→代理集合→规则集合→DNS→TUN”的顺序一次恢复一类配置。
5. 若最小配置也失败，检查二进制架构、执行权限、工作目录、配置路径和安全软件隔离记录。

内核文件不存在、无法执行或架构不匹配时，应从 Mihomo 的启动文档或 Release 页面按系统和 CPU 架构选择文件；当前版本号和资产名称以页面显示为准。Mihomo startup and installation Mihomo Releases

第六步：TUN启动失败与移动端最短路径

Windows

先关闭TUN并启动普通代理。如果普通代理正常，再以管理员身份运行客户端，或在客户端提供的设置中安装、启用 Service Mode 后重新开启TUN；具体入口以当前客户端界面为准。若仍失败，检查 Windows 防火墙是否允许核心程序通过。官方TUN文档给出了 Windows 防火墙放行核心程序的路径。Mihomo Tun configuration

macOS

先关闭TUN验证普通代理，再按客户端提示安装辅助服务或网络扩展。若系统阻止核心执行，检查系统安全提示和防火墙允许列表；Mihomo文档给出了将应用加入防火墙允许列表的处理方向。Mihomo Tun configuration

Linux

确认服务用户能够读取工作目录、访问配置和创建所需网络资源；如果通过 systemd 启动，使用 systemctl status mihomo 和 journalctl -u mihomo -o cat -e 查看服务日志。TUN涉及自动路由、重定向和防火墙，不能只按普通系统代理排查。

Android等移动端

先关闭VPN/TUN模式，确认普通模式或单应用代理是否能启动；再检查系统VPN权限、电池限制、Private DNS和客户端当前内核状态。Android端的TUN封装与桌面端不同，不要直接复制桌面命令。官方文档说明 Android 的DNS劫持还可能受到 Private DNS 设置影响。Mihomo Tun configuration

修复成功的判断标准与安全清单

修复后至少完成三项确认：配置校验输出包含 test is successful 字样；日志不再重复启动错误且目标端口处于监听状态；客户端或控制面板显示内核已运行。只有内核已运行后仍打不开网页，才继续检查系统代理、DNS、规则和节点。

• 备份配置后再改动，不要直接清空整个配置目录。
• 一次只恢复一类配置，避免同时修改端口、DNS、规则和TUN。
• 订阅链接、Token、密码、UUID、控制器密钥和完整日志都要脱敏。
• 配置中的相对路径要配合正确的 -d 工作目录验证。
• 不要把其他客户端的字段直接复制到 Mihomo；字段兼容性需以当前文档核实。

常见问题

Mihomo启动失败时，应该先删除配置文件吗？

不建议。先复制配置文件、Provider、规则集和相关缓存做备份，再读取第一条有效错误。确认某个临时文件损坏后，只处理对应文件，不要直接清空整个配置目录。

mihomo -t 校验通过，为什么客户端仍然启动失败？

配置测试通过只说明配置可以被解析，不代表端口没有冲突、Geo数据可加载、TUN有权限、外部Provider可访问或内核文件可执行。继续检查启动日志、TCP/UDP监听、Geo文件、TUN权限和订阅实际返回内容。

为什么浏览器能打开订阅，Mihomo却提示解析失败？

浏览器得到响应不等于客户端得到相同内容。服务端可能按 User-Agent返回不同结果，响应也可能是登录页、HTML错误页或JSON提示。使用客户端相同的 UA 查看前几行，并对订阅地址和日志脱敏。

proxy group not found 和 YAML语法错误有什么区别？

YAML语法错误通常发生在缩进、冒号、列表或字段类型解析阶段；proxy group not found 属于配置引用错误，表示规则或其他代理组引用了不存在的名称。前者先修语法，后者检查名称和引用关系。

出现 MMDB invalid 或 can't initial GeoIP 怎么办？

先确认 Mihomo 工作目录中的 GeoIP、GeoSite、MMDB或ASN文件是否存在、是否被下载成HTML错误页，再按官方配置文档检查 geodata-mode 和 geox-url。修复数据文件后，再恢复依赖 GEOIP、GEOSITE 或 IP-ASN 的规则。

开启TUN后启动失败，普通代理却能用，怎么办？

先关闭TUN确认故障层级，再检查虚拟网卡、管理员权限、Service Mode、路由和防火墙。Windows、macOS、Linux和Android的权限模型不同，不能直接套用桌面命令。

相关阅读

• 查看 Mihomo 日志
• Mihomo订阅怎么导入客户端
• Mihomo配置文件 YAML 怎么写

参考资料

1. Mihomo Inbound Configuration
2. Mihomo APIs
3. 创建运行服务
4. Mihomo main.go
5. Mihomo DNS configuration
6. Mihomo Proxy Groups configuration
7. Mihomo Route Rules
8. Mihomo Configuration
9. Mihomo General configuration
10. Mihomo Proxy-Providers configuration
11. Mihomo Proxy-Providers contents
12. Mihomo Tun configuration