一、YAML 结构与配置入口

先区分三件东西:订阅链接是获取配置的地址,Profile 是客户端管理的一份配置记录,内核最终读取的才是生效配置。远程 Profile 往往还会经过客户端设置、覆写或脚本处理。因此,订阅原文里出现某个字段,并不代表内核正在使用同样的值。查问题时先找到客户端的运行配置预览,再回头追踪字段来源,比反复编辑订阅文件更有效。

从顶层结构看引用关系

下面是一份可以用来检查加载流程的直连基线。它包含混合端口、模式、空节点列表、一个手动策略组和兜底规则;所有请求最终直连,不提供远程代理能力。先确认这份基线能够加载,再逐项加入服务方提供的节点。这样可以把结构错误与远端连接错误分开,避免一开始就同时处理多个变量。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

proxies: []

proxy-groups:
  - name: "出口选择"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出口选择

proxies 定义具体的远端连接,proxy-groups 把节点或其他组组织成可选目标,rules 决定请求交给哪个目标。规则引用的是名称,不是节点在文件中的序号。名称必须准确对应,空格、大小写和全角标点都可能造成差异。建议先写节点,再写组,最后写规则;这主要是方便阅读,不表示 YAML 顶层字段必须按这个顺序排列。

缩进、列表和字符串的边界

YAML 用缩进表达从属关系。统一使用两个空格,不要使用制表符;同一级字段必须对齐。列表项以短横线和空格开头,列表项内部的属性再缩进一层。冒号后通常需要空格,才能形成键值结构。节点名称、密码、包含冒号或井号的文本适合加引号;尤其是纯数字密码,应写成字符串,避免解析器把它当成数值处理。

井号在引号外通常表示注释。把带有特殊字符的密码直接粘进未加引号的字段,可能使后半段变成注释,文件仍能解析,但连接鉴权失败。布尔值使用 true 和 false,端口用整数,空列表写成 []。不要把界面中复制的中文冒号带进配置;它看起来相似,却不会形成 YAML 的键值分隔。

类型写法示例检查重点
映射mode: rule键名与冒号后的空格
列表- MATCH,DIRECT短横线后有空格
字符串name: "出口选择"引号成对,名称一致
布尔值allow-lan: false不要写成带引号的文本

一份文件与多个配置记录

多个 Profile 通常是互相切换,不会天然叠加。当前选中哪一份,客户端就以哪一份作为主要来源;全局覆写是否继续参与,要看客户端的作用域设置。把两份完整订阅直接拼接,容易重复定义顶层键,也可能让同名节点互相覆盖。需要组合来源时,应明确使用代理集合或客户端提供的合并流程,而不是依赖重复字段的解析结果。

远程配置更新后,手工修改的原文可能被重新下载的内容替换。长期保留的个人规则更适合放进独立覆写;临时试验则先复制成本地 Profile,并用容易识别的名称区分。关于导入、删除和切换记录的具体操作,可继续阅读Profile 与多配置管理方法。本页后续都以“最终配置里只保留一套明确结构”为前提。

二、端口、模式与运行字段

通用字段决定客户端在哪里接收请求、采用哪种代理模式,以及输出多少日志。修改之前先判断请求从哪里进入:浏览器走系统代理,命令行单独指定代理,还是整个设备通过 TUN 接管。三种入口可以同时存在,但它们不是同一个开关。端口已监听,只说明内核具备接收条件;如果应用没有把请求送到该端口,仍然不会产生代理连接。

port、socks-port 与 mixed-port

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

profile:
  store-selected: true

这段示例只接受本机请求。若需要让同一局域网的其他设备连接,必须同时考虑 allow-lan、监听地址与系统防火墙,而不是仅把开关改成真。监听所有网卡会扩大访问范围,不能直接暴露到不受信任的网络。临时共享结束后恢复本机监听,并检查路由器是否配置了端口转发;不需要的转发应一并关闭。

