Mihomo 连接不上怎么办？按日志、DNS 和 TUN 排查
简答：先关闭 TUN 和系统代理，只保留 Mihomo 的普通代理端口测试；如果仍然失败，再看日志区分是内核、节点、DNS 还是订阅问题。面板打不开先查内核和端口，节点全超时先查节点与时间，网页打不开但节点有流量则重点查代理模式、DNS 和应用是否跟随系统代理。
定义：Mihomo 连接失败，是指内核未启动、代理端口不可用、节点建立连接失败、DNS 无法解析，或流量没有被系统代理与 TUN 正确接管中的一种或多种情况。
先做这一步：关闭 TUN，确认普通代理是否能用
不要一开始就同时修改 DNS、规则和 TUN。先备份当前配置，然后暂时关闭 TUN、系统中其他 VPN 或代理软件，只保留 Mihomo 的 HTTP、SOCKS 或 mixed-port。选择一个节点和明确的代理组，使用浏览器访问一个普通网页进行测试。
| 现象 | 优先检查 | 第一步动作 | 复测结果 |
|---|---|---|---|
| 面板或内核状态打不开 | 内核是否启动、Controller 地址、端口占用 | 查看启动日志，确认 external-controller 与实际面板地址一致 | 能打开面板并看到运行状态 |
| 所有节点都超时 | 时间、网络、节点参数、代理组选择 | 换一个节点和网络，观察日志中的 timeout 或 handshake 信息 | 至少一个节点能建立连接 |
| 节点显示可用但网页打不开 | 模式、系统代理、DNS、应用是否走代理 | 切到全局或明确代理模式，再测试浏览器 | 网页请求出现在日志或连接列表 |
| 开启 TUN 后整机断网 | 权限、路由、dns-hijack、防火墙和其他 VPN | 关闭 TUN 恢复网络，再逐项开启 | 普通代理先可用，TUN 再单独验证 |
| 只有一个 App 失败 | App 是否跟随系统代理、是否使用独立 DNS | 先用浏览器对照，再查看该 App 的代理设置 | 确认是单应用问题而非全局连接问题 |
官方配置文档将 TUN 的自动路由、自动检测出口网卡、DNS 模式和防火墙行为分开说明；因此，普通代理可用而 TUN 不可用时，不要直接判断节点失效，应优先检查流量接管链路。可参考 Mihomo 官方 TUN 配置说明。
按日志关键词定位：先确认是哪一层出错
把日志级别临时调到能看到连接过程的级别，复现一次失败，再恢复到日常使用的级别。日志中不要发布订阅地址、密码、节点 UUID、私钥或完整身份信息；分享前只保留时间、错误类型、目标域名是否脱敏和平台信息。
- connection refused：通常表示目标端口拒绝连接，先检查代理端口、节点端口、服务是否监听，以及是否被防火墙拦截。
- address already in use：表示本机监听端口冲突。退出其他代理软件，或在配置中改用一个未被占用的端口，保存后重载配置。
- i/o timeout、context deadline exceeded：先换节点和网络对照；若只有一个节点失败，优先按单节点问题处理，若全部节点失败，再查本地网络、系统时间和配置。
- no such host、dns resolve failed：先判断是节点域名解析失败，还是访问网站域名失败。节点域名失败时应检查 proxy-server-nameserver 或节点参数；网站域名失败时再检查 nameserver、nameserver-policy 和 Fake-IP。
- permission denied：重点检查 TUN 所需权限、防火墙授权、Android VPN 权限或 Linux 网络能力，不要仅靠重启反复尝试。
Mihomo 官方 API 提供 /version、/configs、/logs、/cache/dns/flush 和 /cache/fakeip/flush 等接口，可用于确认内核版本、读取运行配置、查看实时日志和清理缓存。接口地址与密钥必须使用你本机配置中的值，不能照抄他人的地址。详见 Mihomo 官方 API 文档。
如果已启用本机 Controller，可按实际地址执行只读检查：
curl -H "Authorization: Bearer YOUR_SECRET" http://127.0.0.1:YOUR_CONTROLLER_PORT/versioncurl -H "Authorization: Bearer YOUR_SECRET" http://127.0.0.1:YOUR_CONTROLLER_PORT/configscurl -H "Authorization: Bearer YOUR_SECRET" "http://127.0.0.1:YOUR_CONTROLLER_PORT/logs?level=error"
其中 YOUR_SECRET、YOUR_CONTROLLER_PORT 只是占位符。若你没有启用 external-controller，就不要执行这些命令；先通过客户端面板或启动日志查看实际入口。
节点、代理组和模式：区分单节点故障与全局故障
先确认配置中确实存在节点，并且代理组不是停留在 DIRECT、REJECT 或一个已经失效的固定节点上。切换到明确的代理节点后，观察连接列表是否出现请求记录。
- 只测试一个节点，记录是否为超时、拒绝、TLS 握手失败或认证失败。
- 再测试第二个节点。如果只有一个节点失败，不要马上修改全局 DNS 或 TUN。
- 将规则模式临时切换为全局或明确代理模式。若全局模式可用、规则模式不可用，重点检查规则集、域名匹配和代理组选择。
- 如果所有节点都失败，使用另一条本地网络复测，并检查系统时间、IPv4/IPv6、多网卡和其他代理软件。
订阅导入成功不等于节点参数一定可用；配置文件能被读取，也不等于远端节点当前可建立连接。排查时应分别记录“订阅是否更新成功”“节点是否出现在列表”“节点测速是否有响应”“实际网页是否能打开”，避免把四个结果混为一个“连接正常”。
DNS 报错怎么处理：先恢复最小配置，再逐项增加
DNS 设置过于复杂时，建议先备份配置，暂时关闭不必要的策略和自定义规则，只保留一组可验证的 nameserver，并确认配置格式能通过检查。官方 DNS 文档说明了 enable、default-nameserver、nameserver、proxy-server-nameserver、nameserver-policy、enhanced-mode 和 Fake-IP 等字段的用途，修改时应以当前文档和客户端实际支持情况为准，不能把其他客户端的字段直接复制过来。参考 Mihomo 官方 DNS 配置文档。
- 节点域名无法解析：优先检查 proxy-server-nameserver，以及节点地址、SNI 或配置中的域名拼写。
- 网站域名无法解析：检查 nameserver、nameserver-policy 和当前规则模式。
- 开启 Fake-IP 后部分 App 异常：先清理 Fake-IP 与 DNS 缓存，或临时回退到较简单的 DNS 模式进行对照。
- DNS 反复失败：关闭 TUN 后测试普通代理；如果普通代理也失败，不要把问题归因于 dns-hijack。
清理缓存后必须重新访问同一目标进行复测。若清缓存后短暂恢复，记录原始日志和配置差异，再判断是缓存、规则还是上游 DNS 问题，不要连续重复清缓存而不保留证据。
TUN 开启后断网：按权限、路由、DNS、冲突顺序回滚
TUN 会改变系统流量的转发路径。官方文档指出，auto-route、auto-detect-interface、dns-mode、dns-hijack 和 strict-route 在不同平台上的关系并不完全相同；Windows、macOS、Linux 和 Android 的权限及防火墙表现也不同。因此，TUN 必须在普通代理已经可用后单独验证。
- 回滚：关闭 TUN，退出其他 VPN、代理接管工具和网络过滤软件，确认系统网络恢复。
- 检查权限：Windows 查看防火墙是否允许 Mihomo 内核；macOS 查看网络或防火墙授权；Linux 检查 TUN 设备和网络权限；Android 确认 VPN 权限没有被系统回收。
- 检查路由：多网卡、虚拟网卡、公司网络和热点切换可能让自动检测出口失败。存在多个出口时，按官方字段说明核对 auto-detect-interface 或 interface-name。
- 检查 DNS 接管：如果日志出现 DNS 循环、解析超时或系统 DNS 无响应，先关闭 dns-hijack 或回退为普通代理进行对照。
- 逐项复测：每次只改一个字段，分别测试浏览器、DNS 解析和一个实际应用，确认是哪一步导致断网。
如果使用带 TUN 辅助组件的桌面面板，正常退出通常比强制结束进程更容易恢复路由；官方面板说明也建议在 TUN 导致网络异常时使用恢复网络功能或正常退出应用。参考 MetaCubeXD 官方说明。
Windows、macOS、Linux、Android 的最短检查路径
| 平台 | 先检查 | 再检查 | 回滚方法 |
|---|---|---|---|
| Windows | 系统代理是否被其他软件覆盖，内核是否被防火墙拦截 | 关闭 TUN，测试 mixed-port，再检查虚拟网卡与 DNS | 关闭 TUN 和系统代理，重新打开网络设置 |
| macOS | 应用权限、utun 接口和系统代理状态 | 检查其他 VPN、网络过滤器和 DNS 接管 | 正常退出客户端，确认系统代理恢复 |
| Linux | TUN 设备、用户权限、iptables/nftables 和端口监听 | 检查多网卡、auto-route、auto-redirect 与防火墙 | 关闭 TUN，撤销本次新增路由或防火墙规则 |
| Android | VPN 权限、电池优化、后台限制和应用代理设置 | 区分全局 VPN 失败与单个 App 不跟随代理 | 停止 VPN，关闭后台限制冲突后重新授权 |
平台菜单名称会随客户端外壳和版本变化，无法确认时以当前客户端显示为准。官方发布页可用于核对内核版本和对应平台资源，但不要因为版本号较新就直接断定能解决你的连接问题；应先记录当前版本、平台架构和错误日志，再决定是否升级或回退。参考 Mihomo 官方发布页。
复测与回滚：确认修复是否真的生效
- 恢复一个最小配置，只保留已确认能工作的节点、代理组和普通代理端口。
- 先测浏览器，再测出现问题的 App；两者结果不同，说明应用代理接管方式可能不同。
- 开启 DNS 自定义配置后复测一次，开启 TUN 后再复测一次，每次只改变一个变量。
- 记录节点、模式、DNS、TUN、网络类型和日志关键词，避免下次重复试错。
- 如果修改后断网，立即关闭 TUN、恢复备份配置，并撤销新增的系统代理、路由或防火墙规则。
能够复现、定位并回滚，比“换节点后暂时能用”更接近真正解决。若需要提交问题，至少准备平台、架构、客户端外壳、Mihomo 版本、错误原文和脱敏后的最小配置；不要提交订阅链接、密钥或身份凭据。
常见问题
Mihomo 显示已启动，但所有节点都连不上怎么办？
先关闭 TUN 和其他 VPN，切换两个节点并用另一条本地网络复测；同时查看日志是 timeout、connection refused 还是 DNS 解析失败。若所有节点、所有网络都失败，再检查订阅更新结果、系统时间、节点参数和当前配置，而不是只反复清 DNS 缓存。
Mihomo 开启 TUN 后没有网络，如何恢复？
先关闭 TUN并正常退出客户端，确认系统代理和网络恢复；然后检查 TUN 权限、防火墙、自动路由、出口网卡、dns-hijack 以及其他 VPN 冲突。普通代理端口确认可用后，再单独开启 TUN，每次只修改一个选项。
为什么 Mihomo 节点测速有响应，但网页仍然打不开？
测速结果不能代替实际业务验证。先确认当前代理组不是 DIRECT，切换到全局或明确代理模式，再查看连接列表和日志；如果浏览器能打开而某个 App 不行，应检查该 App 是否跟随系统代理、是否使用独立 DNS 或需要 TUN 接管。
出现 no such host 或 dns resolve failed 应该改哪一项？
先区分失败的是节点域名还是目标网站域名。节点域名失败优先检查 proxy-server-nameserver、节点地址和 SNI；目标网站失败再检查 nameserver、nameserver-policy、Fake-IP 与 DNS 缓存。改动前备份配置，并使用官方 DNS 字段说明逐项核对。
Mihomo 连接问题需要升级版本吗？
不能仅凭连接失败就判断需要升级。先记录当前版本、平台架构、配置检查结果和日志关键词，再到官方发布页核对可用资源；升级前保留旧版本和配置，升级后若问题出现，按同一节点、同一网络和同一模式复测，必要时回滚。