Mihomo 配置文件错误怎么办？从 YAML 校验到恢复可用配置

更新于 2026-11-04 · jetstream.best

简答：先不要继续覆盖当前配置：复制一份可用配置作为备份，然后查看日志中的第一条明确错误。接着在与客户端相同的 Mihomo 内核环境中执行 mihomo -t -f config.yaml；如果校验通过但仍无法连接，再转向订阅、DNS、规则、端口或 TUN 排查。

定义：Mihomo 配置文件错误，是指配置无法被 YAML 解析、字段或字段类型不符合内核要求、引用对象不存在，或订阅与覆写合并后无法通过 Mihomo 配置校验。

先做这三步：保留旧配置、定位首个错误、执行内核校验

本文是 JetStream VPN 相关客户端的第三方使用指南，不代表任何品牌官网。Mihomo 配置错误不要一上来重装客户端，也不要连续点击“更新订阅”覆盖旧 Profile。先把当前配置文件复制成备份，再读取日志里最早出现的明确错误，最后用实际运行的 Mihomo 内核校验候选文件。

保留可用版本：在客户端的配置、Profiles、订阅或配置目录中，复制当前文件并改名为 config.yaml.bak。具体目录随客户端和系统变化，无法从单一客户端规则推断，优先使用客户端提供的“打开配置目录”或“打开文件夹”功能。
找到第一条错误：不要只看最后一行“内核启动失败”。优先记录包含 Invalid YAML、mapping values、not found、unsupported、401、403、HTML 或 address already in use 的首条具体信息。
校验候选配置：在终端进入配置文件所在目录，执行 mihomo -t -f config.yaml。如果客户端内置的是其他 Mihomo 衍生内核，应改用该客户端实际调用的内核；二进制名称、参数或配置目录不一致时，以当前客户端日志和内置帮助为准。官方面板文档也将 mihomo -t 作为激活配置前的最终校验。

校验通过只代表配置能够被内核解析和检查，不等于节点可用、DNS 正常、规则命中或代理已经接管系统流量。配置通过后仍需启动内核并做一次实际请求测试。

参考：MetaCubeX 官方面板文档、MetaCubeX Mihomo 配置校验讨论。

按报错关键词分流：先修语法，再修引用和兼容性

日志关键词或现象	通常属于哪一层	优先处理方法
`Invalid YAML`、`mapping values`、`did not find expected key`	YAML 语法	检查缩进、冒号、引号、Tab、列表短横线和多行字符串；从报错行向上查看最近一个结构块。
`proxy group not found`、`xxx not found`	名称引用	检查 `proxy-groups`、`rules`、`proxy-providers` 和 `rule-providers` 中的名称是否完全一致，包括大小写、空格和标点。
`unsupported proxy type`、未知字段或字段类型错误	内核兼容性	确认配置面向 Mihomo 而不是其他内核；对照当前官方配置文档核对字段名称、布尔值、数字和列表类型。
`401`、`403`、返回 HTML、空文件	订阅下载	不要把返回内容直接当 YAML。先在浏览器或命令行查看响应类型，确认登录状态、授权和订阅地址，再保留旧 Profile。
配置校验通过但启动后无请求或不能上网	运行阶段	继续检查代理模式、端口、DNS、规则、TUN 权限和节点连接，不要反复修改 YAML 语法。

YAML 语法问题最常见的触发点是混用 Tab 和空格、同一层级缩进不一致、冒号后缺少空格、字符串中的特殊字符未加引号，以及把列表写成了对象。建议每次只修改一个结构块，修改后立即重新校验。

例如，下面两段看起来接近，但第一段的 proxies 是列表，第二段把它写成了字符串，可能导致字段类型错误：

proxy-groups: - name: Proxy type: select proxies: - DIRECT

proxy-groups: - name: Proxy type: select proxies: DIRECT

代理组名称必须引用真实存在的节点或其他代理组。官方文档说明，代理组中的 proxies 用于引用出站代理或其他代理组；规则则按从上到下的顺序匹配，因此目标名称和规则顺序都不能只凭感觉填写。参考：Mihomo 官方 proxy-groups 文档、Mihomo 官方路由规则文档。

YAML 校验失败时，如何逐项修复而不覆盖订阅

复制候选文件：不要直接改订阅下载文件。先复制为临时文件，例如 config-test.yaml，保留原始文件和上一份可用文件。
缩小修改范围：暂时撤销最近新增的 DNS、TUN、规则集、代理组或覆写内容。每次只恢复一个区块，然后重新执行校验。
检查字段类型：true、false、数字、列表和字符串不能随意互换；端口通常应为数字，节点名和带特殊字符的名称建议加引号。
检查引用链：先确认节点或 Provider 存在，再确认代理组引用的名称存在，最后确认规则指向的策略组存在。任何一个名称改过，都要同步检查下游引用。
检查当前内核：如果同一份文件在一个客户端可用、在另一个客户端失败，先不要认定文件本身一定错误。两者可能使用了不同内核版本、不同衍生实现或不同的覆写机制。用报错客户端实际运行的内核进行校验。

官方配置文档将通用配置、入站、DNS、出站代理、代理组和规则分开说明。出现字段不兼容时，应回到对应章节核对，而不是从其他客户端复制一整段配置。比如 DNS 的 nameserver、fallback、proxy-server-nameserver 作用不同，不能只因为名称相似就互换。

参考：Mihomo 官方配置总览、Mihomo 官方 DNS 文档。

订阅更新后报错：区分下载失败、解析失败和合并失败

订阅更新失败不一定是 YAML 错误。可以按下面顺序判断：

