Clash 配置文件参考

YAML 结构、通用入口、DNS、节点、策略组、分流规则与覆写合并。

首次安装、导入订阅和验证连接,请先走一遍使用指南。本页用于导入之后的逐项查阅:确认字段属于哪一层、修改会影响哪段链路,以及如何从运行结果反查配置。示例以 Mihomo 支持的字段为主,不代表所有历史 Clash 内核或图形客户端均支持同一写法。下文的端口、模式和开关均以示例值标注;判断设备上的实际取值,应查看当前生效配置,而不是把样例当作统一默认值。

YAML 结构总览:入口、出口与引用

顶层键与内部层级

mixed-port、mode、dns、proxies、proxy-groups 和 rules 是不同用途的顶层键。端口定义应用如何把请求交给内核;代理定义可用的远端出口;策略组组织出口;规则把请求送到策略组、具体代理或内置动作。DNS 配置则负责域名解析相关的路径。文件里先写哪一个顶层块通常不改变规则执行先后,但列表内部顺序有时就是配置含义的一部分,尤其不能把规则列表按照字母顺序重新排列。

阅读文件时先看缩进,再看连字符。冒号左侧是键,右侧是值;在 dns: 下面缩进两格的 enable 是它的子键。文档里写的 dns.enable 只是便于引用的字段路径,通常不应直接作为一个带点的顶层键照抄。列表项以连字符和空格开头,节点与策略组往往是由多个键构成的映射项,规则列表则通常是一行一个字符串。层级看起来接近,不代表解析后的类型相同:省掉规则项前面的连字符,可能得到一个字符串而不是列表。

从可独立验证的基线开始

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

proxy-groups:
  - name: Local
    type: select
    proxies:
      - DIRECT
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.com,Local
  - MATCH,DIRECT

这份文件只使用内置动作,不需要远端节点或订阅。把它保存为本地测试配置并加载。在策略组里先选 DIRECT,再选 REJECT,每次通过同一个代理入口新建到 example.com 的连接。预期是规则始终指向 Local,最终动作随选择变化。其余地址由末尾的 MATCH 直连。这里验证的是入口、规则与策略组的引用链,不以公开站点是否始终在线作为唯一判断依据;连接记录和匹配结果比浏览器旧页面更有参考价值。

调试自己的订阅时,可以先画出一条引用链:应用连接本地入口,内核匹配规则,规则给出目标,目标可能再引用节点或另一组。不要把节点服务器地址误当成系统代理地址,也不要把策略组名字当成协议类型。比如把 Local 改成 Local-Test 后,规则第三段也必须改;仅修改图形界面显示的配置文件标题,不会自动替换 YAML 里的引用。

解析成功不等于路径正确

缩进用空格,不用制表符。同一映射下不要重复写同名键;不同加载器可能报错,也可能保留后面的定义。数组和映射应保留原类型,布尔值用 true 或 false,端口写成整数。应为字符串的值如果看起来像数字或布尔值,或者含有可能被识别为 YAML 结构的符号,用引号明确类型。字符 # 在适当位置会开始注释,备注可以另起一行,避免意外改变原值。

保存后分三步检查:先确认 YAML 能解析,再确认内核能加载,最后确认请求的实际路径。通用 YAML 检查器能发现缩进问题,却不一定知道策略名不存在;内核能加载,也不一定意味着客户端使用的是刚才编辑的文件。若前两步正常、流量表现却没变,先核对配置是否已选中、是否重新加载,以及面板里的运行模式有没有覆盖文件值。保存一份可运行的基线,以后每次只改一个类别,出现问题就能准确判断是哪次改动引入的。

通用字段:mixed-port、监听范围与运行模式

先确认应用从哪个入口进入

