Mihomo 配置模板无法启动？先替换订阅并校验 YAML
简答：先使用 Lite 模板，只替换 proxy-providers.main.url 中的订阅地址；保存后用 mihomo -t 校验，再按策略组、DNS、端口和 TUN 顺序排查。
定义：Mihomo 配置模板是用 YAML 编写的基础配置文件，用来定义代理端口、订阅提供者、策略组、DNS、规则以及可选的 TUN 入站。
先选模板：普通代理不要一开始就开启 TUN
本文与 Mihomo 项目及开发者无隶属关系。下面的示例只使用占位符，不包含真实节点、真实订阅地址或密钥；其中 https://example.com/SUBSCRIPTION_URL 必须替换为你的实际订阅地址。Mihomo 官方文档将固定代理端口、TUN 和 listeners 作为不同的入站配置方式，因此新用户应先从普通代理端口开始，确认配置能加载后，再按需要启用 TUN。可参考 Mihomo 入站配置文档。
| 模板 | 适合场景 | 默认内容 | 优先检查 |
|---|---|---|---|
| Lite | 桌面端、浏览器或低内存设备 | 混合端口、订阅提供者、手动策略组、兜底规则 | 订阅地址、端口和策略组引用 |
| 标准 | 希望自动选择可用节点 | 在 Lite 基础上增加 url-test 与 fallback | 订阅是否能返回节点、测速地址是否可访问 |
| TUN/DNS | 需要接管系统流量或软路由转发 | DNS、Fake-IP、TUN 路由和 DNS 劫持 | 权限、DNS 端口、路由和防火墙 |
| OpenClash 或其他兼容前端 | 使用 Mihomo 内核的管理界面 | 以客户端实际支持的字段为准 | 内核版本、字段支持和前端导入方式 |
上表中的 Lite、标准和 TUN 是本文按复杂度划分的使用模板，不是 Mihomo 官方发布的版本名称。OpenClash、Docker、软路由或桌面客户端是否完整支持某个字段，本文未逐一核实，遇到字段未知时应以当前内核和客户端配置说明为准。
Lite 模板：先验证订阅、端口和策略组
如果你只是想让支持代理设置的浏览器或应用连接，先复制下面的 Lite 模板。保存为 config.yaml，只替换 proxy-providers.main.url 的示例地址。proxy-providers 的 HTTP 类型需要填写 URL，路径应保持唯一；字段定义可查看 Mihomo Proxy Providers 配置文档。
mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false
proxy-providers:
main:
type: http
url: "https://example.com/SUBSCRIPTION_URL"
path: ./providers/main.yaml
interval: 86400
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 300
timeout: 5000
lazy: true
proxy-groups:
- name: PROXY
type: select
use:
- main
proxies:
- DIRECT
rules:
- MATCH,PROXY替换时不要删除引号，也不要把 main 改成其他名称，除非你同时修改 proxy-groups.use 中的引用。这个模板的判定标准是：配置可以通过当前 Mihomo 内核的校验，启动后能看到 PROXY 策略组，并且提供者能更新出节点。若策略组为空，先检查订阅返回的内容是否是当前内核能识别的节点格式。
安全默认值说明：allow-lan: false 和 bind-address: 127.0.0.1 让代理端口默认只监听本机。只有在明确需要局域网设备接入时，才考虑修改监听范围，并同步检查系统防火墙和路由；入站是否能从网络访问，取决于监听地址、系统路由和防火墙设置，而不只是配置中的协议名称，可参考 Mihomo 入站配置说明。
标准模板：自动测速与故障转移怎么写
如果 Lite 模板已经能加载，但你希望在多个节点之间手动选择、自动测试或故障切换，可以使用下面的标准模板。url-test 和 fallback 只负责根据健康检查结果选择或切换，不代表线路一定更快，也不等于对实际业务的速度保证。
mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false
proxy-providers:
main:
type: http
url: "https://example.com/SUBSCRIPTION_URL"
path: ./providers/main.yaml
interval: 86400
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 300
timeout: 5000
lazy: true
proxy-groups:
- name: AUTO
type: url-test
use:
- main
url: https://www.gstatic.com/generate_204
interval: 300
tolerance: 50
- name: FAILOVER
type: fallback
use:
- main
url: https://www.gstatic.com/generate_204
interval: 300
- name: PROXY
type: select
proxies:
- AUTO
- FAILOVER
- DIRECT
rules:
- MATCH,PROXY建议按这个顺序验证：先选择 AUTO，观察是否能得到节点结果；再选择 FAILOVER，观察节点不可用时是否切换；最后根据实际连接稳定性保留合适的策略组。Mihomo 官方文档说明，提供者健康检查可以设置测试 URL、间隔、超时时间和延迟检测；如果测速为空，先确认提供者已成功更新，再确认测试地址和本地网络可访问，可参考 Proxy Providers 配置说明。
不要把不存在的节点名称直接写进 proxies。使用 use 时，值必须对应一个已经定义的提供者名称；使用 proxies 时，值应是实际存在的节点名、其他策略组或 DIRECT。最后一条 MATCH,PROXY 只引用本模板中确实存在的 PROXY 组。
DNS 与 TUN 模板：确认需求后再启用
TUN 适合需要接管系统流量、处理不支持代理设置的程序，或用于软路由转发。它会同时涉及系统权限、路由、DNS 监听和防火墙，因此不要把 TUN 直接叠加到一个尚未验证的配置上。Mihomo 官方文档列出 TUN 的 stack、auto-route、auto-detect-interface、dns-hijack 和 strict-route 等字段；普通用户可以先使用较少的字段，出现问题后逐项增加，可参考 Mihomo TUN 配置文档。
dns:
enable: true
ipv6: false
enhanced-mode: fake-ip
fake-ip-filter:
- "*.lan"
- "*.local"
nameserver:
- https://1.1.1.1/dns-query
- https://8.8.8.8/dns-query
proxy-server-nameserver:
- 223.5.5.5
- 1.1.1.1
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53这段只适合作为配置结构示例，不能保证在所有系统或前端中直接运行。DNS 官方字段包括 fake-ip 和 redir-host 两种增强模式；如果启用 Fake-IP 后出现局域网访问异常，可先保留 DNS 基础设置，临时改用 redir-host 或关闭 TUN，确认问题是否由 Fake-IP 和路由组合引起，具体字段可查看 Mihomo DNS 配置文档。
排查 TUN 时，先看三项：第一，系统是否允许核心程序创建 TUN；第二，DNS 监听端口是否被其他程序占用；第三，系统路由是否出现指向 TUN 的路径。官方文档明确指出，Windows 和 macOS 不能自动劫持发往局域网的 DNS 请求，Android 开启 Private DNS 时也可能无法自动劫持；因此遇到“网页打不开但普通代理正常”，先关闭 TUN，若恢复连接，再检查 DNS 劫持和系统路由。
替换、校验和启动：一套可照做的顺序
- 先复制原配置文件，保留一个能恢复的备份；备份文件不要和当前配置使用相同文件名。
- 在
proxy-providers.main.url中，将示例域名和路径替换为实际订阅地址。订阅地址属于敏感信息，不要贴到公开 Issue、群聊或截图中。 - 确认 YAML 使用空格缩进，不要使用 Tab；同一层级字段必须保持一致的缩进。
- 先用当前 Mihomo 可执行文件测试配置，再启动或激活配置。官方 MetaCubeX Dashboard 的配置编辑流程会在激活前调用
mihomo -t，并在校验通过后才重启内核，可参考 MetaCubeX Dashboard 配置编辑说明。
mihomo -t -f ./config.yaml这条命令的目的，是用当前可执行文件检查配置结构。正常判定是命令返回成功，并显示配置测试成功；如果系统提示找不到命令，把 mihomo 换成可执行文件的完整路径。如果你的配置依赖数据目录，再使用对应目录参数：
mihomo -t -d ./mihomo-data -f ./config.yaml若当前客户端没有独立命令行入口，应在客户端的配置编辑或激活界面执行校验，不能把第三方前端的按钮名称当成所有客户端都相同。校验通过只说明配置能被当前内核解析，不代表订阅有效、节点可连接、DNS 一定正常或端口没有冲突。
启动后的最小检查顺序是：先看进程是否运行，再看 mixed-port 是否监听，接着确认策略组中是否有节点，最后测试域名解析和实际连接。如果只改了 YAML 中的端口，却没有同步修改客户端的代理端口，表现仍可能是“连接失败”。
配置无法启动时，按症状逐项排查
- 提示策略组不存在：逐字检查
rules引用的组名，以及proxy-groups.proxies和use中的名称；大小写、空格和连字符都可能造成引用不一致。 - 订阅更新失败：检查 URL 是否完整、是否过期、是否需要请求头，以及
path所在目录是否可写。Proxy Providers 支持 HTTP、file 和 inline 类型，但不同前端可能只暴露其中一部分，字段以当前内核文档为准。 - 配置校验通过但没有节点：校验只检查结构，不会替你确认订阅返回内容。先在提供者页面查看更新时间和节点数量，再确认
proxy-groups.use仍引用main。 - DNS 无法解析：先关闭 TUN 和 DNS 劫持，只保留基础 DNS；确认能解析后，再逐项恢复
fake-ip、dns-hijack和自动路由。 - 端口被占用：更换
mixed-port或 DNS 监听端口，并同步修改客户端设置；不要只改其中一处。 - 规则不生效：规则按顺序匹配，过早的宽泛规则可能提前命中。不要用示例中的短规则覆盖订阅原有规则，除非你已经确认自己需要完全重写规则。
- 升级或更换前端后字段报错：先确认当前实际运行的 Mihomo 内核和客户端支持范围。本文没有核实所有前端对每个高级字段的兼容性，无法确认的字段应删除或按当前版本文档重新配置。
最稳妥的恢复方法是回到 Lite 模板：关闭 TUN，删除不必要的 DNS 高级字段，只保留一个提供者、一个手动策略组和一条兜底规则。Lite 能启动后，再一次只增加一个变量，这样才能判断问题来自订阅、策略组、DNS、TUN 还是端口。
常见问题
Mihomo 配置模板中的订阅链接应该替换哪一行？
替换 proxy-providers.main.url 中的示例地址即可。不要改 provider 名称 main，除非同时修改 proxy-groups.use 中对 main 的引用。订阅链接属于敏感信息，不要公开分享。
为什么 mihomo -t 校验通过，启动后仍然无法连接？
mihomo -t 主要检查当前内核能否解析配置，不等于订阅有效或节点连接成功。继续检查提供者是否更新、策略组是否有节点、DNS 是否可用、端口是否冲突以及本地防火墙。
Mihomo 配置模板要不要默认开启 TUN？
不建议默认开启。只需要浏览器或支持代理的应用时，先用 Lite 或标准模板；需要系统级流量接管时，再单独启用 TUN，并检查权限、DNS 劫持、自动路由和防火墙。
proxy-groups 里的 use 和 proxies 有什么区别？
use 用于引用 proxy-providers 提供的节点集合，适合订阅场景；proxies 用于直接填写节点、其他策略组或 DIRECT。引用不存在的名称可能导致校验或运行时报错。
DNS 使用 fake-ip 后局域网设备无法访问怎么办？
先关闭 TUN 或暂时改用 redir-host，确认普通 DNS 和局域网访问是否恢复；再根据 Mihomo DNS 与 TUN 文档检查 fake-ip-filter、DNS 劫持、严格路由和系统 Private DNS 设置。