← 返回 naixinternet.shop 本地视觉备份 首页

Mihomo报错怎么排查？按日志原文定位问题

更新于 2026-11-01 · naixinternet.shop

简答：先看日志最后一行，再按“配置解析→端口监听→DNS与订阅→代理请求→Dashboard”顺序排查。最先备份配置，并用当前 Mihomo 构建支持的 `mihomo -t -f 配置文件` 校验；校验通过后，再检查端口、域名解析和实际代理请求。

定义：Mihomo 报错是内核、配置文件、监听端口、DNS、订阅内容、节点协议或控制面板之间某一层没有正常工作的提示，不能只凭“无法上网”判断原因。

先做这 4 步：避免把不同问题混在一起

本文是 naixinternet.shop 的第三方使用指南，不代表任何客户端或服务的官方页面。处理 Mihomo 报错时，先不要反复点击重启，也不要直接覆盖原配置。按下面顺序操作，通常能先判断问题属于“核心没有启动”，还是“核心已启动但请求失败”。

  1. 备份配置：复制当前 YAML 文件，并保留原文件名、运行目录和订阅来源。不要把订阅链接、节点密码、Controller secret 或完整配置公开到论坛和聊天群。
  2. 查看最后一条错误：优先记录内核启动日志或进程标准输出；如果只是 Dashboard 打不开，还要分别查看内核日志和面板连接日志。官方 Dashboard 文档明确区分了内核进程日志与 Clash API 日志，二者不能互相替代。参考：MetaCubeX Dashboard README
  3. 校验配置：在当前 Mihomo 可执行文件所在目录运行 mihomo -t -f config.yaml；如果你的构建参数不同，先运行 mihomo -h 或查看对应发行版说明。该测试模式用于校验配置并退出，Dashboard 的配置激活流程也会先执行类似校验。参考：配置激活与 mihomo -t
  4. 记录可观察结果：分别记下“校验是否通过、进程是否存在、监听端口是否存在、代理请求返回什么、Dashboard 是否能连接 API”。不要把一次能打开网页当成长期稳定结论。
现象优先判断先做什么
启动后立即退出YAML、字段类型、路径或权限备份后执行配置测试，查看最后一行错误
提示 address already in use端口被其他进程占用或重复启动检查进程与监听端口，停止重复实例或更换端口
提示 connection refused目标端口没有服务监听确认核心已运行、地址和端口对应正确
提示 no such host 或 DNS resolve failed域名解析、网络或订阅地址问题区分节点域名、订阅域名和目标网站后分别测试
Dashboard 无法连接Controller 地址、端口、secret 或跨域设置先直接确认 API 地址能访问，再检查 secret 与 CORS

YAML 配置报错：先处理缩进、Tab和字段类型

如果日志包含 yaml、parse config、cannot unmarshal、invalid 或类似“配置解析失败”的信息，问题还没有进入节点连接阶段。Mihomo 使用 YAML 配置；YAML 对大小写敏感，并使用缩进表达层级，缩进不能使用 Tab，只能使用空格。参考：Mihomo YAML 语法文档

  1. 用支持显示空白字符的编辑器打开配置，搜索 Tab 并替换为空格。
  2. 检查冒号后是否有空格，列表项是否统一使用短横线，嵌套字段是否保持同级左对齐。
  3. 检查引号是否成对，域名、路径、端口和布尔值是否写成当前版本支持的类型。
  4. 检查策略组、代理组、规则集引用的名称是否与实际定义完全一致，包括大小写和标点。
  5. 删除最近新增的字段或订阅片段，恢复到上一次能启动的备份，再逐段添加并重新测试。

不要只看“校验通过”。配置测试通过表示结构和字段检查没有阻止启动，但不等于节点一定可用、DNS 一定正常或所有规则都符合预期。每次只改一个字段，并在修改前保留备份，便于回滚。

address already in use：端口冲突和重复启动

这个错误表示 Mihomo 想监听的地址和端口已经被其他进程占用。常见原因包括旧进程没有退出、同一个配置被启动两次、多个配置使用同一个 mixed-port 或 external-controller 端口，也可能是容器端口映射重复。

  1. 先确认 Mihomo 是否已经在运行。如果已经有一个正常进程，不要再次启动第二个实例。
  2. 检查配置中的代理端口、DNS 监听端口和 external-controller 端口，确认它们没有重复。
  3. Windows 可使用系统的端口和进程查看工具；macOS、Linux 可用系统自带的监听端口查看命令。命令参数会随系统版本变化，先用当前系统帮助核对，再定位占用端口的进程。
  4. 如果确认是残留进程，先正常停止；无法停止时再结束该进程，并重新启动单一实例。
  5. 如果必须换端口，同时修改客户端代理设置、Dashboard API 地址、容器映射和测试命令，避免只改一处。

修复后的可观察结果应是：旧实例已停止或只保留一个实例，目标端口重新出现监听，内核日志不再重复报告端口冲突。不要用“换成一个没被占用的数字”代替检查，因为 Dashboard、系统代理和容器映射可能仍指向旧端口。

connection refused：先确认服务是否真的在监听

connection refused 通常不是“节点速度慢”，而是请求到达了某个地址，但该地址对应的端口没有服务接受连接。它可能出现在代理测试、Dashboard 连接或订阅下载中。

no such host、DNS resolve failed：先分清是哪一个域名

