Clash 配置文件参考
本页用于查字段、核对引用和阅读内核实际加载的配置。首次安装或导入订阅,先看快速上手教程;连接跑通后,再回到本手册修改设置。下文以 mihomo 为准,涉及外部服务的示例会注明运行条件。
YAML 结构与配置入口
顶层字段、映射与列表
内核接收的是一份以映射为根的 YAML 文档。端口和模式写成顶层键;DNS 写成一个映射,解析器地址再写成这个映射下的列表。节点、策略组和规则各有自己的顶层键。判断一个字段应放在哪里,先找它的父级,再看父级接收的是键值对还是列表。仅把一个字段缩进到视觉上接近其他设置的位置,并不会让它自动归入正确模块。
同级字段保持相同缩进,推荐每层用两个空格。列表用短横线开头,短横线后留一个空格。列表里的每个节点都是一条记录;节点的名称、类型和地址属于同一条记录,不能分别写成三条列表项。规则则不同:每条规则通常是一行字符串。逗号分隔的是规则字符串内部的字段,不能据此把它拆成多个 YAML 列表项。
数字端口写成数值,开关写成 true 或 false,不要统一套上引号。名称或长参数可使用引号;当值中出现可能被解释成注释或键值分隔符的字符时,尤其要保留引号。例如,未加引号的名称包含空格后紧接井号,井号之后的文字可能消失,策略组引用这个名称时就会找不到目标。空列表 [] 和空映射 {} 也不是同一种值。
最小基线与名称引用
下面的基线只开放本机混合代理端口,所有交给该入口的流量都使用内置直连出站。它不依赖订阅或额外资源,适合先验证本机能否通过代理入口访问原本就可达的站点。这份配置不是加密代理方案,也不会改变未接入内核的应用流量。若本机已有其他客户端占用该端口,应先选择一个空闲端口,并同步更新测试端。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
从这个基线增加策略时,数据关系可以沿着一条链查:规则引用策略组,策略组引用节点、其他策略组或内置出站,节点描述实际的连接方式。也可以让规则直接指向内置出站。引用按名称绑定,不按列表中的位置绑定。改一个节点名时,要检查所有策略组;改一个组名时,还要检查规则和引用该组的其他组。名称相似但多了空格,也不算同一个对象。
订阅、配置文件和代理提供器的内容不一定能互换。客户端的订阅导入功能可以取回并处理完整配置,也可能按自己的规则生成最终配置。代理提供器载入的是节点集合,供策略组从中选取;仅有节点列表并不等于具备顶层监听和规则的配置。复制一段内容前先看根键。若根键是 payload,还要确认它属于哪类资源,不能当成主配置直接启动。
区分源配置与实际生效的配置
用图形客户端时,至少区分订阅原文、本地覆写和交给内核的最终配置。界面开关可能参与生成最终文件,也可能通过运行时接口修改内核状态。若订阅一更新,手改的内容就消失,通常应把自定义项迁到客户端支持的覆写位置,而不是反复编辑缓存文件。具体入口按客户端确认;首次选择客户端可从安装包页的首推项 Clash Plus 开始。
中文注释可以解释改动目的,但内核不会用注释解决引用冲突。同一映射下不要重复同名键。部分解析器会直接报错,另一些可能只保留其中一个值。重复写两段规则并不能实现追加;应整理成一个列表,按希望匹配的先后次序排列。保存后先检查实际结构,再核对界面是否选择了正确的配置。
只根据编辑器颜色判断是否合法并不可靠。语法着色能指出一部分缩进和引号问题,却不知道组名有没有定义,也不一定知道当前内核支持哪些字段。遇到加载错误,先从报错位置向上找到最近的父键,确认列表层级和字段类型;语法通过以后,再检查业务引用。这样能避免一边改拼写一边改策略,最后无法判断是哪一步修正了问题。
通用端口、监听范围与运行模式
选择入口并确认实际监听
端口字段描述内核在本机接收请求的入口,不是远端节点所在的服务端口。混合端口可以接收 HTTP 代理和 SOCKS 请求,适合两种应用共用一个地址。若应用明确要求各自独立的入口,可以分别配置 HTTP 和 SOCKS 端口。多个监听入口应使用不同端口,不要把三个字段都填成同一数值。
| 字段 | 控制对象 | 检查要点 |
|---|---|---|
mixed-port | HTTP 与 SOCKS 混合代理入口 | 应用仍需选择与自身相符的代理协议。 |
port | HTTP 代理入口 | 代理 HTTPS 网站不等于把本地入口填成 HTTPS 代理。 |
socks-port | SOCKS 代理入口 | 确认应用提交的是目标域名还是已经解析的地址。 |
allow-lan | 是否允许局域网连接本地代理入口 | 仅本机使用时设为 false。 |
bind-address | 允许局域网连接时的绑定地址 | 需要共享时明确选择接口地址,并检查访问范围。 |
external-controller | 内核控制接口 | 它不是代理端口,也不应随代理入口一起对外开放。 |
下面的例子给两类入口分配不同端口。若客户端已经接管这些字段,应在界面里写入对应值,或者核对覆写后的最终文件。配置里出现端口号,不代表进程已经成功绑定。旧实例仍在运行、另一个工具占用了地址、系统限制进程监听,都可能让端口无法使用。出现端口冲突时先定位占用进程,再决定关闭旧实例还是改端口。
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
本机应用一般填回环地址 127.0.0.1,再填该协议对应的端口。验证时先查监听日志,再用一个能手动配置代理的应用发出请求。如果该应用成功而其他应用没有连接记录,优先检查其他应用是否读取系统代理,或是否有自己的代理选项。不要仅凭代理图标亮起,就认定所有应用已经通过相同入口。
客户端的系统代理开关通常是写入系统层的代理设置,是否采用由应用决定。TUN 则是在网络接口和路由层接管选定流量,通常还涉及系统授权。两者解决的是流量如何进入内核,和进入后选哪个出站是两回事。单独改变 mode 不能开启系统代理,也不会替代 TUN 的接口设置。首次定位问题时,先固定一种接入方式。
区分规则、全局与直连
rule 模式按规则顺序选出站,适合有明确分流需求的配置。global 模式使用全局选择,不按规则列表逐条匹配;使用前要确认客户端当前选中了哪个出站,不能想当然地认为一定在走某个远端节点。direct 模式则令已进入内核的流量直连,不等于关闭本地监听,也不等于还原系统代理设置。
同一网站在规则模式与全局模式下结果不同,先读两次连接记录的实际出站。全局模式下成功,只说明当次选用的路径可用;不能据此判定整份规则错误。也可能是规则命中了直连、所引用的组处于另一个选项,或者两次进行了不同的域名解析。若在直连模式测试,注意该站点本身是否允许从当前网络访问。
日志级别建议平时保持 info。定位问题时可短时提高到 debug,复现一次后还原。日志中的目标地址和配置名称可能反映使用环境,共享时只截取与问题相关的记录。区分「请求抵达入口」「规则选中出站」和「远端完成连接」这三个阶段;只有第一步完成时,不能把问题直接归因于目标站。
限定本机与局域网的边界
需要其他设备连接时,再考虑启用局域网访问。远端设备要使用运行内核的主机在局域网中的地址,不能填写它自己的回环地址。开放前先确定作用接口和防火墙范围,测试后不用就关闭。控制接口应单独判断:能够通过代理访问网络,不代表调用者需要控制内核。不要为排查本机连接而把代理和控制端口同时改成在所有接口监听。
端口有意变更后,还要检查系统代理、浏览器独立设置和终端环境变量是否仍保存着旧值。遇到重启前可用、重启后不可用的情况,记录重启前后的实际监听地址和配置名称,确认启动的是同一个实例。对于系统设置入口和平台授权的差别,可先查快速上手,再回到这里对照内核字段。
DNS 字段与 fake-ip 行为
确认请求是否经过内核解析
在配置中启用 DNS,意味着内核启用自己的解析模块;它不会仅凭这个开关接管操作系统上的所有 DNS 查询。浏览器可能使用自身的加密 DNS,应用也可能把解析后的地址交给代理。系统代理与 TUN 的接入方式不同,是否能收到 DNS 请求也取决于具体设置。排查前先确定发起查询的是哪个应用,以及查询实际进入了哪个解析器。
DNS 配置中的 nameserver 是一般域名的解析器列表;nameserver-policy 可以为指定域名选择解析器。default-nameserver 用于启动阶段解析 DNS 服务器的主机名等引导场景,不是对所有请求逐个尝试的备用列表。使用带主机名的加密解析地址时,要保证用于引导的解析器在当前网络中可达,否则配置能读入,首次查询仍可能超时。
proxy-server-nameserver 用于解析代理节点的服务器域名。它解决的是「还没拨到节点,怎样先拿到节点地址」的问题,不等同于普通网站解析。如果节点是域名,且解析它所依赖的上游又只能通过该节点访问,就会出现循环依赖。发生这种情况时,先为节点地址准备一条在建连之前确实可用的解析路径,再决定一般网站查询走哪条路径。
地址映射、过滤与本机查询示例
在 fake-ip 模式下,内核可以为收到查询的域名分配一个虚拟地址,并保存域名与该地址的映射。连接以该地址回到同一个内核时,内核有机会恢复域名,按域名规则进行判断。这里的虚拟地址不是目标服务器公开的真实地址,也不能脱离当前内核的映射单独使用。若查询经过内核、随后连接却直接交给系统路由,应用可能尝试连接一个不可达的虚拟地址。
mixed-port: 7890
allow-lan: false
mode: rule
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- 'localhost'
- '+.lan'
nameserver:
- system
rules:
- MATCH,DIRECT
示例在回环地址开放一个独立 DNS 端口,普通查询交给系统解析器。它适合手动把测试查询发往该端口,不会替你修改系统 DNS。使用这个例子时,要保证系统解析器不会把查询重新转给这一个监听入口。如果已有工具使用相同端口,先换一个空闲端口。也要核对虚拟地址段是否与本机现有路由或其他代理实例的虚拟网段冲突。
fake-ip-filter 在示例的默认过滤行为下,将列出的名称排除在虚拟地址分配之外。把某个本地域名加进列表,解决的是「需要取得真实解析结果」的问题,并不会凭空提供该域名的记录。如果某个内部后缀必须由组织的解析器回答,还需确认系统解析能返回它,或者为该后缀另行配置可达的解析器,并验证路由允许访问该解析服务。
另一种增强模式是 redir-host,通常向应用返回真实地址。是否还能用域名规则命中,要看域名信息是否被代理请求携带,或内核能否从实际接入链路获取它。不能把切换模式当作修复所有域名匹配的开关。应对同一目标同时检查 DNS 应答和连接日志;只有前者变化,不能说明后者已经命中预期规则。
区分解析失败、缓存和后续连接失败
如果系统装有支持指定服务器和端口的查询工具,可以发起下面的两条查询。第一条明确走示例监听端;第二条走工具默认的系统解析路径。记录应答状态和地址类型,而不是要求两边的地址值相同。在虚拟地址模式中,结果不同可以是预期行为。若监听没有收到请求,则先排查所用地址和端口,不要先更换上游。
dig @127.0.0.1 -p 1053 example.com A
dig example.com A
如果存在应答但连接仍失败,检查连接是否进入保存映射的同一实例,再观察域名规则、策略组和出站日志。切换配置后,浏览器和操作系统可能继续使用已缓存地址,已建立的连接也可能复用。用新连接复测,必要时只清理测试应用的相关状态。每次只改一个因素,避免同时切换 DNS、开启流量接管和更换节点。
启用双栈的环境还应分别观察 IPv4 与 IPv6。DNS 的 ipv6 选项控制内核 DNS 对 IPv6 查询的行为,不等于禁用系统的 IPv6 栈,也不能代替对 IPv6 接入路径的检查。诊断时记录查询类型与实际目标地址;一个地址族连接成功,不代表另一个地址族沿用了相同的策略和路线。
代理节点字段与提供器
按协议组织一条出站记录
proxies 是节点记录的列表。常见记录包含名称、协议类型、服务器和端口,协议专用字段则根据实际服务填写。名称用来引用和显示,地址和端口决定连接目标。地址应是主机名或地址本身,不能把带方案和路径的订阅链接填进去。订阅地址用于获取或生成配置,节点地址用于建立一条出站连接,两者在加载流程中承担不同职责。
下面是接入已有本机 SOCKS 服务的节点示例。它要求另外一个 SOCKS 服务已独立监听在本机 1080,并允许此客户端访问;使用示例不需要改动那个服务。内核接收入站的端口是 7890。不要把该节点的服务端口改成同一内核自己的混合入口,否则请求可能经出站折返到入站,造成重复处理或连接失败。
mixed-port: 7890
allow-lan: false
mode: rule
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
rules:
- DOMAIN-SUFFIX,example.com,Local-SOCKS
- MATCH,DIRECT
该示例只把匹配示例域名的连接指向节点,其他连接仍直连。没有现成的 SOCKS 服务时,可以先按最小基线验证入口;不要把节点示例的失败当成 YAML 载入失败。节点出现在客户端列表里只说明记录已读入。要验证它能工作,应分别确认地址可达、协议握手完成、目标请求经该出站返回。三步中任何一步失败,都可能在界面上简化为超时。
切换协议时,不要只更改 type 并沿用所有旧字段。以 Shadowsocks 为例,密码与加密方法需要和服务端一致;采用 TLS 的其他协议还可能有服务名称、证书校验和传输方式等要求。配置结构相似并不表示握手兼容。遇到证书错误,先核对服务名称、系统时间和服务端证书,不要把关闭校验当成常规修复。
udp 用来声明部分节点是否启用 UDP 转发,它不会让不支持 UDP 的服务自动具备该能力。应用能经节点访问网页,只验证了当次网页连接,不能推出语音或其他 UDP 应用也能工作。排查时应同时检查入站是否承载这种流量、策略是否选到兼容出站、服务端是否能实际转发。不要用网页是否打开替代协议层检查。
代理提供器的路径与装载顺序
有一批单独维护的节点时,可以使用 proxy-providers。主配置声明资源来源,策略组用 use 引用提供器名。下面演示本地文件方式;需要事先在内核工作目录建立列出的文件。示例继续使用前述独立 SOCKS 服务,实际接入前仍需确认该服务已启动。文件不存在时,先修正相对路径或启动时选用的工作目录。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-providers:
local-source:
type: file
path: ./local-proxies.yaml
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
use:
- local-source
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
打开策略组确认提供器成员已出现,再手动选中它。不要只看规则记录显示组名;组里的当前成员若仍是直连,就没有验证节点。若改为 HTTP 提供器,应确认取回的是内核能识别的节点资源,不是登录页面,也不是另外一份完整配置。提供器工作路径和更新周期应独立管理,避免多个资源共用同一个缓存文件。
检查资源更新时,把「下载成功」「解析成功」「成员可用」分开记录。更新可能删除原成员,也可能以同名记录替换其服务端参数。若用户手动选中的成员在更新后消失,先看提供器的新成员列表,再看组当前选择;不能仅对照旧截图。分享配置片段时去掉订阅地址、认证字段和内部主机名,仅保留能够说明结构的字段。
策略组类型、成员与健康检查
策略组负责选出站
proxy-groups 定义出站选择策略,不定义新的代理协议。组名是规则能够引用的目的地,成员可以是单个节点、内置出站、其他组或来自提供器的节点。组可以让规则保持稳定:替换或调整成员时,引用该组的规则不必同步改写。先给组定义明确的职责,再决定成员来源;不建议用多个名称仅差一个字符的组表示不同用途。
| 类型 | 选择方式 | 观察重点 |
|---|---|---|
select | 由用户选定成员 | 确认客户端是否恢复了上次手动选择。 |
url-test | 根据探测结果选择成员 | 探测地址、探测周期和切换容差会影响选择。 |
fallback | 按列表优先顺序选择可用成员 | 主备顺序由成员列表体现,不按延迟从小到大排序。 |
load-balance | 按配置的策略分配连接 | 连接可能落到不同出站,需确认业务是否要求固定出口。 |
静态成员写在 proxies 下,内容是已声明的名字,不是把整条节点记录再次嵌入组内。提供器写在 use 下,内容是提供器名字,不是资源地址。把节点名写入 use,或把提供器名误写入 proxies,都是引用层级错误。迁移配置时先保留一个简短的静态组验证引用,再逐步加入提供器成员。
下例复用上一章的 Local-SOCKS 节点;请把原文件的规则列表替换为这里的规则,并把组定义加到顶层。此例保留直连作为手动比较选项。默认匹配规则写在末尾,确保只有选择的域名进入手动组。测试时分别选择两项并建立新连接,比较日志里最终成员是否随选择变化。
proxy-groups:
- name: PROXY
type: select
proxies:
- Local-SOCKS
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
组嵌套适合把自动选择放在手动入口下面,例如让一个手动组同时包含自动组和固定节点。引用方向必须可追踪,不能让甲组引用乙组、乙组又引用甲组,也不能引用自身。遇到循环引用,先画出「外层组指向内层组」的关系,从每个规则目标顺着读到节点或内置出站;一旦遇到已走过的同一个组,就应调整结构。
探测结果不能代替业务验证
若要把前面的手动组改为主备组,可以采用下面的组定义,规则仍引用同一个组名。interval 的单位是秒。示例用公开的文档域名说明探测字段的写法;实际使用时应选用设备获准访问且返回行为稳定的探测地址,并确认通过各个候选出口都能正常访问。它测的是请求到指定地址的结果,不是整个互联网的可用性。
proxy-groups:
- name: PROXY
type: fallback
proxies:
- Local-SOCKS
- DIRECT
url: https://example.com/
interval: 300
这里使用直连作为后备,仅用于对照行为。如果某项业务要求固定通过特定出口,则不应把直连加入该组作为自动后备;候选全部不可用时,应按业务要求处理失败。也不要仅为了看到更多可用结果,就把互不等价的出口混在一个组里。组的可用性既取决于有没有能连通的成员,也取决于该成员是否满足目标访问条件。
对 url-test 组设置切换容差,可以减少探测时间轻微起伏导致的频繁切换。探测间隔太短会增加额外请求,也更容易把偶发波动当成稳定差异。若一次测试发现某成员较慢,应先看变化是否持续,再看业务目标的问题能否复现。探测成功但应用失败时,比较两者的域名、协议和选择的最终出站,而不是先缩短探测周期。
提供器也可维护自己的健康检查。排查时应区分「资源中有哪些成员」「这些成员的探测状态」「策略组当前选了谁」三份信息。策略改变一般影响新连接,应用维持旧会话时不会立即表现出变化。若客户端启用了选择记忆,重载配置后也可能恢复先前成员。必要时重新建立会话,并以该次连接日志为准。
规则语法、匹配顺序与规则集
从第一条命中规则读起
在规则模式下,内核按列表顺序检查规则,并使用第一条匹配的结果。常用语法是「类别、匹配条件、目标」,个别类别可以再带选项。MATCH 不需要匹配条件,只跟目标。宽泛规则在前,后面更具体的规则可能永远没有机会命中;因此把例外放在通用规则之前,并保持列表末尾的兜底与实际期望一致。
下例不依赖远端节点,通过直连和拒绝区分几个分支。精确名称先直连,同一后缀范围内的其他名称再匹配拒绝。目标为回环地址的连接命中地址规则时直连,其他请求落到兜底。示例只改变进入该内核的请求;直接按系统路由发出的流量不会因为配置中写了拒绝条目就被拦截。
mode: rule
rules:
- DOMAIN,example.com,DIRECT
- DOMAIN-SUFFIX,example.com,REJECT
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- MATCH,DIRECT
DOMAIN 检查完整名称;DOMAIN-SUFFIX 用于该域名及其子域名,不是随意匹配字符串末尾。若仅想影响一个主机名,不要升级成后缀规则,以免把同一主域下的其他服务一起改变。DOMAIN-KEYWORD 按关键字匹配,范围更宽,最好先核查会包含该关键字的其他名称,再决定是否采用。
IP-CIDR 用于 IPv4 地址范围,IPv6 使用 IP-CIDR6。对于需要目标地址的规则,如果连接只提供域名,内核可能需要先查地址。no-resolve 用来避免仅为该规则额外发起解析;它不会抹掉请求已有的目标地址。不要把它当成关闭全局 DNS 的指令。如果命中依赖解析,先确认该条规则是否允许解析,再确认解析结果是否在声明的网段内。
GEOIP 与 GEOSITE 分别依赖内核能读取的地理地址和域名分类数据。它们表示数据中的分类,不是对某个连接位置或归属的实时测量。两个环境使用不同数据文件时,即使规则文本相同,命中结果也可能不同。定位这类差异时记录数据来源和客户端启用的配置;不要用单个站点的行为推断整份分类表。
把规则数据与处置动作分开
当一批匹配条件需要独立维护时,可以用 rule-providers。主文件用 RULE-SET 指定某个规则集及其处置动作,资源本身只声明条件。下面的本地实例用域名集合,将指定域及其子域名指向直连。创建文件后再加载配置;相对路径应按内核的工作目录确认,不要按打开编辑器的目录猜测。
mode: rule
rule-providers:
reference-domains:
type: file
behavior: domain
format: yaml
path: ./reference-domains.yaml
rules:
- RULE-SET,reference-domains,DIRECT
- MATCH,REJECT
payload:
- '+.example.com'
这组示例的末条规则会拒绝未在列表中的目标,仅宜用于有意测试允许范围的配置,不应直接替换日常规则。behavior: domain 接收域名形式的条件;ipcidr 用于地址段;classical 可承载由规则类别与参数组成的条件。不要把 DOMAIN-SUFFIX,example.com,DIRECT 整行写进域名集合,也不要把出站名写进由主文件统一指定动作的条件。
用连接记录验证命中依据
发现目标落入兜底时,先看客户端记录的目标是域名还是数值地址。应用若自行解析并只传地址,域名条件未必有输入可用;这不是简单调整规则顺序就能修复的问题。接着看是否存在更靠前的宽泛规则,最后确认规则集文件实际加载成功。若连接日志已经显示正确的匹配规则,再转向组成员和出站检查,不必继续调整命中条件。
一张网页可能同时访问主文档、静态文件和其他服务,每条连接独立匹配。主文档打开不代表该页面的所有资源均沿相同出站,某个资源失败也不一定需要修改整个主域的规则。先选一条失败连接,记录目标、命中规则和最终成员,再决定是否增加例外。需要用术语定位字段时,可对照名词解释中的分流规则分类。
覆写、合并与更新后的差异
先确定谁执行合并
覆写是客户端生成最终配置的过程,不是内核看到两个同名键就会执行的通用操作。不同客户端对映射、列表和空值采用的合并方式可能不同,也可能分别提供界面覆写与脚本处理功能。修改之前先确定用的是哪一个入口,以及它作用于单份配置还是全部配置。第三方教程中的覆写专用键不能直接移到主 YAML 里当作内核字段。
建议把改动分为标量、映射和有顺序依赖的列表。端口与模式通常只需替换单个值;DNS 是映射,覆盖整块时可能丢掉原来的解析器或过滤项;规则是有序列表,追加、前置和全量替换的结果不同。即使客户端说明「深度合并映射」,也不能由此推断它会追加列表。检查目标是实际输出,不是覆写文件看起来有多少行。
| 数据类型 | 修改示例 | 确认结果 |
|---|---|---|
| 标量 | 将 mixed-port 改为其他空闲端口 | 最终配置、实际监听和应用指向一致。 |
| 映射 | 修改 dns.enhanced-mode | 仍保留需要的解析器和策略映射。 |
| 有序列表 | 在 rules 中加入例外 | 例外位于覆盖其范围的旧规则之前。 |
| 对象列表 | 给 proxy-groups 增加一组 | 原组仍存在,名称唯一,成员引用均有效。 |
下面展示修改前后的完整文件。目标是调整混合端口,并让示例域名在兜底之前命中拒绝。这里给出的是人工合并的结果,不依赖特定客户端理解某种补丁语法。即便客户端能生成同样的内容,也要验证输出中的规则只有一份,例外位于第一条,原有模式和监听范围没有改变。
mixed-port: 7890
allow-lan: false
mode: rule
rules:
- MATCH,DIRECT
mixed-port: 7892
allow-lan: false
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,REJECT
- MATCH,DIRECT
如果客户端仅支持把新规则追加到现有列表,前例中的新增规则就会落到 MATCH 后面,不能命中。应改用明确支持前置的功能,或整理完整规则列表后整体替换。使用整体替换时也要承担维护责任:订阅新加入的重要规则不会自动进入这份自定义列表。更新后应该重新比较上游规则,而不是只核对配置还能启动。
重命名、空值与 YAML 合并键
新增策略组前先确认名称不冲突。若覆写器按名称合并对象,同名组可能变成替换旧组;若只追加对象,结果可能出现无法加载的重名组。删除节点、组或提供器之前,应逐项搜索对它的引用。规则目标为原组名时,只要继续保留同名组并提供有效成员,就不必同步修改全部规则;删除组本身则必须迁移引用。
带空值的字段也要区分。键后留空往往被解析为 null,它不表示「沿用原值」;空列表也不自动表示「不修改」。覆写器可能将它们解释为清空、替换或无效输入,不支持时还可能直接拒绝。若目标是保持订阅中的某个字段不动,通常应从覆写文件省略该字段,再核对最终文件;不要用空值表达未经确认的合并意图。
YAML 锚点与别名只适用于一份 YAML 文档的解析范围,不能让独立的覆写文件共享订阅原文里的锚点。某些解析器支持 << 合并键,它主要用于合并映射,不是规则列表的拼接运算,而且客户端经过读取和重新输出时可能展开或改变这种写法。跨端维护时,优先保留简单结构,并以最终导出的普通 YAML 为核对对象。
把订阅更新当作一次重新生成
更新订阅前保留上次可用的最终配置和本地覆写,分开存放。更新后先比较顶层端口和 DNS 映射,再看节点、组和规则三类引用,最后做同一目标的复测。若某一次更新导致问题,可以先暂时关闭覆写,用原始配置验证,再只启用一项本地改动。这样能分别定位源数据变化、客户端合并变化和运行时选择变化。
迁移到另一个客户端时,也只移植能够确认含义的内核字段。相同的 mihomo 内核不保证两个界面使用同样的覆写顺序,也不保证配置目录和提供器路径相同。若需把旧配置迁移到 mihomo,可对照mihomo 内核与原版 Clash 的字段差异,再检查目标客户端实际采用的内核与配置入口。
配置校验、连接验证与常见问题
先验证文件,再进入运行检查
开始排查时先保留一份已知可用的配置,并为待测文件使用不同名称。在图形客户端中确认当前选中的配置,以及覆写后用于启动的配置。使用独立内核时,明确传入文件路径和工作目录。若同一系统有多个安装来源,还要确认终端调用的二进制与界面实际使用的内核是否相同;否则一边通过测试、另一边加载失败并不矛盾。
下面的命令适用于已经可以在终端运行 mihomo 的环境。示例假定当前目录下有 config.yaml;工作目录应能读取该配置依赖的数据和本地资源。测试通过只表明内核完成了本次配置检查,不证明所有监听端口都能绑定、解析器都可达,也不证明节点通过了协议握手。
mihomo -t -d . -f ./config.yaml
有报错时按阶段缩小范围。语法错误先查报错行和前一条记录是否漏写冒号、破坏缩进或未闭合引号;引用错误检查组、节点和提供器名称;资源错误核对工作目录、路径和文件形状。不要同时更改文件命名、规则与订阅地址。每次修正后重复同一个检查,直到确认报错阶段已经推进,再转向下一层。
按入口、匹配和出口逐层复测
启动后先确认本地监听,再指定代理入口发起一个简单的请求。下面要求混合端口正在 127.0.0.1:7890 监听,且当前策略允许访问目标。如果使用了前文端口覆写示例,应同步调整命令里的端口。若正在测试拒绝规则,则应把被拒绝视为预期结果,而不是看到请求失败就判定入口不工作。
curl --noproxy "" --proxy http://127.0.0.1:7890 \
--max-time 15 --head https://example.com/
上面的续行符用于常见的类 Unix 命令行环境;在不识别这种续行的终端里,把命令写在同一行,并使用实际的 curl 程序。--noproxy "" 清空本次命令的代理绕过名单,便于核对入口。请求出现目标服务器的响应,不意味着所有应用都会读取系统代理;这个测试只覆盖显式指定的线路,并且不依赖界面中图标的状态。
若没有新的连接记录,检查是否使用了正确的代理协议、地址与端口,以及应用是否绕过代理。若已有记录但命中的规则不对,核对当时的模式、请求提交给内核的目标形式和规则顺序。若匹配与选择都正确,再看出站握手、节点域名解析和目标服务的响应。每次记录目标、模式、匹配项与最终成员,这四项比只记「连不上」更有排查价值。
节点全部超时和只有一个节点超时,应分开判断。全部超时时先查共享的订阅、入口、解析与本机网络条件;只有一个节点异常时,可以保持同一入口与目标,对比另一成员。检查完成前不要频繁同时切换多个选项。需要按故障症状继续追查,可看节点超时排查顺序;需要重新配置系统接入时,回到快速上手教程。
常见配置问题
为什么载入成功后,客户端仍沿用旧端口?
先确认界面显示的新端口是否写入了最终配置,再检查是否完成重载和实际绑定。如果内核监听新端口,而应用还向旧端口发请求,应同步修改系统代理、应用代理选项或终端环境变量。若旧端口仍有服务响应,检查是否还有另一实例在运行,避免把旧实例的日志当成本次测试结果。
为什么规则命中了正确的组,结果仍与预期不同?
组名只说明入口策略。手动组可能恢复旧选择,主备组可能落到后备成员,自动组也可能因探测变化而选择另一项。先看该条连接最终走的成员,再核对组中的成员是否符合用途。选择更改后要建立新连接复测;继续复用原连接的应用可能暂时看不到变化。
为什么恢复 YAML 后,系统网络没有随之恢复?
系统代理、虚拟接口、路由和操作系统的 DNS 设置由相应的系统功能或客户端管理,不会仅因覆盖一个配置文件而撤销。在客户端界面按需关闭最初启用的接入功能,检查系统仍使用哪些设置,再以一个新请求验证。如果恢复旧配置前后都能复现,还应区分系统层状态与内核配置问题。