CONFIG.YAML / 字段手册

Clash 配置文件字段参考

从 YAML 载入到规则命中:字段类型、引用关系和生效范围。

使用指南负责首次导入和连接验证,本页负责按字段查找写法与排错依据。还没有可用配置时,先按指南走一遍;遇到端口、解析或分流问题,再用下方目录定位。本文以 mihomo 为参考,客户端界面的选项和覆写机制以实际产品为准。

01 YAML / STRUCTURE

YAML 结构、字段类型与引用

先读顶层,再读流量路径

Clash 配置的顶层是映射,不是一串按文件行号执行的命令。先把顶层字段当作入口索引:端口与运行模式决定请求怎样进入内核,DNS 段决定内置解析器怎样回答查询,节点段描述怎样拨号,策略组列出可以选择的出口,规则段决定连接交给哪个出口。把规则段移到文件开头,不会让规则先于内核初始化;把某条规则移到同一列表的开头,却可能改变最终分流。因此,比较两份文件时要区分顶层字段的位置与列表元素的相对顺序。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
  - name: 手动出口
    type: select
    proxies:
      - DIRECT
rules:
  - DOMAIN-SUFFIX,example.org,手动出口
  - MATCH,DIRECT

这份完整示例没有远端节点,适合先验证文件载入和本地入口。规则接到目标域名后,先尝试把连接交给名为「手动出口」的组;组里只有直连,其他请求也由末尾规则直连。用它测试时,网页能访问只说明这条直连路径可用,不代表已连接到代理服务器。要确认特定规则真的命中,应同时查看客户端的新连接记录,而不是凭页面显示是否成功倒推分流结果。已有代理软件占用示例端口时,先选用空闲端口,再让测试应用连接同一个端口。

区分同名字段的层级

同一个键在不同层级可以有不同含义。顶层的 proxies 是节点对象列表,而某个策略组里的 proxies 是成员名称列表。前者每项要写成一组属性,后者每项写一个名称。若误把节点对象缩进到组成员下面,即便文档仍是合法 YAML,内核也可能因收到错误的字段类型而拒绝加载。改完组名也要查找引用它的其他组和规则;只改定义不改引用,原本能读入的文档便可能无法应用。

字段数据形状编辑时先核对
mixed-port整数是否与客户端实际入口一致
dns映射各键是否缩进在同一个父键下
proxy-groups对象列表名称及所有成员是否可引用
rules字符串列表列表顺序是否符合匹配优先级

分开判断语法、配置校验和运行结果

语法错误先查缩进、引号和列表标记,字段错误再查类型与引用。用空格缩进,不用制表符;同一父键下对齐同级字段,列表行的连字符后留空格。值里有可能被解释成注释的井号,或有冒号加空格时,用引号标出字符串边界。端口、布尔开关应保留相应类型,只有原本就该是字符串的值才按需加引号。直接复制带格式的文字时还要注意全角冒号与弯引号,它们看起来相似,却不能替代 YAML 的语法符号。

配置报错给出的行号是解析器发现问题的位置,不一定是开始写错的那一行。遇到某行提示缺少键时,先回看上一项是否有未闭合的引号,或子项是否少缩进了一层。配置通过 YAML 解析后,再检查是否有重复顶层键、名称冲突或未知引用。同一个映射里出现两份规则键,不表示内核会把两个列表接起来;不同解析过程可能拒绝或覆盖其中一份。编辑时应把同一层的键收敛为唯一一处。

最后用运行结果确认修改落在了实际生效的文件上。客户端可能显示已下载的订阅副本,但当前载入的是另一份本地配置;也可能因新配置校验失败继续使用上一份。记录当前配置名称、应用时间和一条新连接的匹配结果,再与预期对照。旧连接有可能仍使用建立时的出口,切换配置后应重新发起请求。首次导入文件或订阅时,先按配置导入步骤确认当前启用项,再进入字段排查。

02 INBOUND / MODE

通用字段:端口、监听与运行模式

先确认应用连接的是哪个本地入口