字段作用常见判断方法
mixed-portHTTP 与 SOCKS 混合入口核对应用使用的代理端口
allow-lan允许局域网访问代理入口结合监听地址和防火墙检查
mode选择规则、全局或直连模式查看运行界面的当前模式
log-level控制日志详细程度排错暂用 debug,结束后恢复

模式控制分流,不负责开启系统代理

rule 表示按规则决定去向,global 表示普通请求使用全局策略,direct 表示普通请求直接连接。这里的全局并不代表自动接管设备中每个应用:未进入内核的流量仍然不受它控制。日常先用规则模式;排查特定站点时可以短暂切换全局,对比问题是否来自分流。完成对比后恢复规则,避免把本应直连的请求全部交给远端。

profile.store-selected 用于保存策略组的选择状态,方便重启后恢复,但它不等于保存整个 YAML 修改。组名变化、节点删除或缓存重置,都可能改变恢复结果。切换订阅后看到选项与预期不一致,先核对策略组当前成员,不要只根据上次点击记录判断。三种模式的使用场景可参考规则、全局与直连模式说明。

TUN 是另一种流量入口

TUN 通过虚拟网卡和路由接收流量,适合不能遵循系统代理的程序。下面给出常见结构,但启用前仍需确认客户端已安装所需服务并获得系统权限。桌面客户端可能由界面接管这些字段;如果界面关闭了 TUN,直接编辑源文件不一定能改变运行状态。移动端往往使用系统 VPN 接口,也不应套用桌面服务安装步骤。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

stack 选择协议栈实现,可用值与支持情况应以当前 mihomo 内核为准,不应把更换协议栈当成所有网络问题的通用修复。auto-route 创建路由,auto-detect-interface 尝试识别出口;多网卡、其他 VPN 和虚拟机网络可能影响判断。DNS 劫持主要处理匹配的普通 DNS 请求,不能据此推断所有应用内加密 DNS 都已被接管。

三、DNS、fake-ip 与解析路径

DNS 决定域名如何得到地址,但在代理配置里,它还会影响规则判断、节点服务器解析和连接路径。先把两类域名分开:访问网站时需要解析目标域名,建立代理连接时也可能需要解析节点服务器域名。后者如果依赖一个尚未连通的代理,就会形成循环。出现“所有节点同时失败”时,应先确认节点服务器能否解析,而不是立即更换网站规则。

先建立简单、可解释的 DNS 配置

下面使用 fake-ip,并指定上游与节点域名解析器。示例没有配置监听端口,避免直接与本机 DNS 服务冲突;系统请求如何进入内核 DNS,应通过客户端的 TUN 或 DNS 集成设置确认。示例中的公共解析服务能否访问,取决于当前网络。实际部署前应在本地网络测试可达性,再决定是否保留,不要把解析器地址当成适用于所有地区的固定答案。

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
  default-nameserver:
    - 223.5.5.5
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

default-nameserver 用于解析 DNS 上游自身的域名,常称为引导解析;它不是简单意义上的备用网站解析器。nameserver 是常规查询使用的上游。proxy-server-nameserver 面向代理服务器域名,目的是让建立代理所需的解析路径更清楚。如果节点用域名、上游又需要经过该节点才能访问,就应优先检查这一层是否存在依赖闭环。

fake-ip 返回虚拟地址,不是节点地址

fake-ip 模式可以先向应用返回虚拟地址,再由内核保存域名映射并处理后续连接。看到 198.18 网段地址,不代表网站真的位于这个网段,也不能直接据此判断解析被污染。关键是后续连接是否仍经过同一内核,以及映射是否有效。如果应用绕过内核直连这个虚拟地址,连接自然失败;因此启用 fake-ip 时要同时考虑流量接管是否完整。

fake-ip-filter 用于把需要真实地址的域名排除出虚拟地址响应。局域网设备发现、某些游戏或特殊验证程序可能需要单独处理,但不要一遇到故障就把所有域名排除。先从日志确定具体域名,加入范围尽可能小的过滤条目,再清理相关缓存重试。*.lan 和 *.local 只是示例,不能代替对实际局域网域名的核对。

