YAML 结构总览
配置文件首先是一份有层级的文本,不是把设置名称随意堆在一起的清单。YAML 用缩进表示从属关系,用冒号连接字段与内容,用短横线表示列表成员。读一份陌生配置时,先找最左侧的顶层字段,再看每个字段下面缩进的部分。这样能分清哪些是全局设置,哪些只属于某个节点,避免把正确参数写进错误位置。
从缩进看懂对象与列表
建议统一使用两个空格缩进,不要混入制表符。两个同级字段左边应当对齐,子字段比父字段多缩进一级。冒号后面通常需要一个空格;列表项的短横线后面也需要空格。编辑器可以开启“显示空白字符”,把看不见的缩进显示出来。遇到报错行时,也要检查它前面几行,因为遗漏引号或错误缩进常在后续位置才暴露。
# 可由支持这些字段的 mihomo 内核加载
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
- name: 手动选择
type: select
proxies:
- DIRECT
rules:
- MATCH,手动选择
这份示例只演示层级,所有连接最终直连,不包含可用的远程代理。顶层的 proxy-groups 是一个列表,列表里的每个成员是一个策略组对象。对象内的 proxies 又是一个列表,内容是候选出口名称。顶层 proxies 则保存代理节点定义。两个字段虽然同名,所在层级不同,承担的工作也完全不同。
把配置看成一条引用链会更容易理解:代理节点声明连接方式,策略组引用节点名称,规则再引用策略组名称。DIRECT 是内置直连出口,不需要在代理列表里另建一个同名节点。名称引用要逐字对应,包含大小写、空格与标点。把“手动选择”改成“日常选择”时,规则中的目标也要一起改,否则语法可能通过,加载时仍会提示目标不存在。
字符串、布尔值与空内容
带有特殊符号的值优先使用引号,尤其是密码、包含井号的名称、看起来像日期的内容。井号在特定位置会开始注释,没有引号时可能截断原值。布尔值用 true 和 false,端口用数字;不要为了外观统一把所有内容都写成字符串。[] 表示空列表,和只有字段名却没有内容并不相同。敏感字段需要保留原始字符,不能自行修剪内部空格。
同一个对象内不要重复声明相同键。两个顶层 rules 不代表把规则接起来,不同解析器可能拒绝加载,也可能只保留其中一段。若收到别人提供的片段,先判断它是完整文件,还是某个父字段下面的内容,再决定粘贴位置。只拿到 nameserver 的子项时,不能直接把它们放到文件最左侧。
开始修改前,复制一份原始文件,并在副本名称中注明用途。先用上面的最小结构练习缩进,再阅读真实订阅,不要把练习文件直接替换生产配置。每增加一个部分就加载一次,比一次粘贴几百行后寻找错误更省事。如果想逐段对照完整文件,可以继续阅读config.yaml 阅读顺序,本页后续章节则用于查字段含义和边界条件。
端口与运行模式
通用字段决定客户端从哪里接收流量,以及收到后按什么方式处理。先把“本地入口”和“远程出口”分开:本地端口供浏览器或系统代理连接,远程节点端口用于连接服务端。两者恰好使用相同数字也没有关联。只有应用真的把请求送到本地入口,后面的规则才有机会参与判断,因此配置正确不等于所有程序都会自动接入。
选择入口,控制监听范围
port 提供 HTTP 代理入口,socks-port 提供 SOCKS 入口,mixed-port 则让同一个端口接受这两类代理连接。通常选一个混合入口就能满足桌面应用的常见需求,不必为了“配置完整”同时开放所有端口。示例里的数字只是本地约定,若已经被其他程序占用,应改成空闲端口,并同步调整系统代理与应用设置。
mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false
allow-lan: false 适合仅本机使用;bind-address 表示监听地址。回环地址 127.0.0.1 只指向当前设备。即便修改为允许局域网,也仍要核对监听地址、防火墙与客户端覆盖设置。不要把代理入口直接开放到公网。确实需要给同一局域网设备使用时,应先限定可访问范围,再检查内核支持的入口认证方式。
| 字段 | 解决的问题 | 检查位置 |
|---|---|---|
mixed-port | 本地 HTTP 与 SOCKS 接入 | 系统代理和应用代理地址 |
allow-lan | 是否允许其他设备接入 | 监听地址与防火墙 |
mode | 选择规则、全局或直连处理 | 客户端当前模式 |
log-level | 控制日志详细程度 | 内核运行日志 |
规则模式不是连接开关
mode: rule 表示按照规则列表匹配;global 通常把接入流量交给全局策略选择;direct 则按直连方式处理。切到全局模式可以辅助判断规则是否影响某个请求,但不应把它当成修复所有问题的按钮。若应用没有进入代理入口,或节点本身无法连接,切换模式也不能消除这些前置问题。
系统代理与 TUN 模式也属于不同层面。系统代理是向系统登记一个代理地址,应用可以选择是否遵循;TUN 是虚拟网络接口,由路由把符合条件的数据包交给内核。TUN 往往涉及管理员权限、路由与 DNS 接管,字段还会受平台影响。初次调试建议先用系统代理跑通一个明确的请求,再按使用文档启用 TUN,避免同时排查两套入口。
客户端界面中的端口和模式可能优先于文件内容。文件写着规则模式,界面却显示全局时,要查看运行中的最终配置,而不是反复修改原文件。部分客户端把端口作为应用级设置,重载订阅也不会改变。确认当前实际监听端口后,再检查浏览器或命令所使用的地址,才能避免请求误入另一套正在运行的代理程序。
日志级别平时使用 info 即可,定位问题时临时切到 debug。详细日志会增加输出,也可能记录目标域名、地址与连接路径,分享前应检查敏感信息。关闭调试后恢复常用级别,避免长期积累不必要的记录。控制接口用于管理内核,并不是上网入口;不要把系统代理填写为控制接口端口,也不要为方便管理随意扩大它的监听范围。
最后再看 IPv6。顶层的 ipv6 与 DNS 区域里的同名选项分别影响连接和解析行为,具体效果需结合内核实现。示例关闭它是为了缩小入门排查范围,并非所有网络都应长期关闭。若网络和代理出口支持 IPv6,可以在基础连接稳定后单独开启测试,同时观察 AAAA 解析结果与实际出站地址,确认不是仅在界面上改变了一个开关。
DNS 与域名解析
DNS 是把域名转换成网络地址的过程。规则里写的是域名,并不代表整条链路都不需要解析:连接代理服务器、连接目标网站、判断地址所属区域,都可能触发 DNS。排查时先问“谁在解析、向哪里解析、得到什么结果”,不要直接把超时归结为节点失效。浏览器自带的加密 DNS 还可能绕开系统的解析路径,让同一设备上的应用出现不同表现。
普通解析与 Fake IP
enhanced-mode 选择增强解析模式。fake-ip 会给应用返回一个映射用地址,内核再根据映射找回原始域名;它不是网站真实地址。这样更容易保留域名信息供规则使用,但依赖请求后续确实进入同一个内核。redir-host 主要返回实际解析地址,行为更接近传统解析。不要只凭某个网站的推荐,在未理解入口的情况下来回切换。
dns:
enable: true
listen: "127.0.0.1:1053"
ipv6: false
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- "*.lan"
- "localhost"
default-nameserver:
- 223.5.5.5
- 119.29.29.29
nameserver:
- https://dns.alidns.com/dns-query
这段配置提供一个本机 DNS 监听入口,但不会单凭 listen 自动修改系统 DNS,也不会自动完成 TUN 接管。若系统仍把请求交给路由器,内核里的设置可能尚未参与处理。确认入口时,需要结合客户端 DNS 接管设置、系统网络设置和日志。监听在非标准端口时,普通系统 DNS 设置通常不能直接填写这个端口,应使用支持该入口的程序或接管机制。
default-nameserver 常用于引导解析加密 DNS 服务自身的域名,因此示例使用 IP 地址,避免先解析域名才能找到解析器的循环。nameserver 是常规上游解析服务;示例使用 HTTPS 传输,即通常所说的 DoH。加密解析仍需要网络可达,不能保证所有环境下都能直接连接,也不能替代代理节点。更换上游时,应先验证当前网络能否访问它。
按域名指定解析器
部分域名需要走特定解析路径,例如公司内部域名只存在于内网 DNS。mihomo 支持用 nameserver-policy 按域名选择上游。下面的内部域名和解析地址仅演示结构,实际使用时必须换成所在网络提供的值,并把这段放进同一个 dns 对象中,而不是新建第二个顶层 DNS 字段。
# 合并到已有 dns 对象内部
nameserver-policy:
"+.corp.example.com":
- 192.168.1.1
Fake IP 过滤列表用于让指定域名不走虚拟地址映射,不等同于规则中的直连列表。给一个域名添加过滤项后,流量仍会继续受分流规则控制。局域网发现、某些游戏或依赖真实地址的程序遇到异常时,可以针对已确认的问题域名测试过滤,不要把所有域名都加入过滤列表,否则等于取消了原本希望使用的机制。
在支持的 mihomo 配置中,还可以用 proxy-server-nameserver 指定代理服务器域名的解析器。它与网站域名解析不同,目的是确保建立代理连接前就能找到服务器。涉及 respect-rules 等让 DNS 连接遵循分流规则的选项时,更要检查是否产生循环:解析器需要代理,代理服务器又必须先通过该解析器得到地址。没有明确需求时,先保留较简单的解析链路。
验证 DNS 时分两步看:先确认查询确实到达内核,再确认查询结果能用于后续连接。Fake IP 模式下看到映射地址可能是正常现象,不能拿它直接当远程服务器地址使用。若只有一个应用异常,优先检查它的内置 DNS、缓存与接入方式;若所有应用同时异常,再检查上游可达性和接管路径。一次只换一个解析选项,才能从结果判断真正起作用的环节。
代理节点字段
代理节点描述一条远程连接需要的参数,不是一个只要填上名称就能使用的标签。协议类型决定字段集合,服务端决定具体取值,客户端内核决定是否支持。订阅已经提供节点时,优先保留原始参数,只调整策略组或规则。手动修改加密方法、传输方式或认证内容,通常不会让连接更快,反而容易造成客户端与服务端不一致。
先核对公共字段
name 是供策略组引用的本地名称;type 是协议标识;server 是远程服务器域名或 IP;port 是服务器监听端口。名称可以按用途命名,但应保持唯一,避免与策略组和内置出口重名。域名字段只写主机部分,不要附加 https:// 或页面路径。端口也不能直接照抄本地混合端口,必须按服务端资料填写。
proxies:
- name: 示例出口
type: ss
server: proxy.example.com
port: 443
cipher: aes-128-gcm
password: "your-password"
udp: true
proxy-groups:
- name: 手动选择
type: select
proxies:
- 示例出口
- DIRECT
示例使用保留的演示域名与假密码,仅展示 Shadowsocks 节点结构,不提供实际代理服务。要建立连接,需要合法取得的服务端地址、端口、加密方法和密码。cipher 必须与服务端相符,不能把它当作随意挑选的安全等级。复制密码时尤其注意引号内的空格、特殊符号以及换行,界面里显示相似并不代表字节内容一致。
| 字段类别 | 典型内容 | 错误后的常见方向 |
|---|---|---|
| 寻址 | server、port | 域名解析、连接超时、端口拒绝 |
| 认证 | password、uuid | 握手失败、服务端拒绝 |
| 传输 | network 及协议选项 | 路径或传输方式不匹配 |
| TLS | servername 等 | 证书名称、信任链、系统时间 |
协议参数不能相互拼凑
不同协议的认证字段并不通用。例如某些协议使用密码,另一些使用 UUID;传输层可能是 TCP、WebSocket 或其他方式。不能把多个教程里的字段合到一起,期望内核自动判断。先确认协议,再阅读该协议在当前内核中的字段定义。某个字段在另一客户端可用,也不意味着当前内核支持相同写法,未知字段有时被忽略,未必总能得到清楚的报错。
TLS 是连接中用于加密和验证对端身份的机制。servername 常用于指定握手时的服务器名称,和节点显示名称不是一回事。证书报错时,先核对服务器资料、设备时间和名称是否匹配。不要把关闭证书验证当作长期修复方法;这样可能掩盖错误地址或信任问题。WebSocket 的请求路径与请求头也需要匹配服务端配置,不能根据网站首页地址推断。
udp: true 表示允许使用节点的 UDP 能力,不会让原本不支持 UDP 的服务端突然具备能力。浏览网页正常而游戏、语音异常时,要分别检查本地入口是否接入 UDP、协议和服务端是否支持,以及规则是否把这些请求交给预期出口。只看 HTTP 连通性测试不足以证明整条 UDP 路径正常,这也是“节点显示可用但应用失败”的常见原因。
节点数量较多时,可以使用 proxy-providers 管理代理集合,由策略组通过 use 引用。它和返回完整配置文件的订阅不是同一回事:代理提供器期待的是兼容的节点列表结构,不能把任意订阅地址直接填入。远程地址还可能带访问凭据,分享配置时要删除。新手先用客户端现有订阅管理功能,确认需要独立管理节点池后再引入提供器。
更换客户端时,保留配置副本,再检查所用内核和支持协议。可以优先从下载页的 Clash Plus开始选择,其他客户端也应按设备要求挑选。若节点参数来自服务提供方,连接失败时应先对照原始资料,而不是重新命名全部节点。清晰的名称有助于读日志,但它不会改变连接性能,稳定的字段引用比复杂命名更重要。
策略组与选择
策略组是在多个连接选项之间做决定的中间层。规则不必直接绑定某个远程节点,而是把请求交给一个组,再由这个组决定出口。这样更换节点时,通常只需调整组的选择,不必重写每条规则。理解策略组时,先看它的候选成员,再看选择方式,最后看哪些规则引用了它;单独读一个组的名称,无法判断流量最终去向。
手动、自动与故障切换
select 是手动选择,适合需要明确控制出口的场景。url-test 根据指定测试地址的连通性测试结果进行选择,但测得结果只代表该测试目标和测试方式,不代表所有应用的体验。fallback 更偏向按候选顺序寻找可用成员,适合有明确主备关系的需求。三者解决的问题不同,不应单凭“自动”二字就把所有业务交给同一种组。
proxy-groups:
- name: 自动候选
type: url-test
proxies:
- 示例出口
url: https://www.gstatic.com/generate_204
interval: 300
tolerance: 50
- name: 日常出口
type: select
proxies:
- 自动候选
- 示例出口
- DIRECT
此片段需要先在 proxies 中定义“示例出口”,不能单独当完整文件加载。测试间隔的单位是秒;tolerance 是毫秒容差,用于减少结果小幅波动引发的频繁切换。测试地址应当稳定、可达且适合当前网络,示例地址不是强制选择。若测试目标本身受限制,组内全部失败也不能直接证明所有节点都无法用于其他目标。
当“日常出口”选中“自动候选”时,请求会继续由内层组选择节点;选中“示例出口”则直接使用该节点;选中 DIRECT 就会直连。组内出现直连并不表示它只是备用说明,而是真正可被选中的出口。如果某类流量必须使用代理,就不要在它依赖的路径里无意保留可选直连,至少要清楚当前选中的成员是什么。
引用关系与稳定性
组可以引用其他组,但不能形成循环。比如“日常出口”包含“媒体出口”,“媒体出口”又包含“日常出口”,就没有能够结束选择的路径。规划时可以画一条简单的单向链:用途组指向选择组,选择组指向节点或内置出口。每增加一层都要有理由,不要只为了让界面分类更漂亮而嵌套过深,否则出问题时需要逐层确认实际选项。
自动切换主要影响后续建立的连接,不保证已有连接立即迁移。网页使用连接复用、视频保持长连接时,切换后可能仍沿用原出口。涉及登录、支付或对出口地址敏感的业务,稳定选择通常比频繁追逐测试结果更合适。要验证切换效果,关闭旧连接后重新请求,并在连接详情中检查策略链,而不是只看策略组按钮是否变色。
load-balance 会按配置策略把连接分配到候选成员,它不等于把一个下载连接的带宽直接相加。不同连接可能使用不同出口,站点也可能因此触发重新验证。没有明确的负载分配需求时,先使用手动选择或较简单的自动候选组。复杂组的配置不仅需要内核支持,还需要理解候选可用性、连接保持和业务对出口一致性的要求。
通过提供器引入节点时,策略组可以使用 use 引用提供器名称,而不是把提供器误写成普通节点名称。过滤选项会影响实际候选集合,正则表达式写错可能让组变成空组。更新订阅后若组内节点消失,应依次检查提供器是否成功更新、过滤是否匹配、名称是否改变。不要先删除规则,因为规则只是把请求交给组,并不负责生成组成员。
客户端可能保存手动选择结果,重载配置后不一定回到列表第一项。排查时记录当前选项,必要时显式重新选择,再发起新请求。策略组名称应保持稳定,尤其是被规则、覆写文件或客户端选择记录引用时。需要重构组结构,先保留原名称并验证新候选,再逐步调整引用,比一次重命名所有组更容易回退。
规则语法与顺序
规则列表通常从上往下判断,第一条命中后就确定处理目标,不会自动比较哪条“更精确”。因此,规则不仅要写对内容,也要放对位置。把它想成分流河道里的连续岔口:请求先经过上游规则,已经分走的流量不会再流到下游。配置中最容易误判的问题,就是下面的精确规则被上面范围更大的规则提前截住。
域名、地址与最终兜底
多数规则采用“类型、匹配内容、目标”的形式,例如 DOMAIN-SUFFIX,example.com,日常出口。域名规则里的内容不是网址,不带协议、端口或路径。DOMAIN 匹配完整域名,DOMAIN-SUFFIX 匹配域名本身及其子域名,DOMAIN-KEYWORD 根据关键词匹配域名字符串。关键词范围可能比预期大,已知具体域名时优先用完整或后缀匹配。
rules:
- DOMAIN,router.lan,DIRECT
- DOMAIN-SUFFIX,example.com,日常出口
- DOMAIN,ads.example.net,REJECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
- GEOIP,CN,DIRECT
- MATCH,日常出口
这段需要已有“日常出口”策略组。IP-CIDR 按地址网段判断,GEOIP 根据地址数据库判断所属区域,MATCH 不需要匹配内容,作为最终兜底。把 MATCH 放到前面会让它后面的规则失去机会。私有网段示例只列出两段,不代表覆盖所有本地地址;实际网络还可能需要其他网段、IPv6 或内部域名规则。
| 规则类型 | 匹配对象 | 使用提醒 |
|---|---|---|
DOMAIN | 完整域名 | 不包含其他子域名 |
DOMAIN-SUFFIX | 域名及其子域名 | 不填写网址路径 |
IP-CIDR | 目标地址网段 | 区分 IPv4 与 IPv6 规则类型 |
GEOIP | 地址区域数据库 | 结果受数据库与解析影响 |
MATCH | 所有剩余请求 | 通常放在列表最后 |
解析行为与规则提供器
no-resolve 常用在支持该选项的地址类规则后面,表示不要仅为了判断这条规则主动触发域名解析。它不是“这条连接永远不需要 DNS”。若请求已带真实地址,仍可能参与地址匹配;若只有域名且没有可用地址,该规则可能无法命中。把它加到所有地址规则上,会改变匹配机会,应结合前面的域名规则和最终兜底一起分析。
GEOIP,CN 判断的是地址数据库中的区域,不是网站使用什么语言,也不等于域名注册地。采用内容分发网络的网站可能返回不同区域的地址,数据库也可能更新滞后。若某个固定服务需要稳定出口,应考虑明确的域名规则,而不是完全依赖区域判断。涉及 Clash GeoIP 更新时,先确认当前内核实际使用的数据格式和路径,再按客户端提供的更新入口操作。
规则很多时,可以使用 rule-providers 把集合独立管理,再以 RULE-SET 引用。提供器的行为类型与内容格式必须对应,例如域名列表和经典规则列表不能随意混用。远程规则更新还涉及下载路径与可达性,不能把它当成本地文本永远存在。初次配置先用几条本地规则验证方向,确认顺序正确后再引入规则集合,便于区分内容错误和更新错误。
进程规则可以按程序名称或路径匹配,但支持情况受到操作系统、内核权限和流量接入方式影响。看不到进程信息时,添加更多进程规则也未必生效。移动设备与桌面系统不能简单照抄同一套程序识别规则。需要确认某个应用是否进入内核,先看连接记录中的进程字段是否真实存在,再决定是否使用这类规则。
验证一条规则时,记录目标域名、命中的规则、策略组和最终出口四项。网站可能同时访问主站、图片、登录与接口域名,只匹配主域名未必涵盖整个页面。遇到“页面能开但图片失败”,先查看失败资源的实际请求,不要扩大规则到不相关的关键词。常见命中问题也可查阅FAQ 故障排查分类,按现象缩小范围后再修改列表。
覆写与配置合并
覆写是保留原始配置,再通过另一层设置改变最终结果;合并则是把多个来源组织成内核实际读取的一份配置。它们不是 YAML 格式自带的统一功能,不同客户端可能采用不同规则。文件本身能够描述对象和列表,但“列表前插”“节点保留”“脚本加工”通常由客户端实现。看到别人的覆写片段时,先确认适用客户端和执行阶段,不能默认所有软件都以相同方式处理。
原始配置不等于生效配置
一份订阅配置可能依次经过下载、客户端基础设置覆盖、用户覆写、脚本加工,最后才交给内核。实际顺序要以客户端说明为准。若修改后界面和文件不一致,应寻找“查看运行配置”“导出最终配置”或类似入口。只反复打开下载得到的原文件,可能永远看不到客户端最后附加的端口、DNS 或规则变化。
直接编辑订阅下载文件的风险,是下一次更新会重新取得内容,把本地改动覆盖。更稳妥的做法是:订阅管理远程节点,覆写管理个人规则与本地设置,两部分分别维护。若客户端暂不支持适合需求的覆写,可以复制为本地配置,但要接受它不会自动获得原订阅后续变更。选择哪条路径,应看是否需要持续更新,而不是哪种界面按钮更少。
# 原始片段
dns:
enable: true
enhanced-mode: fake-ip
nameserver:
- 223.5.5.5
# 期望的最终结果:保留其他键,只替换上游列表
# 此处展示结果,不是通用覆写指令
dns:
enable: true
enhanced-mode: fake-ip
nameserver:
- 119.29.29.29
上面的重点在于“保留对象中的其他键”。若客户端采用浅层替换,提交一个只包含 nameserver 的新 dns 对象,可能把原来的 enable 和增强模式一起丢掉;若采用递归合并,则可能保留它们。不要用片段看起来合理来推断合并结果。实际操作后展开最终 DNS 对象,确认未修改的必要字段仍然存在。
列表替换与插入位置
列表尤其需要谨慎。rules、proxies 和策略组内的候选都属于列表,合并工具可能整体替换,也可能拼接,还可能按名称处理成员。规则列表若整体替换,原订阅里的分流内容就会消失;如果只是追加,自定义规则又可能落到原有 MATCH 之后,永远无法命中。因此真正需要的通常不是“加进去”,而是“加在明确位置并保留兜底”。
例如,希望让 docs.example.com 直连,应在所有可能提前命中的宽泛规则之前插入 DOMAIN,docs.example.com,DIRECT。插入机制的名称随客户端而变,不要把“prepend”之类工具配置直接写进内核的 rules 列表。完成后查看最终列表顶部和底部,确认目标规则位置正确、只有预期的兜底,并且引用的策略组仍然存在。
策略组列表也不能简单按数组位置覆盖。订阅更新可能调整成员顺序,原先的第二个组不再是同一个用途。支持按名称匹配的覆写方式通常更容易维护,但仍要处理组名被上游改动的情况。每次更新后,至少检查关键组的候选不为空,个人规则引用没有失效。若添加了固定节点名称作为候选,上游删除或重命名节点时,也要更新候选列表中的对应名称。
本地维护建议分成三份:原始订阅副本、个人覆写文件、确认可用的最终配置快照。出错时先停用最新覆写,恢复上一份已验证结果,再逐项重加。不要在同一轮同时更换节点、DNS 与规则列表,否则无法知道是哪一层造成差异。修改说明写清目的,例如“内部域名直连”,比只写一个日期更能帮助后续理解。
完成合并后,还要测试一次订阅更新。手动加载成功只能说明当前文件可用,不能说明下次远程刷新后仍然保留个人设置。更新结束再查看目标规则、DNS 和策略组选择,确认覆写确实在预期阶段执行。若更新后行为改变,先比较最终配置差异,再检查上游内容,不必立即重装客户端;大多数合并问题能在这一步看清具体丢失或重复的字段。
验证与故障定位
配置验证应分成三个层次:文本能否解析、引用能否加载、实际连接是否符合预期。通过 YAML 语法检查,只能说明缩进和基本格式成立;节点名称不存在、协议字段不受支持,仍可能在内核加载时失败;即便加载成功,应用也可能没有接入代理。按这三个层次排查,比看到一个超时就修改整份文件更容易得到可靠结论。
先检查,再加载
编辑后先保存副本,使用客户端提供的配置检查入口。具备命令行环境且已经安装 mihomo 时,可以使用内核测试命令。命令中的路径是示例文件名,需要在实际文件所在目录执行;Windows 上可按安装位置使用对应可执行文件。测试时还要考虑相对路径资源、规则文件和数据目录是否齐全,不能只复制主文件就假定环境与客户端一致。
mihomo -t -f ./config.yaml
如果提示 YAML 解析错误,先查看报错位置附近的缩进、冒号、引号与短横线;如果提示代理或策略不存在,沿着名称引用往上找定义;如果提示字段或协议不受支持,核对当前内核,而不是用删除随机字段的方式碰运气。测试命令通过后再加载,观察启动日志确认实际使用了这份文件,避免检查的是副本,运行的却是另一份 Profile。
用一个明确请求验证入口
先选一个可重复访问的测试目标,确认本地端口,再显式指定代理发起请求。下面的命令要求本地混合入口监听在示例端口,并且环境中有 curl。它使用 HTTP 代理方式访问 HTTPS 网站,可帮助确认请求是否进入本地入口;命令成功不表示系统上其他应用也已经使用代理。
curl --proxy http://127.0.0.1:7890 --head https://example.com
同时观察客户端连接记录。如果完全没有新请求,检查端口、监听地址、程序是否运行,以及命令是否连接到另一套代理。若请求已经出现,继续看命中规则和策略链。只有命中的规则、组选项与预期一致,才进入节点和远程连接排查。返回状态码也要结合目标判断,不是所有站点都对 HEAD 请求给出与普通页面访问相同的响应。
| 现象 | 优先检查 | 暂时不要做 |
|---|---|---|
| 配置无法加载 | 语法、字段支持、名称引用 | 反复更换远程节点 |
| 连接记录为空 | 应用入口、系统代理、TUN 路由 | 大量增加分流规则 |
| 命中规则不符 | 顺序、目标域名、最终配置 | 先删除整个 DNS 对象 |
| 规则正确但超时 | 组选项、解析、远程握手 | 把全局模式当作永久修复 |
日志里的“拒绝连接”“解析失败”“握手失败”和“等待超时”指向不同阶段。拒绝连接可能是端口没有服务监听;解析失败应先看 DNS 路径;握手失败需要核对协议、认证与 TLS;等待超时则要结合发生位置判断网络可达性。不要只截取最后一行错误,保留前后相关记录更有用,但分享前必须清理订阅地址、认证内容和不希望公开的访问目标。
若只有 Windows 商店应用异常,而浏览器通过同一个入口正常,可继续查阅UWP 回环限制处理步骤。若客户端打开就退出,应先按启动闪退排查笔记检查日志与配置回滚。不同现象不要共用一个修复动作,尤其不要一遇到问题就重装;重装可能保留旧配置,也可能丢掉定位所需的线索。
验证完成后,把临时调试设置恢复,保存一份能正常工作的最终配置,并记录测试目标和修改范围。下次出现问题时,从最近改变的那一项开始回退。需要重新梳理操作主线可回到使用文档;需要判断常见现象可查看FAQ;需要更换适合设备的客户端再到下载页。本页的查阅顺序始终是先确认入口,再追踪解析、规则与出口。