入口端口描述的是应用到内核的这一跳,不是代理服务器端口。port 用于 HTTP 代理,socks-port 用于 SOCKS 代理,mixed-port 在同一端口接受两类入站协议。刚开始调试时保留一个入口更容易判断问题:浏览器或系统代理使用 HTTP 时,地址与端口必须对应 HTTP 或混合入口;支持 SOCKS 的程序才应使用相应的 SOCKS 设置。应用若同时保存了自动配置地址和独立的手动代理,先确认实际采用的是哪一个。

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

示例把混合入口留在本机使用。客户端的系统代理功能通常只是帮助系统设置指向内核的地址,并不意味着所有程序都会跟随。某些应用有独立网络设置,另一些服务从环境变量读代理地址,还有程序直接使用自己的连接方式。判断某程序是否走了代理,先单独发起一条新请求,再看客户端连接视图是否有对应目标。连连接记录都没有时,优先检查应用的代理设置、系统例外项和监听端口,而不是反复调换策略组。

同一监听先排除冲突,再调整可访问范围

同一个地址上的同一个端口不能随意分给多个同类监听。配置里同时给 HTTP 入口与混合入口填写相同端口,或者让两个客户端同时接管相同端口,都可能造成绑定失败。遇到启动日志报告地址已被占用,先核对失败的是混合入口、控制接口还是内置 DNS 的监听,不要一概修改节点端口。确认占用方后,停用不再使用的监听,或者为本配置选一个空闲值,并同步更新操作系统与应用中保存的代理地址。

本机用途保留 allow-lan: false 即可。若确有局域网共享需求,需另行核对允许范围、监听地址和防火墙规则,并在可信网络内验证访问来源。还要区分 external-controller 和转发入口:前者供面板或程序管理内核,后者才接收代理请求。界面能连上控制接口,只能说明控制通道可达,不能证明业务端口监听成功。遇到公共网络或不确定接入范围的环境,保持管理和代理入口仅供本机使用更容易控制边界。

模式决定是否用规则表,不决定谁会进入内核

规则模式按列表为进入内核的连接分配出口;全局模式使用全局策略中选定的出口,不按普通规则逐项匹配;直连模式让进入内核的常规代理流量走直连。三种模式改变的是内核内部的处理路径,不会自动替应用打开或关闭代理。排查时可短暂切换模式进行对照:若同一请求在直连可用、改走指定出口后失败,先检查该出口及其解析依赖;若只有规则模式走错出口,再回查命中项和组选择。测试完成后恢复原模式,避免后续误以为规则仍在生效。

日志级别应服务于一个明确的排查问题。平时保留足以识别启动失败的级别,需要定位连接时再短时提高详细程度,并缩小测试范围。一次只打开一个目标并记下时间点,区分启动错误、入站连接、域名解析与出站拨号。路径正常但页面仍慢时,还应区分首次建立连接与已有连接上的后续传输,不能只看单条日志便归因于端口。对外分享日志前,删去订阅地址、内网主机名和账户相关字段;保留错误类型和必要的端口信息即可。

03 DNS / RESOLUTION

DNS 配置:上游、引导解析与 Fake IP

先识别查询来自哪里

dns.enable 开启的是内核 DNS 模块,不等同于修改整个系统的 DNS。应用可能先向操作系统查询并把地址交给代理入口,也可能直接把目标域名交给内核处理。还有应用会启用自己的加密 DNS,不走系统默认路径。排查时要把「哪个组件发起查询」和「哪台解析器回答查询」分开记录。即便普通网页能打开,也不能据此判断所有应用用了同一个上游;同样,查询结果有地址也不表示访问该地址的连接已经成功。

dns:
  enable: true
  enhanced-mode: redir-host
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://cloudflare-dns.com/dns-query
  proxy-server-nameserver:
    - 1.1.1.1

示例用 redir-host 返回真实地址,用加密 DNS 处理普通查询,并显式区分引导上游和节点解析上游。该写法要求本机能访问示例解析器;受管网络应替换成管理员允许并且在当前链路可达的上游。default-nameserver 主要解决解析服务本身以域名表示时的引导问题。加密查询地址写成域名,却依赖尚未建立的加密查询来解析自己,就可能形成循环。引导地址使用可独立到达的数字地址,可把这一环从主解析路径中拆出来。