字段解决的问题容易混淆之处
default-nameserver解析上游服务器的域名不是常规请求的唯一出口
nameserver处理常规域名查询加密传输不等于走代理
proxy-server-nameserver解析节点服务器域名需避免依赖尚未建立的代理
nameserver-policy为指定域名选择上游只选择解析器,不选择业务出口

域名策略、路由策略和缓存分别处理

如果只有内网域名需要交给内部 DNS,可以使用 nameserver-policy 单独指定解析器。但“使用哪个 DNS”与“网站连接经过哪个节点”是两件事,后者仍由规则决定。加密 DNS 的 HTTPS 地址也只说明传输方式,不能自动保证其查询经过代理。启用 DNS 遵循规则的相关选项前,应先安排好节点域名和上游自身的解析,避免循环依赖。

IPv6 也要按链路逐层确认。顶层 ipv6、DNS 是否返回 AAAA 记录、节点是否支持相应目的地址、系统是否存在可用路由,彼此相关但不相同。切换解析模式后,操作系统、浏览器和应用可能继续使用旧缓存;应关闭相关连接并清理必要缓存,再测试相同域名。浏览器打开旧连接成功,不能证明新配置的解析路径已经正确。

四、代理节点字段与代理集合

代理节点描述一次远端连接需要的参数,不负责决定哪些网站使用它。最常见的共用字段是名称、协议类型、服务器地址、端口,以及该协议要求的认证与传输设置。服务方给出的 URI、二维码或订阅,可能已经包含额外参数;手工重建时不能只抄地址和密码。应先确认协议,再按相同协议核对字段,而不是把不同教程的参数混进一张节点定义。

先读共同字段,再读协议专有字段

以下是 Shadowsocks 的结构示例。域名和密码都是教学值,不能用于实际连接;需要由服务方提供真实参数后再填写。name 只用于本地引用,可以改成容易辨认的名字;server 必须是可解析的主机名或正确 IP,不能带网页路径;port 是远端服务端口,不是本机的混合代理端口。

proxies:
  - name: "示例 SS"
    type: ss
    server: proxy.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

cipher 必须与服务端一致,不能为了看起来更新就自行替换;不同加密方式对密码格式也可能有不同要求。udp: true 表示允许节点处理相应 UDP 流量,但还要看协议、服务端和网络路径是否支持。浏览器网页可用而游戏或语音失败,不能仅靠重复开启这个字段解决,应进一步检查该类流量是否进入内核及远端是否开放。

字段填写来源错误表现
name本地定义,保持唯一组引用失败或难以区分
type服务方协议说明字段不被识别或握手失败
server / port远端连接参数解析错误、拒绝连接或超时
认证字段密码、用户标识等协议参数认证失败,不能用本地端口代替

TLS、SNI 与传输参数不能互相替代

对于使用 TLS 的协议,服务器地址与 TLS 校验名称可能不同。以 Trojan 为例,sni 参与 TLS 名称协商,通常应匹配服务端证书和配置要求。它不是随意填写的加速域名,也不一定等于实际连接 IP。WebSocket 的路径、HTTP Host 或其他传输参数则属于额外层次,需要逐项匹配;填写一个 SNI 并不会自动补全这些设置。

proxies:
  - name: "示例 Trojan"
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: proxy.example.com
    skip-cert-verify: false
    udp: true

证书错误应先检查系统时间、SNI、服务器证书与连接目标。不要把关闭验证作为长期修复;它会绕过重要的身份校验,也可能掩盖参数抄错。若服务方要求特殊证书或额外公钥参数,按协议说明配置,不要把其他协议的字段直接塞进当前节点。旧客户端即使能导入 YAML,也未必支持新内核的全部协议,必要时先从安装包页面选择合适的客户端。

proxy-providers 管节点,rule-providers 管规则