mixed-port: 7890 表示在同一个本地端口提供 HTTP 与 SOCKS 代理入口。port 是单独的 HTTP 代理端口,socks-port 是单独的 SOCKS 代理端口,不需要为了启用混合入口把三个字段都填上。若某个应用的设置分成服务器和端口两栏,本机使用时通常填写回环地址与生效端口,而不是订阅服务器的地址。至于选 HTTP 还是 SOCKS,要与应用实际采用的协议一致;仅把数字填对不能修复协议选择错误。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
字段作用修改后核对
mixed-port合用的 HTTP 和 SOCKS 入口。系统代理和应用端口是否仍指向旧值。
allow-lan是否允许其他设备接入代理。实际监听地址、访问范围及防火墙。
mode切换规则、全局或直连模式。界面当前值与新连接路径。
log-level调整内核日志详细程度。是否看到本次重载或连接的记录。

改端口前,先确认旧端口是哪个进程在用。内核日志若提示地址已被占用,常见原因是另一个客户端仍在后台运行,或者客户端本身启动了第二个内核实例。不要只把系统代理指向一个任意空闲端口:应让内核成功监听,再同步修改系统代理和应用设置。反过来,如果内核已成功监听但浏览器直连,先检查浏览器是否使用代理、是否有自己的例外列表,以及地址是否被系统设为直连。系统代理只是向遵循该设置的程序提供入口,不会自动抓取所有应用流量。

监听范围与接管方式是两回事

allow-lan: false 适用于只在本设备使用的配置。只有确实要让同一可信网络中的设备接入时,才考虑启用局域网访问,并结合内核支持的监听地址、认证和主机防火墙限制范围。客户端的控制接口与代理入口是两件事;开放代理并不要求对局域网开放管理接口。另一台设备不能用自己的回环地址找到这台主机,测试时应核对目标主机的局域网地址,并确认网络没有隔离设备。测试结束后,撤掉临时开放的入口。

TUN 则是另一种流量接管路径,关注的是虚拟网卡、路由和平台权限,而不是应用里填的 HTTP 代理。它是否可用取决于平台、内核和前端封装。若系统代理路径正常而 TUN 路径异常,应先看虚拟网卡是否成功创建、是否与已有 VPN 或路由配置重叠,再看 DNS 接管情况。不要同时修改端口、路由和 DNS 来试错,否则即使恢复也无法确定真正起作用的是哪项改动。

mode 决定进入内核后怎样走

rule 按规则匹配;global 使用全局策略所选出口;direct 将进入内核的连接走直连。全局模式并不会替未接入内核的应用建立入口,直连模式也不等于撤销系统代理。把全局模式当作对照试验时,应确认全局组选择的是想测试的出口,比较同一目标的新连接后再切回规则模式。更多行为差异见规则、全局与直连模式对照。

平台客户端可能保存独立的端口、日志级别或模式,并在启动时将其写回运行配置。手改 YAML 后又恢复原值,先看是否有界面设置参与,不必立即重装。若需要调整的项目在当前客户端没有对应入口,可在下载页核对平台选项;有对应安装入口的平台可先查看 Clash Plus,Linux 则以该平台下载列表为准。切换客户端前保存可运行配置,并避免两个实例同时接管同一个入口。

DNS 设置:增强模式、上游与实际解析路径

dns.enable 与 enhanced-mode

dns.enable: true 启用配置中的 DNS 模块;enhanced-mode: fake-ip 指定增强模式。启用模块并不等于系统和各应用都会把查询交给它。系统代理、TUN、应用自己的加密 DNS 以及局域网转发,可能走不同路径。判断是否发生不符合预期的解析,必须先说清是哪台设备、哪个应用和哪种接管方式,再核对该查询究竟交给了哪个解析器。只看到一个公网解析器名称,不能据此判断来自本机直连还是远端解析。

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - 'localhost'
    - '+.lan'
  nameserver:
    - system