普通域名与节点域名不一定走同一条路

nameserver 是默认解析上游,nameserver-policy 可为指定域名选择不同的上游,proxy-server-nameserver 则用于解析代理节点服务器的域名。某个节点以域名而非地址填写时,内核需要先得到它的地址,才有机会建立通道。若解析该域名的查询又被安排通过尚未连通的节点,首次连接就可能卡住。诊断这类问题时,先验证节点域名能通过独立的解析路径得到结果,再验证得到的地址是否能建立连接。只反复改普通上游,很容易错过节点解析这一层。

内部服务解析宜用明确的域范围定向,不要把公司内部域名交给公共解析器试错。内外两套上游可能对同一个名称给出不同视图,公共上游未找到记录也不表示内部记录不存在。调整域名策略后,分别测试一个内部域名和一个外部域名,记录返回地址是否符合预期。切换网络时,原来可到达的内部 DNS 可能已经不可达;若内外名称同时失败,先恢复到可工作的最小配置,再逐项加入定向策略,而不是一次替换所有上游。

Fake IP 是映射地址,不是服务真实地址

fake-ip 模式向查询方返回合成地址。内核收到对这个地址的连接时,再根据映射恢复原始域名。要让这条路径成立,获取合成地址的应用所发出的连接必须能回到负责该映射的内核。若请求离开这一接管范围,或系统缓存了切换配置前的地址,应用可能拿到一个不能按普通方式路由的地址。遇到本地设备发现或内部服务异常时,应先确认环节是否适合合成地址,再考虑用 fake-ip-filter 对所需名称返回真实记录,避免把所有域名一起放入例外。

切换增强模式后,用同一应用重新发起查询和连接,避免缓存掩盖差异。可以分别检查三件事:查询是否得到回答,连接是否正确关联目标域名,规则是否按预期选到出口。第一项失败先看上游可达性;第二项失败先看应用的解析来源和接管范围;第三项失败才检查规则顺序。日志里若先出现解析超时,网页随后报连接失败只是下游症状。节点和系统代理也存在疑问时,可对照节点超时的分层排查顺序逐段缩小范围。

04 PROXIES / OUTBOUND

代理节点字段与连接边界

先把节点的显示名称与拨号参数分开

一个节点是一条出站连接的参数集合。name 是配置里的引用名,type 选择协议,server 与 port 标出实际拨号地址。节点名可以使用方便辨认的文字,但必须与策略组引用一致,且不应和其他出口名称冲突。给节点换展示名不会改变远端服务器,也不能修复拨号失败;反过来,替换了远端参数但保留原名,策略组通常仍会引用它。改配置前先明确是在改显示身份,还是在改实际连接条件。

proxies:
  - name: 本机测试出口
    type: socks5
    server: 127.0.0.1
    port: 1081
    udp: false
proxy-groups:
  - name: 节点核对
    type: select
    proxies:
      - 本机测试出口
      - DIRECT
rules:
  - DOMAIN-SUFFIX,example.org,节点核对
  - MATCH,DIRECT

这段示例依赖另一个已运行的本机 SOCKS5 服务,且该服务在示例端口接受连接。它不是内置节点,也不会启动服务。如果本机没有该服务,应保留直连用作对照,或将节点换成自己获准访问的代理。不要把服务器端口填成本配置自身的混合入口,那会让出站回到入站,不能作为独立的测试路径。应用配置后在组里明确选中测试出口,再访问示例域名,避免把组内保存的直连选项误当作节点已经正常工作。

协议、传输与身份校验分别核对

不同协议的附加字段不能靠名称类推。某些协议使用用户名与口令,某些需要协议专用标识;有的在传输层启用 TLS,有的还需要与服务端一致的传输选项。应先按节点来源提供的字段清单填写协议,再核对地址、认证方式和传输参数。能建立到服务器的基础连接,只说明地址与端口可达,不能证明认证通过。若日志已指向握手或身份校验错误,应检查名称、时间与服务端证书配置,而不是通过关闭校验来掩盖错误。