代理集合把节点来源独立出来,策略组通过 use 引用集合名称。下面使用本地文件,适合先理解结构;相对路径以配置工作目录为基础,不一定是下载文件夹。文件内部应包含 proxies 列表,而不是一整份带端口和规则的配置。HTTP 集合还需要有效下载地址、更新间隔和可写缓存路径,服务方链接也必须与该集合格式兼容。

proxy-providers:
  本地节点:
    type: file
    path: ./providers/local.yaml

proxy-groups:
  - name: "订阅出口"
    type: select
    use:
      - 本地节点

远程来源更新时要保护订阅地址,因为其中可能含有账户访问凭据。分享配置前删除完整链接与密码,不要只遮住节点名称。集合加载失败时,先看路径与格式,再看网络下载,最后检查组是否引用正确。若没有可用成员,策略组即使存在也无法提供预期出口;因此导入成功、节点存在和能够实际建立连接,应分别确认。

五、策略组类型与引用关系

策略组位于规则和节点之间,是配置里最适合保留稳定名称的一层。规则可以始终指向“代理出口”,而组内节点随订阅更新变化。这样不必每次更换节点都修改规则。组本身不创建新协议,也不会把一个不支持 UDP 的节点变成支持 UDP;它只决定从哪些候选目标中选择,以及什么时候允许重新选择。

select 负责手选,自动组负责候选决策

select 是手动选择组,适合把自动组、直连与若干固定节点并列呈现。url-test 定期测试候选项并按测试结果选择,fallback 更侧重按配置顺序使用可用候选。测试只代表对指定地址的探测结果,不等于任何网站都更快,也不能用于推断带宽。选择组类型之前,先明确希望“固定偏好”还是“根据测试调整”。

proxy-groups:
  - name: "代理出口"
    type: select
    proxies:
      - 自动选择
      - DIRECT

  - name: "自动选择"
    type: url-test
    use:
      - 本地节点
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - MATCH,代理出口

这里沿用上一章的“本地节点”集合,单独复制本段时必须先补齐对应定义。interval 以秒为单位控制测试间隔,tolerance 用于减少小幅差异造成的频繁切换。探测地址应稳定且符合实际网络条件;如果该地址被特定路径限制,测试结论可能失真。配置示例使用真实探测用途地址,但部署时仍需确认它在当前环境能够访问。

类型选择方式适合场景
select用户手动指定成员总入口、固定业务出口
url-test根据探测结果选择可接受自动调整的普通浏览
fallback按顺序选可用成员主备线路与明确优先级
load-balance按策略分配连接理解会话约束后的多出口需求

负载分配不是单连接叠加

load-balance 可以把不同连接分配给不同候选,但通常不能把一次下载的单条连接变成多节点带宽相加。业务还可能要求出口地址保持一致,例如账户登录、支付或某些长连接服务。没有明确需求时,先用手动组或自动选择组,通常更容易解释连接去向;只有了解分配策略和会话约束之后,再考虑负载分配。

自动组测试成功,也不表示已有连接会立即迁移到新节点。连接建立后通常会继续使用原来的出口,新连接才体现新的组选择。排查时先查看连接记录中的实际链路,再重新发起请求;不要只看组界面当前高亮,就认定所有流量已经换路。重启内核可以清理连接,但会中断现有业务,通常没有必要作为每次切换后的固定动作。

用稳定组名隔离订阅变化

推荐建立一层稳定的业务组,例如“代理出口”和“工作访问”,由规则引用这些名称,内部再连接节点集合或自动组。层级保持简单:规则到业务组、业务组到候选组、候选组到节点,通常足够。组相互循环引用没有意义,也可能直接导致配置无法加载;例如甲包含乙而乙又包含甲,应改成单向关系。

名称冲突同样需要处理。节点与策略组尽量不要使用相同名称,否则阅读运行链路时很难区分。集合更新后成员名变化,手选状态可能无法恢复;使用集合引用可以降低静态节点名失效的影响,但仍需确认集合有有效成员。正则过滤应从简单表达式开始,先观察结果再收紧范围,避免一次写得过窄,把全部候选过滤掉。

