Clash 配置文件 YAML 手册

01配置文件总览:YAML 语法与顶层结构

Clash 配置采用 YAML 格式。YAML 靠缩进表达层级,规矩不多但每条都不能破:统一用空格缩进(约定两个空格一层),禁止使用 Tab;键与值之间的冒号后必须跟一个空格;列表项以「短横线 + 空格」开头;# 到行尾是注释。字符串通常不需要引号,但当值里含有冒号、井号、花括号等特殊字符,或以数字、*、~ 开头时,应当用引号包住,否则解析结果可能与预期不符——密码、订阅 URL、通配符域名这三类值建议一律加引号。

配置文件在哪里

图形客户端(Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu 等)自行管理配置目录:订阅导入后以 profile 形式保存,查看与修改都通过客户端内置的编辑器或覆写功能完成,一般不需要手动去文件系统里找路径。直接跑内核的用户(服务器、路由器场景)默认从工作目录读取 config.yaml,Linux 下惯例路径是 ~/.config/mihomo/config.yaml,也可以用 -f 参数显式指定文件、-d 指定工作目录。

顶层区块一览

一份完整配置由若干顶层区块组成,各管一摊、互不越界。下表是全文的地图,后续章节按此顺序逐个展开:

最小可用示例

下面这份配置去掉了一切可选项,只保留「一个入站端口、一个节点、一个策略组、三条规则」,是能通过语法校验并正常工作的最小骨架。读懂它,后面每一章都是在这个骨架上加肉:

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

proxies:
  - name: "示例节点"
    type: ss
    server: example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "节点选择"
    type: select
    proxies:
      - "示例节点"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,节点选择
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

三个区块的协作关系:proxies 定义「有哪些出口」,proxy-groups 把出口组织成「怎么选」,rules 决定「什么流量交给哪个组」。规则的出口既可以是组名,也可以直接写节点名或内置的 DIRECT(直连)、REJECT(拒绝)。想看这份骨架更口语化的逐段拆解,可读博客《Clash 配置文件结构逐段拆解》。

02通用字段:端口、模式与运行控制

通用字段位于配置最顶部,不属于任何区块,决定内核「以什么姿态运行」。它们出错不会导致分流异常,但会导致连不上、连错口或者日志刷屏,值得逐个弄清。

入站端口与局域网共享

port 监听 HTTP 代理,socks-port 监听 SOCKS5,而 mixed-port 在同一个端口同时接受两种协议——现代配置基本只写 mixed-port: 7890 一行,省掉两个端口的维护成本。Linux 专属的 redir-port 与 tproxy-port 用于透明代理场景,桌面用户可以忽略。allow-lan 控制是否接受局域网内其他设备的连接:设为 true 后,同一 Wi-Fi 下的手机、电视可以把代理地址指向这台机器;bind-address 进一步限定监听的网卡地址,默认 "*" 表示全部网卡。

mode:三种工作模式

mode 只有三个合法值。rule 按 rules 区块逐条匹配分流,是日常唯一推荐的模式;global 让所有流量走同一个出口,只在测试单个节点时临时使用;direct 全部直连,相当于保留监听端口但不做任何代理。三种模式在客户端界面上都有对应开关,含义与配置字段完全一致,操作层面的选择建议见教程页第二步。

日志、外部控制与状态持久化

log-level 从少到多依次是 silent、error、warning、info、debug。日常用 info;排查分流问题时临时切 debug,能看到每条连接命中了哪条规则,查完记得改回来,否则日志文件增长很快。external-controller 开启 RESTful API(惯例监听 127.0.0.1:9090),网页面板与第三方工具都靠它读取状态、切换节点;secret 是这个 API 的访问口令,监听地址一旦不限于本机就必须设置。profile 区块控制两项持久化:store-selected 记住每个策略组上次手动选中的节点,重启不丢;store-fake-ip 把 fake-ip 映射表落盘,减少重启后的解析抖动。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "your-secret"
profile:
  store-selected: true
  store-fake-ip: true

03dns 区块:域名解析与 fake-ip

分流规则里大量条目按域名匹配,而域名解析本身又可能被污染或劫持——如果内核直接沿用系统 DNS 的结果,规则判断和实际连接都会被带偏。dns 区块让内核自己接管解析:用什么上游、走加密通道与否、要不要启用 fake-ip,全部在这里声明。开启 TUN 模式时该区块必须启用,否则劫持来的 DNS 查询无处应答。

enhanced-mode:fake-ip 与 redir-host