拨号地址和证书匹配的服务器名称可能并不相同。服务端确实要求特定名称时,按该协议支持的字段填写,不能把节点的显示名当成握手名称。类似地,某个传输选项的路径也不是订阅地址:订阅地址用于取得整份配置,路径属于节点连接参数,两者的修改范围不同。核对来源时看正常导入后的实际配置,避免把分享链接中经过编码的字符串直接粘贴进不接受这种格式的字段。对照多份配置时只比较同一种协议的同类字段。

用单一出口区分网络故障和选择误差

排查 UDP 应单独验证。字段允许 UDP,只描述内核这一出站的行为,不保证代理服务器、底层传输和目标应用都支持相同的流量。网页走 TCP 成功,不能证明语音或实时应用也能正常工作;反过来,把 UDP 测试失败视为节点整体失效,也会误伤正常的网页连接。先以单一手动组确认基本出站,再用确实发起 UDP 的应用观察新连接记录,分别记下协议、目标、命中规则和选择的出口,不要用一次网页测速替代整条路径的验证。

节点加载失败时,先保留一个可复现的最小对象;组可见但具体连接失败时,再根据错误发生阶段核对参数。解析失败与节点域名有关,连接被拒绝更多指向端口或服务状态,握手超时则仍可能涉及路径或传输参数,不能由症状唯一确定原因。清理节点前,搜索名称是否出现在多个策略组或规则中。想先确认客户端是否配备所需内核,可查看下载中心,按平台优先查看列为首推的 Clash Plus,再核对对应产品实际支持的字段。

05 PROXY-GROUPS / SELECTION

策略组类型、成员与健康检查

策略组管理出口,不替代规则匹配

规则负责把某条连接交给一个出口或策略组,组负责从成员中选出实际出口。规则命中正确但连接走错路径时,要同时看命中的组名与组内当前选择。建议先在一层手动组里验证真实节点,再增加自动组;如果一上来就把多个自动组套在一起,健康状态、测试结果与用户选择会同时影响表现,难以解释单次连接落在哪个节点。组名适合表达用途,例如「工作连接」或「备用出口」,而不是用容易随更新失效的节点名当组名。

proxy-groups:
  - name: 自动出口
    type: url-test
    proxies:
      - 本机测试出口
    url: 'https://example.org/'
    interval: 300
    tolerance: 50
  - name: 手动入口
    type: select
    proxies:
      - 自动出口
      - DIRECT

这段内容应作为整个顶层策略组列表替换使用,不能在原文件追加第二个同名顶层键。节点来自上一章;若共用上一章的规则,还要把规则里的「节点核对」改为「手动入口」。这里只放一个节点便于演示语法,不会产生候选间切换。测试网址用于示例,部署时宜选轻量、稳定、预期响应明确、各候选路径均可访问的地址。自动组的探测是对这个地址的请求,不是在测试电脑到节点服务器之间的单程时延,也不能代表其他业务站点的表现。

按切换目标选择组类型

类型选择依据适用场景
select用户选择人工指定路径、固定出口排查
url-test探测结果与容差候选之间比较探测响应
fallback成员顺序与可用性优先使用主出口,失效时改用备用
load-balance负载分配策略在多个可用成员间分配连接

需要固定主出口时,用 fallback 表达优先顺序,不要把它当成最快节点选择器。需要按探测结果比较时,url-test 的容差用于避免因小幅差异频繁换出口;tolerance 按毫秒理解,interval 则按秒设置探测周期。测试周期过短会增加探测流量,周期过长则可能延后发现变化。先观察不同时间的实际波动,再调整这两个字段,不必根据单次探测结果立即重写整组。

load-balance 分配的是连接,并不会把单个下载请求拆给多个节点。有会话绑定要求的业务可能对出口变化敏感,适合单独送进固定组,而不是和其他连接共用轮换策略。需要在不同方案之间取舍时,先明确想保持的是主备优先级、连接亲和性还是平均分配,再看自动策略组选型与字段对照。换组前后用相同目标发起新连接,多次观察;已建立的连接不适合作为切换是否成功的证据。