移动设备上也要关注探测频率。多个自动组、多个代理集合同时开启健康检查,可能产生重复请求;把间隔调得很短,并不一定换来更稳定的体验。优先精简重复测试,保留真正使用的候选范围,再对比后台表现。若遇到耗电偏高,可接着查看手机端后台与省电排查,不要仅凭一次电量变化判断内核存在故障。

六、规则顺序、语法与规则集

规则模式按从上到下的顺序匹配,命中后就交给对应策略,不会继续寻找“更精确”的后续规则。因此,例外通常放在前面,范围较大的规则放在后面,最后用 MATCH 接住剩余请求。规则名称相似并不表示范围相同;匹配某个域名、匹配它的子域和匹配一段字符串,需要选择不同类型。

域名规则与地址规则分开理解

DOMAIN 匹配完整域名;DOMAIN-SUFFIX 匹配域名本身及其子域;DOMAIN-KEYWORD 按关键字匹配,范围更宽,容易误伤。需要给一个明确站点设置去向时,优先用完整域名或后缀,不要只因为短就使用关键字。规则里的域名不填写协议前缀,也不填写网页路径;某个 URL 的具体页面通常不能靠域名规则单独区分。

rules:
  - DOMAIN,internal.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,代理出口
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,代理出口

示例中内部站点先直连,其他 example.com 请求再交给代理组。如果交换前两条,内部站点就会先命中大范围后缀规则。IP-CIDR 用于地址段,IPv6 可使用对应的 IP-CIDR6。no-resolve 表示不要仅为评估该 IP 规则而主动触发域名解析,并不表示整个请求不需要 DNS;当目标本身已有地址时,仍可按地址判断。

规则类型匹配对象使用提醒
DOMAIN完整域名适合少量明确例外
DOMAIN-SUFFIX域名及子域不要把 URL 路径写进来
IP-CIDRIPv4 地址段区分解析触发和地址匹配
RULE-SET外部规则集合核对集合名称与内容格式
MATCH剩余所有请求通常置于规则末尾

规则集的 behavior 必须匹配文件内容

规则集合适合把较长的域名列表独立维护。domain 用于域名集合,ipcidr 用于地址段集合,classical 用于带规则类型的经典规则集合。不能把一份完整 Clash 配置当成规则集,也不能把代理订阅地址填进规则集来源。下面使用本地的 domain 集合,主配置负责指定去向,集合文件只负责列出匹配范围。

# 主配置中的片段
rule-providers:
  工作域名:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/work.yaml

rules:
  - RULE-SET,工作域名,代理出口
  - MATCH,DIRECT
# ./rules/work.yaml
payload:
  - "example.com"
  - "+.example.org"

本例中 example.com 为明确域名条目,+.example.org 表达该域名及子域范围。经典规则集合则可以写 DOMAIN-SUFFIX,example.org 等带类型的条目,但不要在条目里再次添加策略目标;由主配置的 RULE-SET 指定目标。HTTP 规则集还需要更新间隔与缓存路径,首次下载失败时应检查是否已有可用缓存,不能假定更新失败必然中断全部规则。

根据连接记录检查实际命中

修改规则后,重新发起目标请求,在连接页面查看域名、命中规则和策略链。浏览器页面可能同时访问登录、图片、接口等多个域名,只修改地址栏中的主域名未必足够。先找出真正失败的请求,再增加最小范围的规则;不要直接把一个宽泛关键字全部送到同一出口。应用内加密 DNS、连接复用或仅以 IP 建立连接,也可能影响域名信息的可见性。

进程规则可以用于桌面应用分流,但需要内核能够获取进程信息,且不同系统权限与流量入口的表现可能不同。仅在自己的平台验证后再使用,不要把进程名当作跨平台通用标识。涉及 GEOIP 或地理分类的规则,还依赖相应数据文件和更新状态。先使用几条明确的域名规则证明分流链路正常,再引入更大的集合,排错会清楚得多。

