mihomo 配置字段参考
先导入配置、打开接管并验证连接,按入门指南走一遍。已经能连、想知道某个键该放在哪一层,或者更新订阅后要找回自己的规则,就查这份手册。示例从可独立启动的直连底稿讲起;后面的片段按章替换或补入,别把同名的顶层键拼在一起。
YAML 结构与最小配置
先分清映射、序列和标量
配置文件顶层是一张字段表。冒号左边是键,右边可以是一个值,也可以是下一层结构。端口号、模式名和布尔开关是单值;dns 是一张子表;proxies、proxy-groups 和 rules 是有顺序的列表。节点列表每一项还是一张表,规则列表每一项则通常是一整行字符串。不要因为节点和规则都以短横线开头,就把节点属性写成几条独立的列表项:那样仍可能是有效的 YAML,却已经不是内核要读的结构。
用空格缩进,每层两个空格最容易对齐;不要用制表符。注意区分冒号后的空格和括在引号里的冒号:一个内容本身带冒号加空格的名称,要把整个值引起来,否则解析器可能误以为遇到了另一对键值。注释从未被引号包住、前面有分隔空白的井号开始。名称里真要出现井号或前导零,就给值加引号;而端口仍写成整数,开关仍写成 true 或 false,不要把所有值机械地改成字符串。
可独立运行的直连底稿
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
- name: LOCAL
type: select
proxies:
- DIRECT
rules:
- MATCH,LOCAL
这份底稿不依赖订阅、地理数据库或远程规则。请求进入本地混合端口,规则用最后一行把它送进 LOCAL,组内唯一的出站是 DIRECT。这里的“直连”仍经过本地内核,只是出站不经过远端代理。用它能先排除远端服务、凭据与测速地址的影响。如果连这份配置也起不来,先查运行目录、配置文件权限和端口占用;换一份更长的订阅只会扩大故障范围。
顶层键的书写位置不是运行顺序。把 rules 搬到文件第一行,不会让规则先于节点初始化。真正依赖排列的是列表内部,例如规则从上往下匹配,手动选择组按清单呈现成员。引用按名字查找而不是按位置找:示例中 LOCAL 在规则和组定义里必须完全一致。编辑时最好用编辑器搜索这个名字,把被引用的位置找齐,再一次性改名。仅修改显示名称,不处理指向它的规则,会让配置引用断开。
空值、重复键与报错行号
proxies: [] 明确表示空列表。单写一行 proxies: 而没有子项,通常会被解析成空值;空值、空列表和省略整个键不是同一回事,覆写时尤其明显。不要在文件尾部再追加一个 rules: 试图给前面的列表加行:有的解析器拒绝重复键,有的实现可能只保留其中一个值。扩充原列表应在原来的键下面补项,或者通过客户端提供的列表合并功能明确追加。
排错从第一条错误开始。某行提示找不到预期的冒号,原因可能是上一行漏引号,或上一个块少缩进;先看报错行上下各几行。语法能解析后,内核还会检查节点类型、目标名称和字段内容。能被编辑器高亮不等于能被内核加载,成功加载也不等于流量已经进入代理。保存一份能运行的底稿,之后每次只改一个字段块,便于区分“写错结构”和“结构正确但网络路径不通”。
如果下载得到的是订阅地址、编码文本或客户端专用分享链接,先按照导入入口识别它,不要改一下扩展名就交给内核。另一种常见文件只有 payload 或只有节点列表,它是供其他字段引用的资源,不是完整配置。核对文件开头的结构,再决定是在客户端里新增配置、替换某个子表,还是把它作为提供器来源。界面显示的配置昵称也不是磁盘文件路径,排错时要确认正在编辑的是哪一份。
通用字段:监听端口与运行模式
先确定入口,再决定出站
监听端口解决的是应用去哪里提交请求,运行模式解决的是内核接到请求后往哪里发。这是两件事。常用的 mixed-port 同时接受 HTTP 代理和 SOCKS 连接,适合只给本机应用配一个入口。port 单独提供 HTTP 代理入口,socks-port 单独提供 SOCKS 入口;需要拆分调用方式时再开,别指望给两个监听字段写相同的端口能自动复用。若客户端替内核分配端口,以启动日志和界面显示的实际值为准。
| 字段 | 作用 | 排查起点 |
|---|---|---|
mixed-port | HTTP 和 SOCKS 共用的入站 | 确认端口空闲,应用配置指向实际监听地址 |
allow-lan | 是否允许其他局域网设备使用代理入口 | 本机用时保持关闭 |
mode | 选择规则、全局或直连模式 | 排查规则时先切回 rule |
log-level | 调整日志详细程度 | 日常用 info,定位时短暂提高详细度 |
external-controller | 配置控制接口,而非应用代理入口 | 确有需要再启用,限制在受信任的访问范围 |
本机应用通常填回环地址 127.0.0.1 和混合端口。别把控制接口地址填进系统代理:两者都可能监听本地端口,但服务完全不同。控制接口可以读取运行状态并改动设置,不应公开暴露;仅本机需要时绑定回环地址,并按客户端的方式管理访问凭据。确实要让其他设备使用本机代理,再分别核对 allow-lan、监听地址、防火墙和访问控制。能从本机连通,不代表同一网络下的其他设备一定能连通。
三种模式与界面状态
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rule 按规则顺序判定出站;global 走全局策略所选的出站,不逐条套用自定义分流;direct 让内核接受的请求直接出站。切换到直连不是退出客户端,系统代理或虚拟网卡可能还在接收流量。用全局或直连排障时,把原来的模式和选择记下来,测完再恢复。想细看三个路径的区别,可对照规则、全局和直连模式笔记中的场景。
配置里的 mode 是文件里的设置,不一定等于此刻界面上的状态。客户端可能在启动后恢复上次操作,也可能生成中间配置再交给内核。改完文件却仍走全局,先确认加载的是刚编辑的那份,再看界面是否还选着全局。反过来,临时在界面切换也不一定写回原文件。要让变更跟着订阅更新和重启一直生效,应找到客户端支持的持久化入口,而不是只修改运行时状态。
端口监听成功,不等于系统已经接管
系统代理依赖应用读取系统设置,通常适合浏览器等支持代理的程序。虚拟网卡模式则从系统路由接收匹配的流量,除了客户端开关,还要考虑权限、路由冲突与名称解析。两个开关不是叠加后就一定覆盖更多;遇到某个应用无法联网,最好先只开一种方式,记录入口、目标和结果,再换另一种方式做对照。更多机制差异见TUN 和系统代理对比。
不同设备的授权方式不同,不必把桌面端的系统代理步骤照搬到手机。首次安装可从下载页按平台选包;想先用图形界面,可从首推的 Clash Plus 开始,具体选项再按客户端实际能力确认。端口被占用时也别急着结束未知进程,先看是否有另一份客户端或旧内核在运行。若为新配置换了端口,记得同步改掉浏览器、终端或系统里仍然指向旧端口的设置。
如果只是验证一个应用,手动让该应用指向混合端口,比直接改全系统设置更容易回退。这一步能确认内核入口、规则和出站的整条路径;成功后再开启系统接管,结果不一致就把范围缩到应用设置或系统路由。临时提高日志级别时只重跑一个明确的请求,看到入站、目标和出站后调回日常级别,否则大量并行请求会把真正有用的记录挤到后面。
DNS:解析上游、域名策略与增强模式
把解析请求和连接请求分开看
域名解析回答的是“这个名字对应什么地址”,连接规则回答的是“这次访问走哪个出站”。两者在访问过程中互相影响,但不是同一张表。dns.enable 启用内核的 DNS 模块;它不会仅凭一个开关就接管系统上所有解析。浏览器自己的加密 DNS、系统缓存和客户端配置的 DNS 劫持都可能改变请求路径。排错前先弄清是谁发起解析、解析到了哪里,以及内核看到的是域名还是一个已经解析好的地址。
dns:
enable: true
enhanced-mode: redir-host
default-nameserver:
- 1.1.1.1
nameserver:
- https://dns.google/dns-query
nameserver-policy:
'+.example.org':
- 1.1.1.1
示例用加密上游处理一般域名,把 example.org 及其子域交给单独的解析器。default-nameserver 用于引导解析 DNS 上游自身的域名,通常填以 IP 表示的解析器;它并不是普通域名解析失败后的通用备用列表。若运行环境不能访问示例中的公共解析服务,换成当前网络允许且能直达的上游再测。判断是否命中策略,应选两个请求作对照:一个在策略范围内,另一个不在范围内。
客户端内置的 DNS 和系统“首选 DNS”不是等价设置。如果需要让某个应用直接查询内核的 DNS 监听,另行配置 dns.listen,再让应用实际把查询发到该地址;只配置监听并不会把系统里的查询搬过来。监听地址也别图省事写成所有接口,尤其在共享网络里。排查时可以先对指定解析器单独做一次查询,再从原应用复现访问,避免把两个入口的结果当成同一次测试。
redir-host 和 fake-ip 怎么选
redir-host 返回真实地址,适合作为兼容性排查的起点。fake-ip 则为被处理的域名分配合成地址,内核收到随后对该地址的连接时,可以用映射找回域名,再按规则处理。合成地址不是目标服务器的公网地址,不要把它复制到静态主机表,也别用它判断远程服务是否换了地址。如果应用绕过了相应的接管路径,或者把合成地址交给另一台没有映射的设备使用,就可能解析有结果、连接却到不了目标。
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- '+.local'
nameserver:
- 1.1.1.1
这段是对上一段 dns 子表的整体替换。过滤项用于让选定域名不走合成地址分配,常见原因是设备发现或某些服务依赖真实地址。过滤不等于让域名走直连规则,也不会凭空提供多播解析能力。若局域网服务仍打不开,确认服务名是否有真正可用的本地解析途径,以及返回的地址是否被路由到正确网段;切回真实地址模式做对照时,还要考虑应用保留了上次的地址,必要时重启应用并重新查询。
拆开普通域名和节点域名的解析
如果出站节点的 server 写的是域名,节点开始连接前也要解析这个名字。可针对节点名设置 proxy-server-nameserver;使用依赖规则的 DNS 路径时,尤其要确保节点解析有一个不依赖该节点已连通的入口。否则会形成循环:请求要先经过节点,节点却要等这次请求完成才能获得地址。出现所有节点同时超时、直连地址正常但域名节点都失败时,先查这一段依赖,不要先把组内成员全删掉重建。
同一名称返回多个地址不必然是故障,地址可能随地区、缓存和记录类型变化。更可靠的验证是固定一次测试条件:保持同一客户端、同一接管方式和同一个域名,记录查询的入口、返回的记录类型和应用最终连接的地址。如果只有 IPv6 结果失败,应检查系统和出站路径是否都支持该地址族;关闭某个解析选项最多只能改变返回内容,不能代替判断网络是否具备对应的路由能力。
代理节点:协议、远端地址与提供器
节点是出站,不是本地监听
proxies 定义一批可以引用的出站。每个节点的 name 是配置里的引用名,type 决定按哪种协议读后续字段,server 和 port 描述实际要拨号的远端。节点端口与本地 mixed-port 没有对应关系。把客户端的本地端口抄进节点条目,最轻是连不上,指回自己时还可能形成循环。写入配置前先从提供方确认协议、地址和端口,不要从节点名字里的地区或备注去推断字段。
proxies:
- name: LAB-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
proxy-groups:
- name: LAB
type: select
proxies:
- LAB-SOCKS
- DIRECT
rules:
- MATCH,LAB
这组字段可替换直连底稿里的三个同名顶层字段。它要求本机另有一个受控的 SOCKS5 服务监听在 1080,没有就只能用组内的 DIRECT 做对照。测试时先确认这个服务不是当前内核的另一个入口,也不会再把流量送回当前内核。该节点关闭 UDP 是为了让最初的测试只关注 TCP。若应用明确需要 UDP,协议能力、节点设置、服务端支持以及入口的接管方式都要同时满足。
节点名可以用中文,但排查时最好选稳定、简短、容易搜索的名称。同名节点或节点与组重名,会让引用变得含糊,部分配置会直接被内核拒绝。同一个服务器若因协议或端口不同而配置两次,给它们独立名称,不要只靠列表次序辨认。订阅会定期变更显示名称时,也别让大量规则直接依赖单个名字;先用稳定的本地组接住规则,之后维护组的成员关系。
协议参数不能互抄
不同协议对认证字段的要求不同。例如 SOCKS5 可以按服务端配置填写用户名和密码;Shadowsocks 节点则根据服务端资料填写加密方法和密码。不能为了补齐字段,把一种协议的认证块原样搬到另一种协议。涉及 TLS 的节点还要核对服务端要求的名称、传输方式与相应选项;服务器地址和 TLS 用来识别对端的名称不一定相同。看到握手失败,先核对协议和服务端资料,别把放宽证书验证当成长期解决办法。
出站无法建立时,区分三类信号:节点域名解析失败,通常在握手前就能看到错误;目标端口不可达,通常表现为拒绝或等待超时;协议或认证不匹配,则常在连接建立之后失败。验证端口有回应只能说明抵达了某个监听服务,不代表服务认可了当前协议。启用了额外传输层的节点还应检查对应的路径或服务标识,只有服务端明确采用相同设置时,这些选项才有意义。
把可替换的节点清单交给提供器
proxy-providers:
lab:
type: file
path: ./providers/lab.yaml
proxy-groups:
- name: LAB
type: select
use:
- lab
proxies:
- DIRECT
rules:
- MATCH,LAB
本地文件提供器把组定义和节点来源拆开。先在内核的工作目录下准备 providers/lab.yaml,文件只需要前一个示例的 proxies 块;主配置保留通用字段,再使用上面这一段定义组和规则。这里的相对路径按内核工作目录理解,不一定从 GUI 里刚打开的 YAML 文件旁边找。遇到路径报错,先查客户端实际给内核指定的目录,并确认运行内核的用户能读这个文件。
远程提供器取回的内容也必须符合内核预期,不是任意分享链接都能当作节点清单地址。更新失败时,先区分是拉取过程出了错,还是拿到的内容不能解析;后者可能是服务返回了普通网页。分享排查材料时保留错误类型和字段结构,把订阅地址、认证内容及连接记录里不相关的个人地址去掉。需要补概念,可对照术语手册里的订阅、节点和策略组条目。
策略组:选择、测速与故障切换
规则指向稳定的组名
策略组把“哪些请求走这里”和“这个出口当前选谁”分开。规则引用组名,组再引用节点、其他组或内置出站。这样更换节点只需改成员,不必重写全部网站规则。最容易检查的结构是一层业务组对一层候选出口;需要加一层自动选择时,也要保持单向关系。比如手动组可以引用自动组,自动组就不要反过来引用手动组,否则无法得到一个最终出站。
select 是手动选择组,适合首次验证、固定出口和保留备用项。列表里的先后顺序方便操作,但不要把“写在第一位”当作每次启动的强制选择:客户端可能恢复历史状态。排障时应在组界面点到明确的成员,再从连接记录核对实际上线的是哪一个。把 DIRECT 放进组里也不代表会自动切到直连,它只是多了一个可点选的出口。
proxy-groups:
- name: WEB
type: select
proxies:
- LAB-SOCKS
- DIRECT
rules:
- DOMAIN-SUFFIX,example.org,WEB
- MATCH,DIRECT
这段依赖上一章定义的 LAB-SOCKS 节点。它只让指定域名进入手动组,其余请求直接出站。手动切换成员后,用新连接验证,不要指望已有会话自动迁移;浏览器可能复用连接,应用也可能维持一条长连接。如果界面显示已选中另一个节点但行为没变,先断开测试应用原有的会话,再核对新连接的规则命中与实际出站。这样可以区分选择没有保存和连接尚未重建。
自动组的探测只代表探测本身
proxy-groups:
- name: AUTO
type: url-test
url: https://www.gstatic.com/generate_204
interval: 300
tolerance: 80
proxies:
- LAB-SOCKS
- DIRECT
rules:
- DOMAIN-SUFFIX,example.org,AUTO
- MATCH,DIRECT
url-test 用探测网址比较候选出口,适合接受自动选择的流量。这里的 interval 以秒为单位,tolerance 以毫秒为单位,用来减少小幅延迟变化导致的切换。界面显示的是对指定网址的一次或一组探测结果,不是实际业务站点的延迟,更不是带宽。示例把直连加进组里是为了便于实验;如果业务必须走代理,不要把直连列为自动候选,否则它可能因探测更快而被选中。
fallback 更接近按优先顺序选当前可用的成员,而不是挑延迟最低的成员。用它保留首选出口时,把常用成员放前面,再列备用成员,并配置能被这些成员稳定访问的探测网址。两种自动组都受探测地址、连接超时以及调度节奏影响。如果只有探测地址打不开,却能访问实际业务,那么整个组的可用性判断也会偏离实际需求。换探测网址必须同时考虑目标网络是否稳定,以及返回结果是否能说明连接已建立。
成员来源和恢复策略
proxies 点名引用已定义的节点或其他可选出站,use 引入提供器中的成员。节点名字会随订阅更新变动时,用 use 往往比在组里硬编码一长串名字省事。两种来源可以并存,适合把固定的本地备用项与更新的远程候选放在一起。组看起来有名字却没有可选节点时,检查引用的提供器是否加载、清单里是否真有节点、客户端有没有再套筛选条件;不要只刷新测速结果。
如果问题是固定出口不稳定,先决定允许哪些退路,再选择组类型。需要保留登录会话或来源地址时,手动组通常比频繁比较延迟更合适;需要第一候选失效后才转移时,再用故障切换。对无法判定的流量,不要让组偷偷把“走备用代理”变成“直接出站”。保留手动对照组测试新节点,等连接、解析和应用请求都能验证,再纳入自动调度。这样出现异常时也能很快退回上一个明确的选择。
提供器的健康检查与组自己的测速配置也值得分开核对。一个节点在提供器里显示可用,不表示某个组的探测地址一定能从它访问;反过来,一个短期错误也不意味着该节点应从全部组移除。选定同一个目标和同一种传输路径做复查,再决定要修的是候选清单、探测设置还是实际出站。记录判断依据比记录某一次延迟读数更有用。
规则语法:匹配顺序、目标和资源集
第一条命中就决定去向
在规则模式下,内核从上到下检查 rules,第一条命中后就使用其目标,不会继续寻找更精确的规则。大部分规则由类型、匹配内容和目标组成,以英文逗号相隔;MATCH 没有匹配内容,只写一个出站目标。具体例外放在宽泛分类前,最后才放兜底。不要按字母顺序排序规则,也别把个人规则追加到兜底后面:那样虽然字面上存在,实际没有机会执行。
rules:
- DOMAIN,api.example.org,DIRECT
- DOMAIN-SUFFIX,example.org,LOCAL
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,DIRECT
这段可直接替换直连底稿的规则列表,保留其中的 LOCAL 组。首行只对精确域名成立,第二行覆盖主域及其子域。即使两个目标现在都最终走直连,连接记录也能区分是精确项落在 DIRECT,还是后缀项落在 LOCAL。把两行对调,精确域名则会先被后缀项截住。用结构简单的目标做这个对照,可以在排除远端网络影响的情况下验证顺序。
域名规则的内容不是完整网页地址。不要附上协议、路径、端口或查询参数;要匹配的是内核看到的主机名,不是浏览器地址栏里整行内容。重定向后访问的是新目标,页面还可能异步请求另一个域名,从结果看像同一页面,日志里却是多条连接。一次只测一个已知的主机名,并在记录中确认目标与命中行。填从别处复制的规则时,也留意全角逗号或不可见空格。
地址匹配可能触发解析
IP-CIDR 检查 IPv4 地址段,IPv6 用 IP-CIDR6;GEOIP 根据地址与地理数据匹配,依赖当前工作环境中的相应数据。它们不是域名后缀规则。对域名目标,地址类规则可能需要先解析才能判断;某些地址规则末尾支持 no-resolve,用于避免为这条规则额外发起解析,并不代表已经取得的目标地址不会被使用。若无法取得可匹配的地址,就不能假设地址规则必然命中,后面的规则仍要有合理去向。
如果同一项业务一会儿进域名规则,一会儿进地址规则,先查发起连接的应用是否总以同一种方式交付目标。一些应用传域名,另一些直接连接缓存地址。同一域名可解析出多个结果,按地理数据判断也会随实际地址或数据内容变化。别用地理项去代替业务域名清单:对关键业务先定明确例外,再用地址段或地理分类处理剩余请求,并用日志检查命中时实际拿到的目标信息。
外置规则用提供器声明类型
rule-providers:
local-domains:
type: file
behavior: domain
format: yaml
path: ./rules/local-domains.yaml
rules:
- RULE-SET,local-domains,LOCAL
- MATCH,DIRECT
再在内核工作目录的 rules/local-domains.yaml 里写 payload 列表:
payload:
- '+.example.net'
domain 资源集写域名表达式;ipcidr 用于地址段;classical 可容纳带匹配类型的经典规则。行为声明要和文件内容一致,且不要在提供器文件里给每项另写出站,去向由主配置里的 RULE-SET 指定。RULE-SET 在列表中的位置照样影响优先级;私人例外规则如果要覆盖资源集,应该放在引用行之前,而不是挪去改资源文件的顺序。
规则资源更新后出现大面积策略变化,先比较资源类型、更新前后的匹配范围,以及主规则里的优先级。可临时用一份工作目录中的本地资源做对照,区分是下载失败、格式错误还是确实匹配了更广的范围。真正要加一条自己的分流规则时,在前面插入最窄的有效条件,然后各测一个应命中和不应命中的请求。两种结果都符合预期,才算验证了边界,而不是只证明“这次访问能打开”。
覆写与合并:从订阅文件到有效配置
找对要修改的那一层
图形客户端常把远程订阅、个人覆写、界面选择和最终交给内核的文件分开保存。手改订阅缓存可能眼下有效,但下一次更新就被覆盖;手改临时输出也可能在重载时丢失。要让个人规则经得住更新,先确认客户端是否提供覆写、扩展配置或脚本入口,并确认它们的应用顺序。内核读到的是处理后的结果,不会因为源文件里出现“覆写”字样,就自动把两个文件合在一起。
按键值类型来决定如何合并。端口和模式是标量,通常只能留下一个最终值;DNS 是映射,可以只改一个子键,也可能被工具整块替换;规则和策略组是序列,工具可能整段替换,也可能支持前插、后追加或按名称处理。YAML 本身没有规定客户端如何把两份配置的序列拼起来。使用某个工具之前先拿两行规则做实验,检查最终文件中的顺序,不要拿另一款客户端的覆写字段直接套用。
覆写项最好和用途一起记录。例如只需把某个域名转到本地组,就别同时复制端口、日志和整份节点清单;这些无关字段以后会抢占上游的更改。相反,如果要替换整块 DNS 配置,先列出必须保留的解析上游与策略,避免把节点域名使用的专用解析入口一并删掉。覆写越短越便于审查,但不能为了短忽略一个完整功能块需要的其他字段。
用输入和输出验证合并规则
# 远程配置原有规则
rules:
- DOMAIN-SUFFIX,example.org,LOCAL
- MATCH,DIRECT
# 增加一条前置例外后的有效规则
rules:
- DOMAIN,api.example.org,DIRECT
- DOMAIN-SUFFIX,example.org,LOCAL
- MATCH,DIRECT
这两段是输入和预期输出,不是两段能同时启用的配置。重点是例外位于后缀规则之前,原有兜底仍在末尾。客户端若只支持替换规则列表,就用完整的输出列表;支持前置项时,只在相应入口写第一条例外。用输出里的规则与日志交叉验证,顺便确认输出中的 LOCAL 仍能找到定义。改动策略组名时,也要检查覆写程序是不是追加了两个同名组,而不是把原来的组替换掉。
JSON 风格的内联列表和多行列表一般可以表达同样的一组值,但展开后更易比对新增位置。不要为了漂亮而让工具自动排序规则;排序映射键往往只影响阅读,排序列表却会改变含义。删除字段时也先分清“继承原值”和“主动清空”:省略某个键常表示不参与覆写,写空列表可能表示覆盖为零项,具体仍看工具规则。写成空白冒号则可能给内核留下一个并不期望的空值。
锚点复用与更新后的回归
YAML 的锚点和别名适合在同一份文件中复用已有结构,不是跨配置的导入机制。映射合并写法是否受支持取决于客户端预处理器和解析器,尤其别用它来假定序列会逐项合并。如果准备把文件交给其他客户端使用,优先保留已展开、可独立读取的版本。看到日志报告别名找不到时,检查前处理是否移动或删掉了锚点,而不是先去改规则本身。
更新订阅前留住一份上次可用的本地快照,并把个人覆写单独保存。更新后先看节点名和目标组是否仍能被引用,再看名单有没有变空,最后比对规则兜底、DNS 和运行模式。若回归失败,可以先停用覆写跑一次原订阅,再单独启用覆写对照。如果两次都失败,问题不一定在合并;如果只有启用覆写才失败,就把覆写分块恢复,定位到第一个改变行为的块。
保存有效配置做对照时别顺手把包含认证信息的整份文件贴到公开讨论区。比较本地文件时,重点看改动的路径、顺序和引用关系;共享时只保留必要片段,并用一致的假名同时替换定义和引用。这样既能复现结构,也能让协助排查的人看到到底是错位、重名,还是文件生成后根本没有被重新加载。
验证与排障:从加载结果到连接记录
先验配置,再验监听
命令行内核可以先测试配置,不必直接替换正在运行的一套。把当前目录切到自己的测试目录,将有效配置存成 config.yaml;如果用到了本地提供器或规则资源,在同一测试目录中按配置准备子目录。下面的命令假定 mihomo 已在可执行搜索路径里,curl 也可直接调用。第一条先单独执行,成功后在一个终端启动第二条,再到另一个终端运行请求。
mihomo -t -d . -f ./config.yaml
mihomo -d . -f ./config.yaml
curl --noproxy "" --proxy http://127.0.0.1:7890 https://example.org/
不要让图形客户端和这份测试内核同时争抢同一端口。启动前先退出占用者,或为测试配置选另一个空闲端口并改掉命令里的数字。有些环境中 curl 是终端的别名,可改用该平台上的实际可执行程序。使用显式代理选项的目的是让这一次请求按指定入口走,减少系统代理设置和代理环境变量对实验的影响。若测试通过,说明这条入口能接受一次请求,不等于所有应用都读取同一设置。
配置测试失败,先查它有没有找到文件、是否存在解析错误,以及依赖资源能否读取。测试通过但启动失败,重点转向运行环境,例如端口冲突、权限不足或实际工作目录与测试时不同。能启动却连不上,才进入连接路径排查。在这一阶段记录一条完整的错误就够用:重复出现的同类报错通常只是应用不断重试,并不意味着配置里同时坏了十几个地方。
用连接证据缩小故障范围
| 现象 | 先检查 | 下一步 |
|---|---|---|
| 代理端口连接被拒绝 | 内核是否监听在预期地址和端口 | 对照启动日志与应用设置 |
| 应用有请求,内核没有记录 | 应用是否实际经过代理入口 | 分别验证显式代理与系统接管 |
| 有记录,命中目标不对 | 模式、规则顺序与实际目标 | 核对组的当前选择及生效配置 |
| 代理命中后仍超时 | 节点解析、连接与远端握手 | 切换单一成员重试并记录出错阶段 |
没有连接记录时,不要先编辑 DNS 策略或给节点加参数。用明确指定入口的请求做第一组对照;如果它能命中,问题更可能是应用没有读系统代理设置,或者接管入口没有收下这个进程的流量。浏览器与终端要分开看:前者可能有代理扩展,后者可能读取环境变量或工具自己的配置。详细步骤见系统代理不生效的浏览器和终端排查。
已有记录但去向不对时,记下模式、目标名称、命中规则和最终出站这四项。比如规则指向自动组,并不等于出站一定是预想的代理;实际可能选中了允许作为候选的直连。若只有旧会话状态异常,关闭这条会话后重新连接;若新会话仍稳定复现,再检查运行时选项是否覆盖文件中的设置。始终以当次连接的记录为准,别拿上一轮测试的面板截图下结论。
把验证留成可重复的回归步骤
每次修改后至少留三类对照:应走直连的目标、应命中自定义规则的目标,以及应落到兜底的目标。先确保最小配置可运行,再依次放回节点、策略组、DNS 和外部资源,任意一步失败都能回溯到刚增加的一块。对于偶发故障,记录发生时的网络环境和入口类型;从有线切到无线、从桌面换到手机时,系统接管和上游解析都可能变,不能直接把两次结果当成同条件对比。
如果配置在首次导入时就失败,可先回入门指南按导入、模式、连接的顺序复核。已经定位到某个字段时,记录预期行为、实际行为和最小配置片段,再单独复现。恢复生产环境前,把临时打开的详细日志、测试端口和临时接管设置恢复到原状态。这样下一次遇到“改完就不能上网”,能直接从最后一次有效的配置和可重复的请求出发,而不是重新猜一遍。
最后别漏掉重载后和重启后的对照。前者可以确认内核接收了文件变更,后者用来确认客户端是否恢复旧选择、重新生成配置,或者在启动时拉取订阅。若两次结果不同,把变化记录在实际发生的阶段,回到覆写与合并检查来源。长期维护最有用的不是留下更多调试输出,而是知道哪份文件可回退、哪条请求能复验、哪条规则应该被命中。