组引用应形成单向关系

组可以包含其他组,但不能直接或间接引用自己。用一个面向规则的入口组引用下层自动组,自动组再引用节点,是比较容易检查的结构。通过代理集合提供成员时,组内 use 引用的是提供者名称,不是其中任意节点的名称。若一个组启动后没有可选成员,先核对本地定义与引用是否存在,再检查集合是否加载成功、过滤条件是否把成员全部剔除,最后才考虑探测失败。有定义却没有成员,与成员存在但全部不可达,是不同的问题。

判断自动组异常时,先在独立手动组使用同一个候选和同一个目标地址。如果手动连接也失败,应优先排查节点路径;若业务正常但探测失败,应核对探测地址是否被目标站限制、是否在该出口返回与预期不同的响应,以及探测是否已执行。部分客户端会保存手动组的上一次选择,改了 YAML 不代表界面会自动切回第一项。每次记录配置的候选顺序、实际选择和探测时间,才能区分配置变化与客户端保留的运行状态。

06 RULES / MATCH ORDER

规则语法、命中顺序与兜底

先匹配窄范围,再放宽范围

规则模式下,规则列表按从上到下的顺序处理,首条命中的规则决定出口。精确域名规则应先于覆盖它的后缀规则,短范围网段也应先于覆盖它的大网段。配置目标不是让条目越多越好,而是让范围和优先级可以解释。新增一条规则前,先问是否已有一条更早的宽规则覆盖相同目标;有的话应把新例外放在其前面。把例外写在最后一条兜底之后,即使配置载入,也不会得到对应分流效果。

mode: rule
proxy-groups:
  - name: 文档出口
    type: select
    proxies:
      - DIRECT
rules:
  - DOMAIN,upload.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,文档出口
  - IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
  - MATCH,DIRECT

示例的第一条只匹配上传子域名,第二条覆盖示例主域及其子域,第三条用于说明地址段的匹配写法,其中的网段为文档保留地址。末尾规则接住未命中前序条件的连接。示例组只有直连成员,所以要看连接记录里的规则或策略路径,才能分辨前两条的差异。MATCH 没有域名或网段参数,只跟出口。含逗号的整条规则在此写法中是 YAML 列表的一项;不要用多个连字符把条件和策略拆成几个不同条目。

目标域名、连接地址和数据来源是三个判断维度

域名规则依赖内核能看到或恢复目标域名。如果应用只传递一个数字地址,而没有可用的域名信息,域名规则不会凭空命中。IP-CIDR 按地址范围判断,遇到只有域名的目标时,某些 IP 类规则会触发解析。支持的规则类型可附加 no-resolve,避免仅为这条匹配额外发起查询;若已掌握目标地址,仍可基于地址判断。添加这个选项之后,应分别用域名和数字地址做验证,否则很容易把「没有解析就无法判断」误解成网段写错。

GEOIP 依赖地理地址数据库,不是按照域名后缀猜测地域;RULE-SET 引用已在 rule-providers 定义的集合。地址库更新后,相同地址的归类可能变化。集合也有自己的行为类型与数据格式,文件能下载并不等于内核已经成功读取其中的规则。将这两类条件放入正式列表前,先确认数据是否被当前配置加载,再用覆盖与未覆盖的目标各测一次。故障排查 FAQ适合先查更新失败、节点异常与分流不符的常见现象。

用正例、反例和兜底例验证顺序

一次验证至少覆盖三类目标:应命中精确例外的目标、应命中较宽条件的同类目标、应穿过前序规则落到兜底的目标。先记下每个目标的预期规则和出口,再创建新连接。如果精确目标被宽规则接走,检查上下顺序;如果两个域名都落入兜底,核对目标值、域名是否可见以及当前是否为规则模式;如果规则正确但出口不符,再看组内成员。网站可能同时请求多个子域和第三方资源,排查时应逐条看连接,不要把地址栏中的主域视为整个页面的唯一目标。