七、覆写、合并与订阅更新

覆写的目标是让个人设置独立于远程订阅,而不是再维护一份内容几乎相同的大文件。常见需求包括固定本机端口、给内网站点添加例外、增加稳定策略组,以及修改 DNS。不同客户端的覆写格式和执行顺序并不统一,必须先确认界面提供的是字段替换、递归合并、规则前置,还是脚本处理;不要把一种客户端的控制键当成 mihomo 原生字段。

先确定修改哪个来源、作用于哪些配置

一般可以把处理链理解为:获取远程内容,应用客户端的转换或扩展,执行个人覆写,再交给内核。实际顺序可能还包括全局设置和运行时修改,应以客户端的生效配置为准。只有单份订阅需要的例外,优先绑定到对应 Profile;所有配置都需要的本机设置,才考虑全局作用域。范围过大可能让另一份订阅引用不存在的组。

新增覆写前先复制原配置,记录当前模式、组选择和能够复现的测试目标。随后只改一类字段,例如先固定 DNS,不要同时调整节点和规则。加载成功后比较源文件与最终配置:字段值是否按预期改变,原有列表是否还在,目标组有没有被删除。确认结果后再做下一步,这比看到“保存成功”就一次加入所有修改更可靠。

标量覆盖与列表合并不是一回事

标量如 mode 往往采用后写值覆盖前写值;映射如 dns 可能递归合并,也可能整体替换;列表如 rules 则尤其容易发生整段替换。即使两个客户端都把功能叫“合并”,行为也未必相同。下面展示的是语义上的前后对照,不是可直接粘贴到所有客户端的覆写语法。

订阅原始规则

rules:
  - DOMAIN-SUFFIX,example.org,代理出口
  - MATCH,代理出口

希望得到的最终规则

rules:
  - DOMAIN,intranet.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,代理出口
  - MATCH,代理出口

这里的需求是把一条例外放到前面,并保留原有规则。如果客户端只支持列表替换,就必须明确构造完整结果;如果提供规则前置功能,使用该功能更适合。单纯向文件末尾再添加一个 rules 键,不会自然实现“前置”。也不要依赖 YAML 锚点完成跨文件列表拼接:锚点主要服务于同一文档中的引用,不能代替客户端的业务合并流程。

修改对象需要确认的行为检查结果
端口、模式是否被界面再次接管最终值与运行状态一致
DNS 映射递归合并还是整体替换必要的解析器字段仍存在
规则列表前置、后置还是替换例外在前,兜底在后
策略组列表按名称合并还是重新创建引用目标有效,成员未丢失

同名组与动态节点要一起考虑

订阅中的组名可能变化。如果个人规则长期引用某个服务方组名,更新后就可能出现找不到目标。可以自行建立名称稳定的业务组,并让它引用代理集合;也可以在客户端明确支持的脚本中按条件构造成员。脚本应处理空节点列表和名称冲突,不能假定每次下载都一定有相同节点,更不能在找不到候选时静默选择一个未经确认的出口。

个人覆写里尽量不重复保存服务方凭据,这样订阅更新密码时不需要维护两处。若必须手工节点与订阅节点并存,使用不同名称并说明来源。排查合并失败时先停用个人扩展,确认原订阅能加载,再逐项恢复;如果原始订阅本身已经损坏,应先解决来源问题。关于顶层结构的补充拆解,可阅读config.yaml 逐段解析。

八、配置验证、定位与恢复

验证分成三层:文件能解析、内核能接受、请求按预期工作。YAML 语法正确只通过第一层;字段不受支持、组名不存在或规则集格式不符,仍可能被内核拒绝。内核成功启动也不表示所有远端都可达。按照这三个层次检查,可以避免把启动错误当成网络错误,也能减少无意义地反复重装客户端。