DNS 类错误至少要分成三类：订阅地址无法解析、节点服务器域名无法解析、目标网站域名无法解析。三者的解决方向不同，不能一律修改 DNS。

  1. 把日志中的域名记录下来，标注它属于订阅域名、节点域名还是目标站点。
  2. 在不经过 Mihomo 的情况下，用系统 DNS 查询该域名；再在 Mihomo 已启动后，用代理路径测试同一域名。
  3. 如果只有订阅域名失败，先检查链接是否过期、返回内容是否为 HTML 登录页、是否需要鉴权，以及当前网络是否能访问该地址。
  4. 如果只有节点域名失败，检查节点信息是否过期、域名是否拼写错误，或服务端是否要求特定协议字段。不要把节点域名失败直接归因于本机 DNS。
  5. 如果目标网站失败而其他域名正常，检查规则命中、代理组选择和目标站点本身的连接结果。

修改 DNS 后要重新测试并记录结果。DNS 配置字段和可用选项可能因 Mihomo 构建变化，不能从其他客户端复制整段配置后直接使用；先对照当前版本文档，再逐项启用。

订阅更新失败与 unsupported proxy type

订阅更新失败时，先把“下载失败”和“下载成功但解析失败”分开。用浏览器直接打开订阅链接看到 HTML 页面，不代表它是有效配置；同样，HTTP 请求成功也不代表返回内容包含当前 Mihomo 能识别的代理节点。

如果只是需要处理订阅导入，可参考本站的 Mihomo 订阅导入与节点不显示排查，不要在同一次排障中同时修改 DNS、TUN、规则和端口。

浏览器不能联网：检查系统代理、应用代理和 TUN

如果 Mihomo 核心运行正常，但浏览器或某个应用没有走代理，先不要继续修改节点。检查应用是否使用系统代理、是否单独配置了代理、是否启用了 TUN，以及测试请求实际使用的是哪个端口。

  1. 先用一个明确指定本地代理端口的请求测试，确认代理端口能返回结果。
  2. 再检查系统代理开关和 HTTP、HTTPS、SOCKS 端口是否与配置一致。
  3. 如果只有某个应用失败，检查该应用是否绕过系统代理、启用了自己的安全 DNS，或不支持当前代理类型。
  4. 如果启用 TUN 后出现全局断网，先关闭 TUN 回到系统代理模式，确认普通代理可用后，再检查 TUN 权限、虚拟网卡、路由和 DNS 劫持设置。
  5. 恢复时一次只打开一个功能，并在每次变更后记录 DNS 查询、代理请求和规则命中结果。

TUN 是高级配置。官方 Dashboard 文档指出，容器环境启用 TUN 需要相应的网络权限、设备和运行模式；缺少这些条件时，内核可能无法正常建立隧道。参考：TUN 运行条件说明

Dashboard 无法连接后端：检查地址、secret与跨域

Dashboard 打不开或显示连接失败，不一定代表 Mihomo 内核停止。先直接检查 external-controller 是否监听，再确认面板填写的 URL、端口和 secret 与配置完全一致。

  1. 确认核心进程存在，并确认 external-controller 的监听地址和端口。
  2. 如果 Controller 只绑定在 127.0.0.1，远程设备通常无法连接；如果绑定到局域网地址，则应同时限制访问范围并设置强 secret。
  3. 如果面板和 API 使用不同来源，检查 external-controller-cors 是否允许面板的准确来源，不要为了省事直接扩大到所有来源。
  4. 确认没有把 Dashboard 的控制接口地址误填到 Mihomo Clash API 地址中，也不要把 secret 放入公开截图。
  5. 如果仍失败，暂时使用本机访问、最小配置和单一面板测试，排除反向代理、浏览器缓存和防火墙因素。

官方配置文档说明，external-controller 是 REST API 监听地址，secret 用于 API 访问控制；绑定到所有网络接口前应配合访问限制。参考：Mihomo 外部控制与 API 配置

修复后的验收与回滚清单

排障完成后，至少完成以下四项验收：

需要注意的是，配置测试通过不等于节点、DNS、规则和上游服务都可用。若错误只在某个节点或某个目标域名出现，应保留最小复现信息：系统、Mihomo 构建、配置中相关字段、日志最后几行、测试端口和时间；删除订阅链接、密码、secret 与完整节点信息后再寻求帮助。

常见问题

Mihomo 报 YAML 错误，最先检查什么？

先检查缩进是否使用 Tab、冒号和引号是否完整、字段类型是否正确，再用当前构建支持的 mihomo -t 校验。不要直接从其他客户端复制整段配置。

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

配置测试主要验证配置能否被解析和启动，不代表节点、DNS、规则或目标网站一定可用。下一步应检查端口监听、代理请求、DNS 查询和实际规则命中。

address already in use 怎么解决？

先确认是否已经有一个 Mihomo 实例运行，再定位占用代理端口、DNS 端口或 external-controller 端口的进程。停止重复实例或同步修改端口及所有客户端引用。

Mihomo 出现 connection refused 是节点坏了吗？

不一定。它首先表示请求目标端口没有接受连接，可能是核心未启动、地址或端口填错、容器映射错误，也可能是上游节点拒绝连接，需要先区分本地端口与节点连接。

订阅更新失败但浏览器能打开链接，为什么？

浏览器能打开只代表收到内容，不代表内容是有效订阅。检查响应是否为 HTML 登录页、鉴权错误、过期提示或不兼容格式，并将更新前配置保留为回滚版本。

Dashboard 无法连接时应改代理端口吗？

通常不应先改代理端口。先确认 Dashboard 使用的是 Mihomo 的 external-controller 地址，并核对监听地址、端口、secret 和跨域设置。

相关阅读

参考资料

  1. Mihomo YAML 语法文档
  2. MetaCubeX Dashboard README：配置校验、Controller、TUN与日志说明
  3. Mihomo 外部控制、API与外部界面配置文档