这里的 system 适用于支持该写法的 Mihomo,用系统解析器作为示例上游,并未指定独立的公共 DNS。系统解析器已经被另一个组件转发时,应先确认它不会把同一查询送回内核,造成循环。示例也没有配置额外的 DNS 监听地址;如果计划把内核作为显式 DNS 服务端,监听和防火墙范围要单独检查,不能从 enable: true 推断服务已在某个地址对外开放。

在 fake-ip 模式下,内核可为域名返回一个用于映射的虚拟地址,并在后续连接进入内核时根据映射还原目标。测试中看到该地址段,不表示网站真实地址变成了这个值。如果应用保留了虚拟地址而后续连接未被内核接住,或内核重启失去了对应映射,便可能表现为解析有结果但连接失败。对照测试应重建连接,同时排除应用与操作系统持有的旧结果。redir-host 则以返回真实解析结果为主;切换模式不是对所有 DNS 故障通用的修复方法。

区分普通查询、例外与节点解析

nameserver 是常规上游列表;nameserver-policy 可以为特定域名指定解析路径。支持 proxy-server-nameserver 的内核还可单独设置代理服务器域名的解析。这个区分在节点服务器以域名填写时很重要:如果解析该域名必须先连上同一个尚未启动的代理,就产生了依赖循环。调整前先列出哪些上游使用域名、这些上游如何建立初始连接,以及哪个解析器负责节点服务器本身,不要把所有类型的查询机械地指向同一路径。

fake-ip-filter 处理的是虚拟地址返回行为,不是访问权限,也不是代理分流表。把某个局域网服务域名加入例外,可能解决应用必须读取真实地址的问题;能否访问这个真实地址,还取决于所用上游是否认识它、本机是否有对应路由,以及规则最终选择的出口。排查时先确认服务在网络内有可用的解析记录,再缩小例外范围。对所有域名添加宽泛例外会改变整套增强模式的行为,后续很难判断到底是哪类应用需要特殊处理。

如何验证所谓 DNS 泄漏

先定义预期:例如内网域名应交给指定的内网解析器,某个应用的公网查询不应落到当前接入网络的默认解析路径。随后用同一个应用重复测试,分别观察内核是否收到对应域名、它使用的上游是否符合设置,以及应用是否启用了自己的安全 DNS。浏览器测试页只能描述浏览器发出的那组查询,不能代表整个系统;终端工具也可能因直接指定服务器而绕开实际应用路径。比较时记录代理模式、TUN 状态和查询结果,避免把不同环境得到的结果混在一起。

代理节点字段:协议、地址与传输参数

name 是引用名,server 是连接地址

proxies 是内联节点列表。节点的 name 供策略组和规则引用,type 决定内核按哪种协议解释其余字段,server 和 port 给出代理服务实际监听的位置。图形界面可以给节点显示图标、别名或备注,但连接仍以生效配置中的字段为准。服务端端口与本机 mixed-port 属于不同链路,即使数字相同也不自动关联。名称尽量在一个配置里保持唯一,不要与已有组名或内置动作重名。

proxies:
  - name: Local-SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: Route
    type: select
    proxies:
      - Local-SOCKS
      - DIRECT

rules:
  - MATCH,Route

这个片段可并入最小基线,用来引用本机已经运行的 SOCKS5 服务。它不会创建该服务;如果没有独立程序监听回环地址的 1080,选中 Local-SOCKS 后连接应当失败。不要让该地址指回同一个内核实例的代理入口,否则会形成自引用。选中 DIRECT 可以对照代理上游是否才是故障点。应用若要使用这个示例,仍需把请求交到内核另设的本地入口,不能把节点上游地址与该入口混用。

协议专用选项不可互换

不同节点会使用不同的授权字段和传输参数。HTTP 或 SOCKS5 可以有用户认证;其他类型可能要求协议专有的标识、加密设置或握手参数。值应使用服务端或订阅提供的原始配置。把其他类型节点的字段整段复制过来,或只把 type 从一种协议改成另一种,无法让内核和服务器形成相同的握手。导入工具转换配置时,也要留意是否把整数、布尔值、嵌套映射和字符串保留成原类型。