fake-ip 是目前的主流模式:应用发起域名查询时,内核立刻从 fake-ip-range(惯例 198.18.0.1/16)取一个假地址返回,同时记下「假地址 ↔ 域名」的映射;应用拿假地址发起连接时,内核凭映射还原出域名再做规则匹配和真实解析。好处是省掉一次前置解析、规则始终能按域名精确匹配;代价是有些程序拿到 198.18 开头的地址会困惑——局域网设备发现、NTP 校时、部分游戏平台属于典型场景,这正是 fake-ip-filter 存在的意义:列在其中的域名跳过 fake-ip,直接返回真实地址。redir-host 模式则始终返回真实 IP,兼容性最好但规则匹配精度和性能都逊一筹,仅在确认 fake-ip 引发问题时退回使用。

上游服务器的三层结构

default-nameserver 是引导层,只负责解析后面 DoH 服务器自己的域名,因此必须填纯 IP;nameserver 是主力层,日常查询都发给它,推荐写 DoH(https:// 开头)或 DoT(tls:// 开头)地址;fallback 是备用层,配合 fallback-filter 工作——典型策略是 geoip: true 加 geoip-code: CN:主力层解析结果落在中国大陆 IP 段就采信,否则改用 fallback 的结果,以此对抗污染。还有一个精确制导工具 nameserver-policy,可以为特定域名指定专用上游,比如把公司内网域名交给内网 DNS。

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "time.*.com"
    - "ntp.*.com"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

fake-ip-filter 支持两种通配符:* 匹配一级,+ 匹配任意多级(+.local 能覆盖 a.b.local)。修改 fake-ip 相关字段后建议重启内核并清空客户端的 fake-ip 缓存,让旧映射失效。另外,TUN 模式下的 DNS 处理与浏览器证书报错之间有一条容易被忽视的因果链,展开分析见博客《开代理后浏览器提示 HTTPS 证书错误?》。

04tun 区块:虚拟网卡与系统级接管

常规的「系统代理」只是向操作系统登记一个 HTTP/SOCKS 端口,愿不愿意用全看应用自觉——命令行工具、部分游戏客户端和不少后台服务从不读取这项设置。TUN 模式换了思路:创建一块虚拟网卡并把默认路由指过去,所有流量在网络层被截获,不给应用绕行的机会。代价是需要更高的系统权限,并且与系统代理属于两套并行机制。

关键字段

stack 选择协议栈实现:system 走系统网络栈,性能最好,是桌面平台的默认推荐;gvisor 是用户态实现,兼容性场景备用;mixed 取两者折中。auto-route 自动改写路由表,把默认路由导向虚拟网卡,几乎总是应该开启;auto-detect-interface 自动识别真实的物理出口网卡,避免流量在虚拟网卡里打转形成回环。dns-hijack 声明要劫持的 DNS 目标,写 any:53 即拦下所有发往 53 端口的查询交给内核 dns 区块应答——这也是「开 TUN 必须开 dns」的原因。strict-route 进一步收紧路由防止绕过,个别虚拟机与容器环境下可能引发不通,遇到再关。

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
  mtu: 1500

各平台的权限与差异

05proxies:代理节点字段

proxies 是一个列表,每一项完整描述一个节点。订阅场景下这个区块由机场生成、随订阅更新,通常不需要手写;但读懂字段仍然必要——排查「某个节点连不上」时,第一步就是核对这里的参数。所有协议共享四个基础字段:name(节点名,策略组和规则靠它引用,同一配置内不得重名)、type(协议类型)、server 与 port(服务器地址与端口);udp: true 声明该节点支持 UDP 转发,语音通话和游戏依赖它。

Shadowsocks(ss)

字段最少的协议:cipher 指定加密方法(常见 aes-128-gcm、chacha20-ietf-poly1305 等 AEAD 系),password 为预共享密钥。两端的 cipher 与 password 必须完全一致,任何一个抄错的表现都是「连接立即失败」而非报错提示。

VMess

以 uuid 作为身份凭证,alterId 在现代部署中固定为 0,cipher 一般写 auto。VMess 常与传输层伪装组合:network: ws 启用 WebSocket 传输,配套的 ws-opts 里 path 与 headers.Host 必须与服务端约定一致;tls: true 在外层再套一层 TLS。这类节点参数多、相互耦合,连不通时优先逐字段与订阅源比对。

Trojan 与更新的协议

Trojan 天生跑在 TLS 上,核心字段只有 password 和 sni(TLS 握手时声明的服务器名)。skip-cert-verify 控制是否跳过证书校验——见下方警告。VLESS、Hysteria2、TUIC 等更新的协议需要 mihomo 内核支持,经典 Clash 内核无法解析;本站下载页收录的 Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu 均基于 mihomo,这些协议开箱可用。

proxies:
  - name: "SS-香港-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "VMess-日本-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /your-path
      headers:
        Host: jp01.example.com

  - name: "Trojan-新加坡-01"
    type: trojan
    server: sg01.example.com
    port: 443
    password: "your-password"
    sni: sg01.example.com
    udp: true

06proxy-groups:策略组字段

策略组是节点与规则之间的中间层:规则不直接指向某个节点,而是指向一个组,组内再决定当前用哪个节点。这层间接让「换节点」不必动规则、「节点失效」可以自动切换。每个组必有 name、type 和成员列表(proxies),成员可以是节点名、其他组名,以及内置的 DIRECT 与 REJECT。

五种组类型

select 手动选择,面板上点谁用谁,是最常见的「主开关组」。url-test 定期向 url 指定的测试地址发起请求,自动选用延迟最低的成员;interval 是测试间隔(秒),tolerance 设定切换容差——新旧节点延迟差小于该毫秒数就不切换,避免在两个水平接近的节点间反复横跳;lazy: true 让组在被规则实际用到之前不发起测试,省流量。fallback 按成员列表顺序取第一个可用节点,首选挂了自动顺延、恢复后自动切回,适合「主用一个、备用一串」的场景。load-balance 把连接分摊到多个成员,strategy 可选 consistent-hashing(同一目标站点固定走同一节点)或 round-robin(轮询)。relay 把成员按顺序串成链路,流量依次经过每一跳,延迟与故障率随链长叠加,仅特殊需求使用。

组的嵌套

组可以引用组,常见的分层写法是:按地区各建一个 url-test 组(香港自动、日本自动……),再建一个 select 总组把这些地区组和 DIRECT 收进来。日常只操作总组,地区内部的择优交给自动测速。需要注意 url-test 面板上显示的毫秒数衡量的是「到测试地址的握手往返」,与实际带宽不是一回事,选节点时不要唯延迟论——原理拆解见博客《Clash 节点延迟测试原理》。

proxy-groups:
  - name: "节点选择"
    type: select
    proxies:
      - "自动测速"
      - "故障转移"
      - "SS-香港-01"
      - "VMess-日本-01"
      - DIRECT

  - name: "自动测速"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - "SS-香港-01"
      - "VMess-日本-01"
      - "Trojan-新加坡-01"

  - name: "故障转移"
    type: fallback
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - "SS-香港-01"
      - "VMess-日本-01"

07rules:规则语法与匹配顺序

rules 是一个字符串列表,每条形如 类型,匹配值,出口(个别类型没有匹配值或带附加参数)。内核对每条新连接自上而下逐条比对,第一条命中的规则立即生效,其后所有规则不再参与——顺序就是优先级,这是理解一切分流行为的钥匙。列表末尾必须有一条 MATCH 兜底,否则未命中的流量行为未定义。

规则类型速查

no-resolve:别让 IP 规则触发解析

当目标还是域名时,IP 类规则(IP-CIDR、GEOIP 等)默认会先把域名解析成 IP 再比对——这次解析可能是多余的,还会拖慢匹配。在 IP 规则末尾追加 no-resolve 参数后,域名流量直接跳过该条,只有本来就以 IP 为目标的连接才参与匹配。经验法则:排在域名规则之后、仅为兜底 IP 流量服务的 IP 规则,一律加 no-resolve;唯一的例外是希望 GEOIP,CN,DIRECT 对域名流量也生效的场景。

排序建议与常见误伤

推荐的排列次序:进程规则与精确域名规则放最前,DOMAIN-SUFFIX 批量规则居中,RULE-SET 与 GEOSITE 大集合其后,GEOIP,CN,DIRECT 倒数第二,MATCH 收尾。两个高频翻车点:其一,DOMAIN-KEYWORD 匹配面极宽,DOMAIN-KEYWORD,go,节点选择 这类短关键字会误伤大量无关域名;其二,把宽规则放在窄规则前面,导致后面的精细规则永远轮不到——排查时开 log-level: debug 看连接实际命中了哪条即可定位。GEOIP 与 GEOSITE 依赖本地数据库文件,数据库版本直接影响匹配结果,下载源选择与更新方法见博客《Clash GeoIP 与 GeoSite 数据库更新教程》。

rules:
  - PROCESS-NAME,Telegram.exe,节点选择
  - DOMAIN,dl.google.com,节点选择
  - DOMAIN-SUFFIX,github.com,节点选择
  - DOMAIN-SUFFIX,githubusercontent.com,节点选择
  - DOMAIN-KEYWORD,youtube,节点选择
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

08proxy-providers 与 rule-providers

Provider 机制把「节点清单」和「规则集」从主配置里拆出去,变成可独立下载、独立更新的外部资源。好处直接:订阅更新只刷新节点文件,不碰你精心维护的策略组与规则;规则集可以引用社区维护的现成清单,不必自己维护上千行域名。

proxy-providers:外置节点源

每个 provider 有一个自定义键名。type: http 表示从 url 定期拉取(interval 单位为秒,86400 即一天一次),下载结果缓存到 path;type: file 则直接读本地文件。health-check 子区块给这批节点配置健康检查,参数含义与 url-test 组一致。策略组通过 use 字段引用 provider,与 proxies 列表可以并存——手写的常驻节点和订阅节点混编在同一个组里完全合法。订阅链接本身有 Base64、Clash YAML 等多种格式,provider 需要的是 Clash YAML 格式的地址,格式识别与转换方法见博客《Clash 订阅链接常见格式详解》。

rule-providers:外置规则集

字段与 proxy-providers 大体同构,多一个关键的 behavior:domain 表示文件内容全部是域名(内核用域名树高效匹配)、ipcidr 全部是网段、classical 则允许混写各种规则类型但匹配开销最大——能用前两种就不要用 classical。规则文件的格式由 format 声明(yaml 或 text)。定义好之后,在 rules 里用 RULE-SET,键名,出口 引用,该条的排序原则与普通规则完全相同。

proxy-providers:
  airport:
    type: http
    url: "https://example.com/sub?token=xxxx"
    path: ./providers/airport.yaml
    interval: 86400
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "节点选择"
    type: select
    use:
      - airport
    proxies:
      - DIRECT

rule-providers:
  cn-domains:
    type: http
    behavior: domain
    format: yaml
    url: "https://example.com/ruleset/cn.yaml"
    path: ./ruleset/cn.yaml
    interval: 86400

rules:
  - RULE-SET,cn-domains,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

09覆写与合并:改配置而不丢改动

订阅是机场生成的完整配置,每次更新都会整体覆盖本地 profile——直接在订阅文件里改 dns、加规则,下次更新全部归零。覆写(Override / Merge)机制解决这个矛盾:你的修改单独存放,客户端在每次加载订阅时把它自动叠加上去,订阅随便更新,改动始终生效。

客户端里的覆写入口

本站下载页收录的主流客户端(Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu)都提供订阅覆写能力,入口名称略有差异,常见叫法是「覆写」「全局扩展配置」「Merge」。多数客户端同时提供两种形态:声明式的 YAML 合并(写一段片段,按键名叠加)和脚本式覆写(用 JavaScript 函数直接加工配置对象,自由度更高)。日常需求用 YAML 合并就够,脚本留给「按条件批量改节点名」这类程序化场景。

合并语义:什么会被覆盖,什么会被追加

理解合并的关键是区分值类型:标量键(如 mode、log-level)与映射键(如 dns 整块)在覆写片段中出现时,直接替换订阅里的同名内容;列表键(如 rules、proxies)默认也是整体替换——这往往不是你想要的,所以 Clash Verge Rev 风格的合并提供了 prepend- 与 append- 前缀:prepend-rules 把若干条规则插到订阅规则的最前面(利用「先命中先生效」抢占优先级),append-rules 则补在 MATCH 之前的队尾。同理还有 prepend-proxies、prepend-proxy-groups 等。

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - PROCESS-NAME,ssh,DIRECT

append-rules:
  - DOMAIN-KEYWORD,tracker,REJECT

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://doh.pub/dns-query

覆写常见误区与排查顺序

覆写用错最典型的表现是「片段明明写了,行为却没变」,原因通常落在三处。其一,列表键忘了加前缀:直接写 rules 会把订阅里原有的全部规则整体替换掉,只留下你片段里的这几条,分流自然大乱;需要追加时必须写成 prepend-rules 或 append-rules。其二,插入位置理解反了:想让某条规则优先命中就要用 prepend-rules 抢到最前,用 append-rules 补在队尾时,它很可能排在 GEOIP,CN,DIRECT 之后,永远轮不到。其三,片段本身缩进不合法,客户端静默忽略了整段覆写而没有明显报错。排查时按「先确认片段被加载 → 再看键名前缀 → 最后核对插入顺序」推进,配合 log-level: debug 观察连接实际命中哪条规则,能快速定位是覆写没生效还是顺序不对。若同一份配置在不同客户端上表现不一致,多半是各家对合并前缀的支持程度有差异,以客户端文档标注的语法为准。

改完先校验,再谈生效

无论直接编辑还是覆写,保存前都值得过一遍语法校验。图形客户端的内置编辑器一般会即时标红错误行;命令行环境下,mihomo 自带配置检查参数,只验证不启动:

mihomo -t -f config.yaml

校验通过后重载配置即可生效,不需要重启整个客户端。如果加载后行为不符合预期,按本手册的区块顺序自查:入站端口对不对 → dns 是否启用 → 规则顺序有没有被宽规则截胡 → 策略组当前选中的是谁。仍未解决的问题,先查 FAQ 的「故障排查」分类;从零开始的完整操作路径回看快速上手教程;还没有装客户端的读者,直接前往获取客户端页,首选 Clash Plus。