修改兜底之前先明确未分类流量应该怎样处理。以 DIRECT 兜底便于隔离已知规则的影响,适合先验证配置;正式使用时应按网络与业务要求选择明确的兜底出口,并检查常用应用在这条路径上的表现。保存变更时同时记录哪条规则因改动被提前截走。以后删除临时例外,才能知道它原本替代了哪条路径,而不是依赖记忆清理。对经常更新的外部规则集,保留一两个可重复验证的目标,更新后用同样的顺序复查。

07 OVERRIDES / EFFECTIVE CONFIG

配置覆写、合并与回滚

原始订阅、本地改动和有效配置分开保存

排查改动未生效时,应对照内核实际加载的配置,而不是只看编辑器中的订阅副本。客户端可能先取得基础订阅,再合并本地覆写,最终还会依据界面设置补充运行参数。覆写文件不是所有客户端共同采用的一种内核语法,必须先确认产品提供的是整份替换、按键合并、列表追加、脚本处理,还是其他机制。若产品没有对应功能,在 YAML 里自行增加一个合并指令不会让内核自动执行。

保留未经改动的订阅来源,另存一份本地配置用于验证。只需更改入口时,可用下面的 YAML 作为改动清单,或在支持映射式覆写的客户端中按其规则应用。请勿把这个片段单独当作原配置的替代文件,否则原节点、组和规则都不会随它一同加载。先应用这两项,确认实际监听与预期一致,再继续改 DNS 或规则。多项改动分批应用的价值在于:出现问题时可以确定是哪次变更使行为不同。

mixed-port: 7891
allow-lan: false

合并前先判定值的形状

端口是标量,替换后通常只需要同步使用这个端口的应用;DNS 段是嵌套映射,有的工具逐子键合并,有的会用新段覆盖整个旧段。因此只改增强模式,也可能意外丢掉已有的上游或内部域名策略。正确做法是查看生成结果中旧字段是否仍在,并用一个原本能解析的内部目标复测。不要用空值测试删除语义:字段缺失、空列表和 YAML 空值是不同状态,客户端与内核也可能分别处理它们。

列表需要额外核对是否被替换、前插或后插。尤其是规则列表,合并后项目都在,并不表示顺序正确。下面是要保留旧规则时的一个最小结果示意:第一条是新加的例外,第二条与兜底来自基础配置。如果工具只支持整段替换,应把需要保留的旧条目一并纳入最终列表;如果工具支持前插,只提交新条目,避免重复插入旧规则。例外本身还要引用存在的出口,不能仅因为两份 YAML 都能读取,就认为合并后一定可以载入。

rules:
  - DOMAIN,status.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,文档出口
  - MATCH,DIRECT

用加载测试验证结构,用回滚验证操作路径

独立使用 mihomo、且本机已有可执行文件时,可用测试模式检查待加载的完整配置。在客户端环境中,优先使用客户端提供的校验入口;若另用命令行,工作目录及所需的规则资源应和实际部署一致,否则外部资源相关报错可能只反映了测试环境的差异。测试通过后仍需重新载入配置,并核对监听、域名解析和一条新连接的出口。静态测试不能保证远端节点或解析服务可达,也不能代替操作系统代理的接入验证。

mihomo -t -f ./config.yaml

订阅更新前后应关注名称和顺序的变化。更新可能删掉某个节点、改变节点名,或把策略组成员替换为另一批。若本地覆写按节点名称绑定,更新后可能找不到引用;若策略组把可用候选交给提供者并附加过滤条件,则应重新核对过滤结果。需要在多台设备上复用配置时,建议把节点、组和规则作为共用部分,把监听端口等环境设置留在各设备的本地层,具体取舍见多设备配置同步方案对比。

备份应能区分更新前基础文件、本地覆写和用于回滚的有效配置。给每次改动写一条简短说明,包含修改目的、影响范围与验证结果,例如「调整监听端口,浏览器已用新端口完成连接验证」。如果有效配置中包含账户信息,应限制访问,不把原文件直接附在公开问题里。这样即使订阅更新与本地变更恰好发生在同一天,也可以先恢复已知可用的路径,再从修改记录定位导致差异的那一步。

Clash下载