启用 TLS 的节点还涉及连接地址与证书身份。地址说明要联系哪台服务,服务器名称等参数则可能参与 TLS 握手;某些前置服务还会依据传输层以外的主机名或请求路径转发。三者偶尔相同,却不是同一个字段。遇到证书错误时,先核对系统时钟、节点要求的服务器名称以及实际提供的证书,不要把关闭证书验证当成长期解决办法。连接建立后接口返回拒绝,则应再核对路径、认证和服务端是否接受当前协议。

把导入故障与连接故障拆开

同一节点如果完全没有出现在界面上,应先看配置是否加载、来源是否更新成功、组有没有引用该来源,以及是否被筛选条件排除。如果节点可见但无法使用,再分开检查节点服务器域名解析、目标端口可达性、协议握手和实际业务请求。界面上的测试结果只是一次特定请求的观察,不足以单独解释授权失败、地址不可达或某种业务传输不受支持。展开节点加载前后的日志,比连续更换许多节点更容易找到第一处异常。

订阅还可能经由 proxy-providers 提供节点。此时顶层 proxies 不一定列出每一项,组通常通过 use 引用来源;来源名和节点名是两个不同的引用层。如果订阅更新后节点消失,先判断是来源未加载、筛选条件未匹配,还是名称被上游改动。记录前后组成员的差异,不要直接把整份带凭据的配置发到公共渠道。若所有节点同时失败,按节点超时排查清单先排除订阅、时间、入口和系统网络等共同因素。

策略组字段:select、url-test 与 fallback

先定组负责的决策,再选类型

proxy-groups 是策略组列表。select 由用户选择,适合作为手动对照或固定出口;url-test 用指定地址的探测结果挑选成员;fallback 以成员顺序表达优先级,从可用候选中选择靠前的成员。自动组并非把多条连接叠加为一条更快的连接。若目标只是保持某个出口优先并在失败时换备用,fallback 比试图通过调整探测延迟来模拟优先级更直接。

proxy-groups:
  - name: Manual
    type: select
    proxies:
      - DIRECT
      - REJECT

  - name: Probe
    type: url-test
    proxies:
      - DIRECT
    url: 'https://example.com/'
    interval: 300
    tolerance: 50

  - name: Preferred
    type: fallback
    proxies:
      - Manual
      - DIRECT
    url: 'https://example.com/'
    interval: 300

rules:
  - DOMAIN-SUFFIX,example.com,Preferred
  - MATCH,Manual

示例故意不依赖远端订阅。Probe 只有一个成员,用于检查探测设置,不会产生真正的节点比较;Preferred 则展示组引用及其成员顺序。实际使用时可用已确认存在的节点替换内置动作,探测地址应选择允许定期访问、各候选都能到达的轻量目标。示例中的 interval: 300 以秒为单位设置探测间隔;tolerance: 50 为自动延迟比较提供毫秒级容差,减少微小波动导致的来回切换。保存后应检查内核对组的实际处理,别用界面上一次读数推断切换时机。

测试结果看条件,不只看数字

探测路径只到配置指定的测试地址。探测所经历的解析、连接、握手及响应环节,与实际业务地址不一定相同。一个出口可以快速响应轻量测试,却在长时间下载时受吞吐限制;也可能因为测试域名本身在该路径上不可达,而被排除在自动选择之外。对照时先用同一个地址复测,再换成业务请求比较。若需要进一步理解测量边界,见延迟测试数值与真实网速。

带有探测地址的组和代理来源自己的健康检查不一定共用配置和执行时机。看到某个来源有健康状态,并不等于引用它的组会按完全相同的条件选择成员。排查时确认界面当前展示的是节点手动测试、组探测还是来源健康检查,核对各自的地址与间隔。探测过密会增加网络请求,移动设备上还可能增加唤醒成本;排障时可以临时手动测试,不应把长期探测频率当作修复连通性的手段。