先做静态检查,再测试运行链路

如果已安装 mihomo 命令行内核,可在配置所在目录执行测试命令。Windows 使用对应可执行文件名称,其他系统根据实际安装路径调用;下面假设当前目录已经放置可执行内核和 config.yaml。命令会检查配置,但不能证明服务方账号有效、所有远程资源可下载或每条业务规则都符合预期。桌面客户端用户也可以使用界面提供的配置检查功能。

# Linux / macOS:在测试目录内执行
./mihomo -t -d . -f ./config.yaml

# Windows PowerShell:在测试目录内执行
.\mihomo.exe -t -d . -f .\config.yaml

相对路径问题应优先用明确的工作目录解决。-d . 指定当前目录作为配置工作目录,规则集和代理集合引用的文件也要在对应位置。不要为了通过测试而随意移动正在运行的客户端数据目录。独立测试时复制必要文件到单独目录,既方便确认路径,也能避免调试过程影响主配置和缓存。

现象优先检查下一步
提示行号或解析失败缩进、引号、冒号和重复键查看报错行及其前一段
找不到代理或组名称和集合引用检查最终配置中的实际定义
无法监听端口端口占用、地址与权限关闭冲突程序或统一更换入口
连接超时或握手失败DNS、远端地址、协议参数分开测试解析与建立连接
只有部分网站失败命中规则、实际出口与相关域名比较直连和代理路径

日志只围绕一个可复现请求阅读

需要详细日志时暂时把 log-level 调为 debug,关闭无关应用,再访问一个明确目标。先看请求是否进入内核,随后看匹配规则和策略链,最后看连接阶段错误。若根本没有请求记录,问题可能在系统代理、应用代理设置或 TUN 接管,不应先修改远端节点。若已有正确策略链,再检查解析、认证与 TLS。

不要把每条错误日志都当成同一个故障。后台更新规则集失败,与当前网页通过现有缓存正常访问可以同时发生;单个测试地址失败,也不表示所有业务请求都失败。分享日志时保留错误上下文和时间顺序,但删除订阅链接、访问凭据及不希望公开的域名。只截取一句“超时”通常无法判断失败发生在解析、连接还是握手阶段。

用对照测试确认修复,而不是凭感觉判断

端口入口可通过明确指定 HTTP 代理来测试,例如下面命令只验证请求是否能经本机混合端口发出。它不证明整个系统已被接管,也不会自动测试 UDP。命令执行前确认内核正在监听对应端口;若出现连接被拒绝,先检查本机服务与端口,不必立即更换订阅。测试目标也应选择当前网络中有明确预期的站点。

curl -I --proxy http://127.0.0.1:7890 https://example.com

接着分别访问应直连和应代理的目标,在连接页面核对结果。规则修改后要创建新连接,DNS 修改后要考虑旧缓存,策略组切换后要观察实际链路。每次记录“改了什么、测试什么、看到什么”,只保留能够解释效果的改动。如果问题仍然无法定位,可按节点超时排查顺序继续缩小范围,或在帮助中心查找相应现象。

恢复顺序与后续维护

恢复时先停用新加的覆写,再切回已验证的 Profile;若仍异常,核对系统代理和 TUN 是否残留了不匹配的入口。不要同时删除全部配置、缓存和日志,那会丢失对照依据。客户端选择可优先考虑 Clash Plus,再按系统和功能需求比较其他选项;安装入口统一在客户端下载页。旧客户端缺少字段支持时,先确认内核能力,而不是不断调整缩进。

配置稳定后,把调试日志恢复为常用级别,移除无效测试条目,保留简短的修改说明。备份应同时涵盖个人覆写与必要的本地集合文件,单独保存订阅链接不能还原所有个人规则。后续每次更新只抽查几个固定场景,就能比较快地发现规则顺序、组成员或 DNS 路径变化。需要重新走一遍连接流程时,再回到快速上手教程,本页则继续作为字段查阅入口。