下载失败：日志出现 401 或 403，重点检查授权、登录状态、订阅是否过期以及客户端是否使用了错误的订阅地址。
内容不是配置：打开下载结果后看到 HTML、登录页、JSON 错误信息或空内容，说明请求返回的不是预期配置。不要把它保存为新的活动配置。
YAML 无法解析：内容看似是配置，但出现缩进、冒号或引号错误，复制为临时文件后单独校验。
YAML 能解析但 Mihomo 拒绝：可能是字段、协议、代理组名称或规则 Provider 引用不符合当前内核要求。
单独文件能通过，客户端仍失败：检查客户端是否执行了覆写、订阅合并、脚本转换或自动补字段。最终应以合并后的候选配置校验结果为准。

如果客户端支持“更新前备份”“保留旧配置”或“候选配置校验”，建议开启；如果没有，手动复制旧 Profile。恢复时优先重新激活上一份通过校验且曾经可用的配置，再单独处理订阅来源。

配置校验通过但仍无法使用：不要继续改 YAML

如果 mihomo -t 已通过，问题通常已经从“配置文件错误”转移到运行阶段。按现象分流：

内核无法启动：查看是否有 address already in use，检查端口是否被其他程序占用；客户端自动分配端口时，不要直接套用网上的固定端口。
系统代理没有生效：检查客户端的系统代理开关、代理模式和监听端口是否一致。配置文件中的 mixed-port、port 或 socks-port 不是同一个概念。
TUN 无法开启：检查系统权限、虚拟网卡、驱动或安全软件拦截。Mihomo 官方文档将 TUN 归为用于接管系统流量的入站配置，启用 TUN 不等于所有规则和 DNS 已经正确。
域名解析失败：再检查 DNS 的监听地址、上游服务器、fake-ip 设置和端口冲突。不要在尚未确认基础连接的情况下同时更改 DNS、TUN 和规则。
网页能开但部分应用不能：查看规则是否命中、应用是否使用系统代理、是否存在 QUIC/UDP 或应用级代理差异。

官方文档说明，路由规则按从上到下匹配；因此即使配置能启动，规则顺序或策略组名称仍可能导致请求走错出口。先用一个简单的测试目标验证代理和 DNS，再逐步恢复复杂规则。

参考：Mihomo 官方入站与 TUN 文档、Mihomo 官方通用配置文档。

Windows、macOS、Linux 和图形客户端的安全恢复流程

环境	建议先做什么	不要直接做什么
Windows	从客户端打开配置目录，复制 Profile；在 PowerShell 或终端用实际 Mihomo 可执行文件校验。	不要把系统代理端口、客户端控制端口和内核监听端口混为一谈。
macOS	先保存配置副本，再检查客户端日志和系统权限；如涉及 TUN，确认系统授权状态。	不要直接删除应用数据目录，避免同时丢失配置、缓存和日志。
Linux	确认配置路径、运行用户和文件权限；用服务实际调用的 Mihomo 二进制执行测试。	不要只运行一个不同版本的 mihomo 来替代服务内核。
图形客户端	优先使用“打开配置目录”“查看日志”“复制配置”“切换 Profile”等内置入口。	不要把某一个客户端的菜单名称当成所有客户端都相同。

恢复完成后，按“配置通过—内核启动—监听端口存在—代理请求成功—目标应用正常”的顺序复测。每一步都正常，再恢复下一项高级配置。这样可以把语法问题、内核问题、端口问题和网络问题分开。

安全提醒：订阅链接、节点密码、控制器密钥和带认证信息的配置都属于敏感内容。提交日志或截图前，应遮住 URL 参数、用户名、密码、UUID、密钥和控制器 Secret。

最后的复测与回滚清单

候选配置已另存，旧配置仍可找到。
mihomo -t -f config.yaml 使用的是实际运行环境中的内核。
校验日志没有新的语法、字段或引用错误。
客户端启动后，监听端口没有冲突。
先测试一个简单请求，再测试 DNS、规则和目标应用。
如果修改后问题扩大，立即停用候选配置，恢复备份文件或上一份可用 Profile。

如果日志只显示“启动失败”而没有具体原因，优先提高日志级别、查看内核标准输出或客户端的 Kernel/Core 日志；不要只看网页面板中的状态文字。若涉及某个具体版本的新字段，先查看 Mihomo 官方发布记录和对应配置文档，当前版本行为未核实前不要照搬旧教程。

常见问题

Mihomo 配置文件报错，应该先重装客户端吗？

通常不应先重装。先备份当前配置、查看第一条明确错误，并用实际运行的 Mihomo 内核执行配置校验。只有在配置通过、端口和权限也正常后，才考虑客户端本身的问题。

mihomo -t -f config.yaml 校验通过，就代表可以正常上网吗？

不代表。该测试主要确认配置能够被内核读取和校验；节点连接、DNS、规则命中、系统代理、TUN 权限和端口占用仍需单独复测。

为什么 YAML 看起来没有问题，Mihomo 仍然提示配置错误？

可能是字段名称、字段类型、代理组引用、规则 Provider、协议类型或覆写合并结果不符合当前内核要求。YAML 能解析与 Mihomo 语义校验通过是两个不同阶段。

订阅更新后出现 Invalid YAML，如何恢复？

先停止继续更新，保留上一份可用 Profile；把本次下载内容保存为临时文件，确认它不是 HTML、登录页、JSON 错误或空内容，再单独执行校验。候选文件通过后再激活。

proxy group not found 怎么修复？

检查代理组的 proxies、use、rules 目标和 Provider 名称是否完全一致。名称中的大小写、空格、标点和引号都可能影响引用；删除或重命名对象后，要同步修改所有引用位置。

配置校验通过但客户端仍然无法启动怎么办？

查看运行阶段日志，重点排查端口占用、TUN 权限、文件权限、内核版本差异和客户端覆写。不要继续修改已经通过校验的 YAML，先把故障范围从配置层转到运行层。