检查引用链与选择持久化

proxies 在策略组内部表示成员名,和顶层定义节点的同名字段不同。成员可以是内置动作、节点名或可引用的组;use 列出代理来源名称。组之间不要循环引用。若某个组显示空白,核对来源是否加载、筛选条件是否留下成员,以及前端是否展示当前这份配置。多层嵌套虽然能分离手选和自动策略,但层级太多时界面只显示上级组名,检查连接时应一路追到最终出口。

重新加载后仍选中上次用过的成员,未必说明 YAML 顺序没有生效:前端或内核配置可能启用了选择持久化。判断顺序或自动切换时,记下当前手选值,用新连接而不是旧连接验证;已有长连接往往不会因为组选择改变就立刻移到另一条路径。组名、引用链和可用性都正常却依旧走错时,再查看规则是否命中了该组。若连接被更早的规则送往其他策略,调整当前组的排序不会改变结果。

规则语法:从首个命中项到兜底动作

从上到下匹配,不按精确程度自动重排

rules 是规则列表。常见条目由类型、匹配值和目标组成,部分类型还能带额外参数。DOMAIN 匹配明确域名,DOMAIN-SUFFIX 覆盖指定域名及其子域名,IP-CIDR 匹配地址段,GEOIP 依赖相应地理数据。MATCH 不需要匹配值,通常放在最后。内核按顺序选取首个满足条件的条目;宽泛规则写在特例之前,后面的特例即使写得更精确也无法被执行。

rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

把这段替换到基线后,访问 blocked.example.com 的新请求在域名可见时会命中首条规则;同一后缀下的其他请求可命中第二条。保留最后的直连兜底是为了方便在没有远端节点的环境中验证,不代表生产配置应默认直连。要把目标改为自定义策略,先在同一份配置里建立相应节点或组。注意示例中的地址段只覆盖一段常见私有地址,不能把它误当成完整的本地地址或私有网络清单。

类型判断依据容易忽略的条件
DOMAIN精确域名。请求不一定把域名交到内核。
DOMAIN-SUFFIX域名后缀。更窄的例外通常放前面。
IP-CIDR目的地址段。可能涉及域名解析;区分地址族。
GEOIP目的 IP 对应的地理数据。不是按域名后缀识别地区。
MATCH此前未匹配的请求。放早了会遮住后续条目。

域名信息和目的地址不总是同时存在

规则只对进入内核且具有所需信息的流量有效。应用直接连接一个地址时,内核不一定知道这个地址原先对应的域名;使用系统代理的应用也可能把主机名交给代理,或者先解析后提交地址。启用域名嗅探的环境下,能否恢复域名还取决于协议和实际可见内容。看到域名规则不命中,应先读连接记录里的主机或地址字段,再决定是否需要添加地址规则,不宜直接扩大后缀范围来碰运气。

no-resolve 可以让相应的地址规则不为此次匹配额外触发解析;若已经有可用的目的地址,规则仍可据此判断。它不是全局禁用 DNS 的开关,也不会让域名凭空符合一个地址段。域名尚未解析且没有可比对的地址时,该规则可能跳过并继续匹配后面的条目。使用 GEOIP 时还要确认内核有可用数据,且目的实际落在预期分类。站点可能有多个地址或经由不同网络提供服务,直觉上的站点归属不能代替匹配记录。

把规则集当成带依赖的配置项

rule-providers 提供外部规则集,RULE-SET 在主列表中引用对应名称。来源的数据格式和行为分类须与所用内核和规则集内容一致,不能只凭文件扩展名判断。导入后确认来源已加载,并检查主列表中引用的位置;同一个规则集放在精准例外前后,结果可能不同。来源刷新还可能改变规则覆盖范围,排查某个域名时建议记录命中的规则和来源,而不是只比较两个日期的界面状态。

