Mihomo启动失败怎么办?按日志、配置、端口和权限排查
简答:Mihomo启动失败,最先不要重装:先打开客户端或服务日志,找到启动过程中第一条明确的 error,再执行配置校验。通常优先检查配置文件、端口占用、TUN权限和内核文件;如果内核已经启动但网页打不开,则应转到DNS、规则或系统代理排查,而不是继续处理“启动失败”。本文为缥缈墟的第三方使用指南,具体界面和字段请以当前客户端日志及Mihomo官方文档为准。
定义:Mihomo启动失败,是指Mihomo内核进程无法正常加载配置并持续运行,常见表现包括启动后立即退出、客户端一直显示启动中或服务反复重启。
先做这三步:确认现象、查看日志、校验配置
建议先做:记录当前现象和日志,不要立即删除配置或重装客户端。Mihomo本身可以通过配置测试命令检查配置文件,官方生态中的配置编辑流程也明确建议先用 mihomo -t 校验,校验通过后再重启内核。可参考 MetaCubeX Dashboard 文档 与 Mihomo 配置校验示例。
- 在客户端中打开“日志”“内核日志”或“运行日志”,从启动失败的位置向上查看,记录第一条明确的
error、failed、invalid或bind信息。 - 确认是“内核启动失败”,还是“内核已运行但无法联网”。如果日志持续输出运行信息、客户端能显示代理端口或控制面板能打开,通常已经不是启动故障。
- 找到实际配置文件后先复制一份,再运行配置校验。例如在配置文件所在目录打开终端,执行:
mihomo -t -f config.yaml
如果配置文件不叫config.yaml,应替换为客户端日志中显示的实际文件名;不要用新建的空白配置代替正在使用的配置。
预期结果:校验成功后再启动;如果校验直接返回错误,先修复该错误,不要继续排查TUN、DNS或节点连接。若命令提示找不到 mihomo,说明当前终端没有找到内核程序,应改用客户端自带的“检查配置”功能,或在客户端日志中确认内核文件路径。
| 现象 | 优先判断 | 下一步 |
|---|---|---|
| 点击启动后立即退出 | 配置、文件、权限或端口 | 看第一条明确错误并运行配置校验 |
| 一直显示启动中 | 内核卡住、TUN权限或服务通信异常 | 查看日志是否有监听、权限或服务错误 |
| 内核已运行但网页打不开 | DNS、规则、系统代理或节点连接 | 不要继续按启动失败处理,转做联网排查 |
| 只有开启TUN后失败 | TUN权限、网络扩展或路由设置 | 先关闭TUN验证普通代理是否能启动 |
按日志关键词定位:配置、端口、文件还是权限
日志中的第一条明确错误通常比最后一句“启动失败”更有价值。下面按关键词分流,修复后只改一个变量,再重新启动,避免一次改动多个设置导致无法判断结果。
| 日志关键词或现象 | 常见原因 | 处理方法 |
|---|---|---|
yaml、unmarshal、parse config、mapping values | YAML缩进、冒号、引号、字段类型或层级错误 | 恢复最近一份备份,逐项检查缩进;YAML通常使用空格,不要用Tab;再运行 mihomo -t -f config.yaml |
invalid domain、invalid field、unknown field | 字段值格式错误,或当前内核不支持该字段 | 定位具体字段,暂时删除最近新增的覆写项、规则项或协议参数,以当前版本文档为准 |
address already in use、bind、listen tcp | HTTP、SOCKS、Mixed或DNS监听端口被其他程序占用 | 查出占用进程,关闭冲突程序或在配置中改用空闲端口 |
permission denied、operation not permitted | 没有访问配置目录、创建TUN设备或绑定端口的权限 | 检查文件权限;暂时关闭TUN验证;macOS检查网络扩展授权,Linux检查运行用户和TUN设备权限 |
no such file、cannot open | 内核、配置、证书、规则集或Geo文件路径不存在 | 确认客户端配置目录和文件是否仍在,检查安全软件隔离记录,必要时从可信来源重新取得对应文件 |
provider、download、unexpected character、返回HTML | 订阅或Provider地址不可访问,或返回登录页、错误页而非预期内容 | 先用浏览器或命令行确认返回内容,再用本地备份配置启动;不要把HTML保存成YAML继续加载 |
配置中的策略组、代理名称、规则集引用也可能导致启动错误。官方文档说明,监听器中的 proxy 字段必须对应有效的代理或策略组名称;如果你最近修改过名称,优先检查引用是否仍然一致,可参考 Mihomo监听器字段说明。
端口被占用:Windows、macOS和Linux分别检查
Mihomo常见的监听项包括HTTP代理端口、SOCKS端口、Mixed端口和DNS端口。官方配置文档将这些端口分别作为不同入口,具体端口号以你的配置为准,不要默认认为所有客户端都使用相同端口,可参考 Mihomo代理端口文档。
Windows:以配置中的端口号为例,检查7890是否被监听:
Get-NetTCPConnection -LocalPort 7890 -State Listen
如果返回了进程信息,可继续执行:
Get-Process -Id 进程ID
其中“进程ID”必须替换为上一条命令实际返回的数字。若是旧的Mihomo进程占用端口,先回到客户端正常退出;确认进程属于本客户端后,再结束残留进程。
macOS或Linux:检查TCP监听:
lsof -nP -iTCP:7890 -sTCP:LISTEN
检查UDP端口时可执行:
lsof -nP -iUDP:7890
如果查到其他程序占用,优先关闭该程序;如果不能关闭,再把Mihomo配置中的对应端口改成未被占用的端口,并同步更新系统代理或客户端设置。修改后必须重新运行配置校验,再重启内核。
回滚方法:如果改端口后客户端无法连接,恢复原配置文件备份,并把客户端的HTTP、SOCKS或Mixed端口设置改回原值。不要同时修改代理端口、DNS端口和TUN配置,否则很难判断是哪项导致失败。
TUN模式导致启动失败:先关闭验证,再处理权限
如果普通代理可以启动,只有打开TUN后失败,优先把问题限定在TUN,而不是重新导入订阅。Mihomo官方文档说明,TUN用于捕获系统流量、自动路由和DNS劫持;Windows、Linux和macOS对路由、DNS和系统权限的处理并不完全相同,可参考 Mihomo TUN配置文档。
- 关闭TUN,只保留普通HTTP、SOCKS或Mixed代理,启动并确认内核能持续运行。
- 如果关闭TUN后可以启动,检查客户端是否有“以管理员身份运行”“安装服务”“允许网络扩展”或类似授权选项。
- Windows重点看管理员权限、严格路由和安全软件拦截;macOS重点看系统设置中的网络扩展或相关权限;Linux重点看当前用户是否能访问TUN设备,以及服务是否具备创建网络接口所需权限。
- 确认后重新开启TUN,只改一个选项。若仍失败,保留日志中的完整错误,不要直接复制其他系统的TUN配置。
官方文档还说明,TUN的DNS模式和自动路由行为会随系统及选项变化;因此“别人的TUN配置能用”不能证明同一字段在你的系统上也适用。若只是想先恢复连接,可暂时使用普通代理模式,待TUN权限确认后再恢复。
订阅、Provider和DNS错误:区分启动阻塞与启动后故障
订阅或Provider加载失败有两种情况:一是配置加载阶段就因为文件内容错误而阻止内核启动;二是内核已经启动,只是规则集、节点或DNS在运行时加载失败。两者处理顺序不同。
订阅或Provider加载失败
- 先查看日志中请求地址对应的HTTP状态、内容类型或解析错误。
- 如果返回内容是HTML、登录页或错误提示,不要将其当成YAML或JSON配置继续导入。
- 使用最近一次可用的本地配置启动,确认内核本身正常,再单独更新订阅或Provider。
- 更新后再次运行配置校验;如果更新前能启动、更新后不能启动,优先回滚订阅生成的配置,而不是重装内核。
DNS初始化失败
官方DNS文档列出了 listen、nameserver、proxy-server-nameserver和增强模式等配置项。DNS监听地址或端口冲突、nameserver格式错误,都可能使DNS模块初始化失败,可对照 Mihomo DNS配置文档。
- 查看日志是否明确出现DNS监听端口占用、解析器初始化失败或nameserver格式错误。
- 暂时关闭自定义DNS监听或恢复最近一份可用DNS配置,确认内核能否先启动。
- 不要在没有日志依据时随意增加多个DoH、Fallback或代理DNS字段;复杂配置会增加判断分支。
- 如果内核已经启动但只有部分域名打不开,再转向DNS解析、规则匹配和节点连接测试,而不是把它认定为启动失败。
安全软件隔离内核文件与版本字段不匹配
如果日志提示内核文件不存在、无法执行或客户端反复寻找同一个文件,检查操作系统安全软件的隔离区、下载目录和客户端内核路径。先确认文件是否确实属于你主动安装或更新的组件,再决定恢复或重新取得文件;不要把未知来源的可执行文件加入白名单。
如果日志提示未知字段、协议参数不支持或解析错误出现在升级之后,可能是配置使用了当前内核不认识的字段,也可能是客户端和内核组合不匹配。此时应记录客户端版本、内核版本、具体错误字段和配置来源,优先回退到升级前的配置或内核组合,并以当前Mihomo文档和发布说明为准。本文不对未核实的版本兼容关系下结论。
官方发布页会列出不同系统和架构的构建资产;如果确实需要重新取得内核,应先确认操作系统、CPU架构和客户端要求,再核对文件校验信息,不要只按文件名猜测。可从 Mihomo官方发布页核对当前可见的构建信息。
复测、回滚与最小化恢复流程
- 保留证据:保存启动失败日志、当前配置副本和最近一次可用配置,不要覆盖原文件。
- 最小化启动:先关闭TUN、复杂覆写、远程Provider和自定义DNS,只保留能够通过校验的基础配置。
- 逐项恢复:先恢复代理节点,再恢复规则集,再恢复DNS,最后恢复TUN;每次只增加一项并重新启动。
- 确认进程:检查客户端是否持续运行、监听端口是否出现、日志是否继续输出新的启动错误。
- 确认联网:先测试本地代理端口,再测试DNS解析和实际网页请求。内核已运行但网页打不开时,转到规则、DNS或节点连接排查。
建议的回滚顺序:当前配置文件 → 最近一次可用配置 → 关闭TUN → 移除最近新增Provider或覆写 → 恢复端口设置。不要直接删除整个配置目录,因为这样可能丢失可用于定位问题的日志、缓存和备份。
如果使用客户端图形界面,菜单名称可能因平台和版本不同而变化。找不到“日志”“内核管理”或“配置校验”时,以当前客户端界面和Mihomo文档为准;如果你能提供第一条明确错误、操作系统、客户端名称以及是否开启TUN,后续判断会比只描述“启动失败”更准确。
常见问题
Mihomo启动失败,第一步应该重装吗?
不建议。第一步应打开启动日志,找到第一条明确错误,再复制配置并执行 mihomo -t -f config.yaml 校验。只有确认内核文件缺失、损坏或安全软件隔离,才考虑重新取得对应文件;配置问题单纯重装通常不会自动修复。
mihomo -t -f config.yaml 命令无法执行怎么办?
先确认终端能找到mihomo程序。如果提示找不到命令,可改用客户端自带的配置检查功能,或根据日志确认内核文件路径后再执行。配置文件名和路径必须使用当前客户端实际加载的文件,不能用随手新建的空白文件代替。
Mihomo报端口被占用,应该改哪个端口?
先根据日志确定冲突的是HTTP、SOCKS、Mixed还是DNS监听端口,再用Windows的Get-NetTCPConnection或macOS/Linux的lsof确认占用进程。关闭冲突程序通常比盲目改配置更稳;如果必须改端口,还要同步客户端和系统代理设置。
为什么关闭TUN后Mihomo就能启动?
这通常说明基础内核和普通代理入口可以运行,问题集中在TUN创建、系统路由、网络扩展或权限。先保持TUN关闭确认普通代理可用,再按操作系统检查管理员权限、网络扩展授权、TUN设备和路由选项。
Mihomo启动成功但网页打不开,还是启动失败吗?
不一定。只要内核进程持续运行、代理端口已监听,通常应转向DNS、规则、系统代理、节点连接或TUN流量接管排查。可以先确认请求是否进入代理,再根据日志判断是解析失败、规则直连还是远端连接超时。
订阅返回HTML会导致Mihomo无法启动吗?
可能会。如果客户端把HTML错误页、登录页或访问提示保存为配置或Provider文件,后续解析时可能出现YAML、JSON或字段错误。应先确认返回内容,再回滚到本地可用配置,单独处理订阅访问问题。
相关阅读
- 继续看客户端连接、订阅、代理与TUN的分流排查
- 如果内核已启动但DNS异常,查看DNS配置与故障排查
- 如果是开启TUN后无法上网,按权限、路由和DNS排查
- 如果问题发生在订阅导入,查看订阅内容和导入错误处理
- 进入连接问题排查总目录