Mihomo配置文件怎么写：从空白 config.yaml 到正常运行
简答：Mihomo 配置文件通常是 config.yaml，先用最小模板跑通端口和规则，再按需加入手动节点或 proxy-providers。YAML 缩进、节点名称引用和规则顺序是最常见故障点；按文中的校验、日志和 curl 步骤检查后，能判断是配置解析、订阅加载还是连接本身的问题。
定义：Mihomo 配置文件是以 YAML 编写的运行参数文件，用于定义本地代理端口、节点、策略组、订阅 Provider、DNS、规则以及可选的 TUN 和控制接口。
先复制最小模板：确认配置文件能启动
本站是第三方使用指南站，不是任何客户端或服务品牌的官方页面。Mihomo 使用 YAML 配置，字段区分大小写，只能用空格缩进，不能用 Tab；同一级字段必须左对齐。官方语法说明见Mihomo YAML 语法。
先新建名为 config.yaml 的文件，复制下面的最小结构。它不包含真实节点，适合先检查 YAML、端口和规则结构：
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "请替换为本地控制密钥"
proxies:
- name: "直连"
type: direct
udp: true
proxy-groups:
- name: "默认"
type: select
proxies:
- "直连"
rules:
- MATCH,默认
这份配置只定义了一个直连出口，因此不会凭空产生可用节点。它的目的，是先确认 Mihomo 能读取文件、监听 7890 端口，并把未匹配请求交给名为“默认”的策略组。策略组中的名称必须与 proxies 或其他策略组名称完全一致。
配置文件的核心结构：每一段分别负责什么
| 配置段 | 作用 | 新手先怎么写 |
|---|---|---|
mixed-port | 同时提供 HTTP 和 SOCKS 代理的本地端口 | 先保留 7890，确认没有端口占用 |
mode | 决定直连、全局或规则模式 | 使用 rule，让 rules 生效 |
proxies | 手动定义出站节点 | 没有节点参数时只保留 direct |
proxy-providers | 从 HTTP 地址或本地文件加载节点集合 | 有订阅时优先使用，避免直接改下载文件 |
proxy-groups | 把节点、订阅集合或其他策略组组织起来 | 先使用 select，需要自动测试再改为 url-test |
rules | 按顺序决定请求走直连、代理组或拒绝 | 最后保留一条 MATCH 兜底规则 |
dns | 启用 Mihomo 的 DNS 处理模块 | 先用最小配置，遇到兼容问题再调整 fake-ip |
官方配置索引将通用配置、入站、规则、出站、DNS 和策略组分开说明。不要一开始把 TUN、嗅探、复杂规则集和多个 DNS 策略全部加入；先让一个本地端口和一条规则运行，再逐项扩展。
手动写节点：名称、协议和必填字段必须对应
节点写在 proxies 数组中，每个节点至少要有唯一的 name、协议类型 type、服务器地址 server 和端口 port。官方说明明确指出，节点是数组结构，名称必须唯一；通用字段可参考Mihomo 出站代理通用字段。
下面只展示字段结构，不包含真实服务器、账号或密钥。请把示例值替换成服务方提供的参数，不要猜测协议字段：
proxies:
- name: "SS示例"
type: ss
server: 替换为服务器地址
port: 443
cipher: aes-128-gcm
password: "替换为密码"
udp: true
- name: "VMess示例"
type: vmess
server: 替换为服务器地址
port: 443
uuid: 替换为用户ID
alterId: 0
cipher: auto
tls: true
servername: 替换为TLS名称
- name: "VLESS示例"
type: vless
server: 替换为服务器地址
port: 443
uuid: 替换为用户ID
tls: true
servername: 替换为TLS名称
- name: "Trojan示例"
type: trojan
server: 替换为服务器地址
port: 443
password: "替换为密码"
sni: 替换为TLS名称
不同协议的字段不能混用。例如，VMess 的用户字段和传输字段应以VMess 配置文档为准；VLESS 的 flow、reality-opts 等字段只有在服务端参数对应时才填写，参考VLESS 配置文档。Trojan 的密码和 TLS 参数参考Trojan 配置文档。不要为了“补全”而添加未提供的字段。
订阅 Provider 怎么写：避免直接修改订阅文件
如果节点来自订阅，建议将下载内容交给 proxy-providers 管理，再在策略组中通过 use 引用。官方文档支持 http、file 和 inline 类型，并说明 Provider 文件路径默认受工作目录限制，详情见proxy-providers 配置文档。
HTTP 订阅模板如下。将 url 替换为你已核验来源提供的订阅地址；不要把带有个人 token 的完整地址公开发布或提交到代码仓库：
proxy-providers:
my-provider:
type: http
url: "替换为订阅地址"
path: ./proxy_providers/my-provider.yaml
interval: 86400
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 300
timeout: 5000
lazy: true
proxy-groups:
- name: "默认"
type: select
proxies:
- "直连"
use:
- my-provider
直接编辑下载后的订阅文件，更新时可能被新内容覆盖；把本地个性化设置写进单独的覆写或扩展配置，通常更容易保留修改。具体覆写能力和字段应以当前版本文档为准，不能把订阅返回内容当作完整主配置文件直接运行。
策略组和 rules 怎么写：先理解引用关系与匹配顺序
select 适合手动选择，url-test 适合对组内节点做周期性健康检查，fallback 会按顺序选择可用节点。策略组的官方字段、use、健康检查和默认选择说明见proxy-groups 配置文档。
一个同时支持手动节点和订阅节点的示例：
proxy-groups:
- name: "手动选择"
type: select
proxies:
- "直连"
use:
- my-provider
- name: "自动测试"
type: url-test
use:
- my-provider
url: https://www.gstatic.com/generate_204
interval: 300
tolerance: 50
rules:
- DOMAIN-SUFFIX,example.local,直连
- IP-CIDR,192.168.0.0/16,直连,no-resolve
- MATCH,手动选择
规则从上到下匹配，顶部优先级更高；官方路由规则文档也说明了这一点。通常把局域网或明确需要直连的规则放在前面，把代理组规则放在后面，最后用 MATCH 兜底。若策略组名称写成“默认”，规则却写成“Proxy”，配置可能能解析，但请求不会按预期进入目标组。
DNS、TUN 和控制器：新手先保持最小化
DNS 可以先使用最小配置，确认代理和规则工作后再考虑 fake-ip、分流 DNS 或更复杂的策略：
dns:
enable: true
ipv6: false
enhanced-mode: redir-host
nameserver:
- https://dns.alidns.com/dns-query
- https://doh.pub/dns-query
官方 DNS 文档说明 enhanced-mode 可选 fake-ip 或 redir-host；如果某些应用、局域网域名或企业办公系统不兼容 fake-ip，再针对性调整，不要把所有故障都归因于 DNS。TUN 会接管更广泛的系统流量，通常还涉及系统路由、DNS 劫持和管理员权限；它不是普通系统代理的同义词。入站文档说明，TUN 适合系统流量捕获，而固定代理端口适合只让应用显式使用代理。
external-controller 建议只监听 127.0.0.1。官方通用配置文档说明，将地址改为 0.0.0.0 会监听所有 IP；如果确实需要远程控制，应设置 secret 并限制防火墙访问。不要把控制器端口直接暴露到公网，也不要把 token、密码或订阅地址写进截图和公开仓库。
启动、校验和报错排查：按顺序定位是哪一层出错
- 先检查 YAML：确认文件扩展名确实是
.yaml，缩进只用空格，冒号后有空格，字符串中包含特殊字符时使用引号。若启动时出现解析错误，先回退到最小模板，再逐段加入节点、策略组和 DNS。 - 再检查端口：如果提示端口被占用，换一个未使用的
mixed-port，或关闭占用该端口的程序。不要同时让多个 Mihomo 实例监听同一端口。 - 检查节点引用：策略组里的
proxies名称、Provider 名称和规则末尾的目标名称必须存在且拼写一致。出现“找不到代理”时，优先检查名称、缩进和use是否放在正确的策略组下。 - 检查订阅返回：Provider 更新失败时，先确认地址没有过期、返回内容确实是 Mihomo 能解析的节点集合或配置文件；不要只看浏览器能否打开。若服务方要求特定请求头，应按其说明配置
header，不要在日志中打印认证信息。 - 查看日志：前台启动时直接看终端输出；Linux 使用 systemd 时，可执行
journalctl -u mihomo -o cat -e查看末尾日志，持续观察可执行journalctl -u mihomo -o cat -f。官方运行服务文档给出了这些日志路径和命令。 - 最后验证端口：确认 Mihomo 已运行后，在本机用 GET 请求检查控制器版本：
curl -H "Authorization: Bearer 请替换为控制密钥" http://127.0.0.1:9090/version。代理连通性可用带代理参数的 GET 请求验证，例如curl -x http://127.0.0.1:7890 https://www.gstatic.com/generate_204 -o /dev/null -w "%{http_code}\n"。如果端口能访问但目标请求失败，再检查节点、DNS、规则和网络，而不是继续改 YAML。
Windows、Linux、macOS 或图形客户端的配置文件位置可能不同，应以启动参数、客户端配置目录或当前客户端说明为准。Linux 以 systemd 运行时，官方示例使用 mihomo -d /etc/mihomo 指定工作目录；涉及 TUN 或系统服务时，需要管理员权限。
什么时候使用覆写，而不是修改原始订阅
可以按下面的判断选择：
| 场景 | 建议 | 原因 |
|---|---|---|
| 只有一两个手动节点 | 直接写入主配置的 proxies | 结构简单，便于逐字段核对 |
| 节点由远程订阅定期更新 | 使用 proxy-providers | 避免把原始订阅当作长期手工文件维护 |
| 只想改策略组、DNS 或规则 | 使用客户端支持的覆写或扩展配置 | 减少订阅更新覆盖本地修改的影响 |
| 需要 TUN、嗅探或复杂 DNS | 先备份，再逐项加入 | 高级设置涉及系统权限和流量接管，故障范围更大 |
无论采用哪种方式，都建议先保存一份能启动的版本，再一次只改一个配置段。这样出现问题时，可以根据日志快速判断是 YAML 解析、节点加载、策略组引用、DNS 解析还是系统代理设置导致。
常见问题
Mihomo 配置文件默认叫什么？
常见文件名是 config.yaml，但实际读取位置取决于启动参数、工作目录或图形客户端配置目录。Linux systemd 示例使用 -d 参数指定工作目录，因此不能只凭文件名判断是否被读取。
为什么配置能启动，但策略组里没有节点？
优先检查 proxy-groups 的 use 是否引用了正确的 Provider 名称，或者 proxies 中的节点名称是否与定义处完全一致。Provider 下载失败、返回格式不兼容或 filter 排除了全部节点，也会导致策略组为空。
rules 写了却没有生效，应该先查什么？
先确认 mode 是 rule，再检查规则顺序、规则目标名称和最后的 MATCH 兜底。规则从上到下匹配，前面过宽的 DOMAIN、GEOIP 或 RULE-SET 规则可能已经提前接管请求。
能不能直接修改订阅下载下来的 YAML？
可以临时修改，但订阅更新可能覆盖本地改动。若只是调整策略组、DNS 或规则，优先使用客户端支持的覆写或扩展配置；节点本身仍应以订阅返回内容为准。
Mihomo 配置文件报 YAML 解析错误怎么办？
先将文件回退到最小模板，再逐段粘贴内容。重点检查 Tab 缩进、冒号后的空格、引号是否闭合、列表前的短横线以及重复或错位的缩进。随后查看前台终端或 systemd 日志中的行号。