网页通常会生成多条连接。主页面、登录、图片和接口可能各用独立域名,不会因主域名命中一个策略就自动走相同出口。排查某个页面部分加载失败,应找出具体失败的请求,在规则模式下对照同一域名的新连接,核对命中项、策略名和最终出口。若失效条目在现有配置里根本找不到,先检查客户端使用的合并结果;旧连接、缓存以及模式切换也可能让结果看起来与文件不符。

覆写与合并:从订阅原文到实际运行配置

区分订阅、覆写和运行副本

订阅原文是上游输入;覆写是本地维护的改动;运行副本是客户端应用设置、执行合并后交给内核的结果。许多“改完就没了”的情况,是修改了会被订阅刷新覆盖的缓存或运行副本,而不是持久化的覆写。开始前先确认界面编辑入口属于哪一层,并保留修改前能运行的本地副本。当前端没有导出合并结果的功能时,至少记录启用的配置、覆写入口、作用范围和加载日志,避免把预览误当成当前执行状态。

标量、映射和列表不能用同一种直觉理解。标量通常是替换,例如把模式值改为另一个字符串。映射可能逐键合并,也可能整体替换,例如只写 dns.enable 的嵌套定义是否保留原有上游,取决于合并器。列表则要区分替换、前置与追加:从内容看都像“新增一条”,但在首条命中的规则系统里会产生不同结果。只有在当前客户端确实支持特定语法时,才使用诸如 prepend-rules 的覆写键;它不是应该直接交给所有内核识别的通用顶层字段。

用合并结果核对顺序,不猜合并器规则

假设订阅有两条规则,希望增加一个精确例外。下面展示输入和目标输出,不假定各客户端使用相同覆写格式。若编辑器支持前置规则,就提交一条例外并查看结果;若只支持整个数组替换,则应提交完整的目标列表,同时承担后续订阅更新时维护这份列表的成本。两种方式都应保留最终兜底。

# 订阅原文中的规则
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT
# 预期的合并结果
rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

如果编辑器把例外追加在末尾,它会被兜底挡住;如果放到后缀规则之后但仍在兜底之前,同样会被后缀规则挡住。若组定义也要覆写,检查合并器是按名称修改某个元素,还是直接替换整条组列表。后一种情况下,只提交一个同名组不一定会“更新一组”,可能导致其他组全部消失,而原规则仍引用它们。先做一次单字段试验,观察合并前后的差异,再决定如何维护较大的本地改动。

按可回滚的顺序验证和恢复

将规则、DNS 和入口改动分开保存,有助于确定故障是由哪一层引起。先确认未覆写时能运行,再启用单项改动,检查内核是否重载并对比一条受影响的连接与一条应保持不变的连接。随后主动刷新一次订阅,再比较结果。需要特别留意组名被上游改动、来源不存在、DNS 子键被整体替换、前端自动写回端口等情况。这些问题不一定在首次保存时显现,有的要等到订阅更新或客户端重启才会出现。

若启动直接失败,先停用最近一次覆写并重载已知可用的配置,保留第一条明确错误作为定位线索。若内核可启动但连接异常,比较当前模式、应用入口和命中规则,确认不是多个组件同时改写网络设置。若最终要退出客户端,先恢复由客户端设置的系统代理,再验证应用在当前网络下是否能按预期直连。更详细的首次导入和启用步骤见使用指南;不熟悉内核与前端的区别时,可另查术语表。

修改覆写后,为什么面板还是显示原值?

先区分面板显示的是订阅原文、客户端自己的设置,还是内核的当前运行值。再确认覆写已启用并作用于当前配置,合并过程没有报错,客户端也已经执行重新加载。

怎样确认故障来自覆写而不是订阅?

在同一客户端和网络下暂时停用覆写,使用原订阅重载并新建连接。如果恢复,再逐项启用覆写比较结果;如果仍异常,应先检查订阅更新、入口和内核日志。