Clash 配置文件字段参考大全

Clash 系客户端的一切行为都由一份 YAML 配置文件驱动:监听哪个端口、DNS 如何解析、有哪些节点、流量按什么规则分派,全部写在这份文件里。图形客户端的开关与下拉框,本质上只是这份文件的可视化编辑器——理解字段本身,才能在界面选项不够用、或订阅内容需要微调时不至于束手无策。

本站对配置相关内容做了明确分工:使用文档负责"从下载到连通"的最短路径,不展开字段细节;常见问题收录按症状检索的独立问答;本页则是系统化的字段参考,按配置文件自上而下的书写顺序组织,适合整段通读建立框架,也适合用顶部目录直接跳到某个字段所在章节。

字段语义以 mihomo 内核为基准。原版 Clash 内核归档后,主流图形客户端——包括本站首推的 Clash Plus,以及 Clash Verge Rev、FlClash、Clash Nyanpasu 等——均已切换到 mihomo,本页描述的字段在这些客户端上通用;个别 mihomo 扩展字段在极老的内核上不可用,文中会单独标注。各客户端的平台覆盖与获取方式见安装包页面,项目间的谱系关系可参考文章《Clash、mihomo、Verge Rev 是什么关系》。

顶层结构:一份最小可用骨架

config.yaml 是一个由若干顶层键组成的映射(mapping)。抛开所有可选项,一份能跑起来的最小配置只需要五个部分:运行参数、DNS、节点列表、策略组列表、规则列表。先看骨架,后续各章逐段展开:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://223.5.5.5/dns-query

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - HK-01
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

顶层键的加载没有顺序要求,内核按键名取值;但社区约定俗成按"运行参数 → dns → proxies → proxy-groups → rules"排列,与流量处理的逻辑顺序一致,阅读与排错都更顺手。下表列出常见顶层键及其类型:

书写规范:缩进、引号与常见笔误

YAML 对格式敏感,配置报错的相当一部分根源是书写问题,而非字段用错。三条铁律:第一,缩进只能用空格,统一两格,制表符(Tab)会直接导致解析失败,且报错行号往往指向文件后面很远的位置,极难定位;第二,冒号后必须跟一个空格,port:7890 是非法写法;第三,数组元素以"短横线 + 空格"开头,短横线的缩进层级决定它属于哪个键。

字符串默认不需要引号,但三种情况必须加:值里含冒号、井号等特殊字符时;值是纯数字却希望按字符串处理时;密码、UUID 这类可能以特殊字符开头的敏感值——统一加双引号是最省心的习惯。另外注意 YAML 1.1 遗留坑:不带引号的 yes、no、on、off 会被部分解析器当成布尔值,节点名恰好叫这些词时务必加引号。

端口族:mixed-port、port 与 socks-port

端口字段决定本机应用如何把流量交给内核。mixed-port 是当前的推荐写法:单个端口同时接受 HTTP 与 SOCKS5 两种协议的入站,系统代理只需指向这一个端口,是绝大多数客户端默认生成的形态,约定值 7890。历史写法 port(纯 HTTP)与 socks-port(纯 SOCKS5)仍然有效,可与 mixed-port 并存,分别监听不同端口,适合需要区分协议入口的调试场景。

此外还有 redir-port 与 tproxy-port,面向 Linux 透明代理(配合 iptables/nftables 转发),桌面日常使用无需配置。所有端口共享同一条约束:不能与本机其他进程冲突。启动时报 bind: address already in use,就是端口被占,定位与改端口的完整步骤见文章《Clash 提示端口被占用怎么办》。

allow-lan 与 bind-address

allow-lan 控制是否接受局域网内其他设备的入站连接,默认 false(只监听 127.0.0.1)。设为 true 后,同一 Wi-Fi 下的手机、电视盒子可以把代理指向这台电脑的内网 IP 与端口,实现"一机开代理、全屋共享"。配套的 bind-address 限定监听网卡:默认 "*" 表示所有网卡,多网卡环境可以填某块网卡的地址,把入口收窄到指定网段。开启 allow-lan 意味着局域网内任何设备都能借道你的出口,公共网络环境(办公室、酒店)下应保持关闭。

mode:三种分流模式

mode 取三个值。rule 为规则模式,每条连接逐条比对 rules 列表决定走向,是日常使用的标准形态;global 为全局模式,跳过规则,所有流量交给全局出口(界面上通常表现为直接选一个节点);direct 为直连模式,所有流量不经代理,相当于临时停用分流但保留内核运行。排查"某网站到底走了哪条规则"时,可以在 global 与 rule 之间切换对照,快速判断问题在规则还是在节点。

日志与外部控制器

log-level 控制内核日志详细程度,从简到繁依次为 silent、error、warning、info、debug。日常建议 info;排错时切 debug,可以看到每条连接命中的具体规则与 DNS 解析路径;确认稳定后调回,避免日志文件无谓膨胀。external-controller 声明 RESTful 控制接口的监听地址(约定 127.0.0.1:9090),图形客户端与网页面板都通过它读取状态、切换节点;配套的 secret 为接口设置访问口令,凡是把控制器监听到 0.0.0.0 或开放给局域网的场景,secret 必须设置,例如 secret: "your-secret"。

其他常用开关

ipv6 默认 false,置 true 后内核会解析并连接 AAAA 记录,本机或节点侧 IPv6 不通时反而造成部分站点超时,建议确认链路支持后再开。unified-delay(mihomo 扩展)让延迟测试扣除握手开销,不同协议节点的延迟数字更可比。profile 块下的 store-selected: true 会记住每个策略组上次选中的节点,重启或更新订阅后不必重选,几乎所有客户端模板都默认开启。

为什么需要内置 DNS

分流的前提是"知道这条连接要去哪",而域名解析恰恰是最容易被污染或泄露的环节:如果解析交给不可信的上游,拿到的 IP 可能是错的;如果所有解析都走本地运营商,访问记录又会完整暴露。dns 模块让内核接管解析过程,配合规则系统决定"哪些域名用哪组 DNS、解析结果如何交还给应用"。在 TUN 模式或透明代理下,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"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://223.5.5.5/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enhanced-mode:fake-ip 与 redir-host

这是 dns 块里影响最大的字段。fake-ip 模式下,内核对每个域名先返回一个保留网段(由 fake-ip-range 定义,默认 198.18.0.0/16)里的假地址,应用拿假 IP 发起连接,内核在假 IP 与域名之间维护映射——好处是应用侧完全跳过真实解析,规则可以直接按域名匹配,连接建立快且无解析泄露;代价是少数依赖真实 IP 的程序(局域网发现、某些游戏联机、NTP 校时)会异常,需要把这类域名加进 fake-ip-filter 白名单,命中白名单的域名回落为真实解析。redir-host 模式则始终返回真实 IP,兼容性最好,但域名信息在部分链路上会丢失,规则命中率与解析速度都逊于 fake-ip。桌面客户端模板普遍默认 fake-ip,遇到特定应用异常再补 filter 即可。

三组上游:default-nameserver、nameserver 与 fallback

三个列表分工明确。default-nameserver 只做一件事:解析后面两组上游里 DoH/DoT 服务器自身的域名,因此必须填纯 IP,否则出现"解析器域名没人解析"的死锁。nameserver 是主力上游,承担日常全部解析,推荐填加密协议地址(https:// 开头的 DoH 或 tls:// 开头的 DoT),避免明文 53 端口在链路上被篡改。fallback 是备用上游,与 fallback-filter 联动:当 nameserver 的解析结果命中过滤条件(典型配置 geoip: true 且 geoip-code: CN,即"结果不属于中国大陆 IP")时,改用 fallback 的结果——用于对抗污染,让境外域名拿到干净解析。若不需要这套机制,可以只留 nameserver,结构更简单。

所有协议共有的四个字段

proxies 数组的每个元素定义一个节点。无论什么协议,四个字段必填:name(节点名,全文件内必须唯一,策略组与规则都靠它引用,重名会导致加载失败)、type(协议类型)、server(服务器域名或 IP)、port(服务端口)。可选的 udp 声明该节点是否转发 UDP 流量,游戏与实时通话场景建议开启(前提是服务端支持)。mihomo 支持的协议相当广:ss、vmess、trojan、vless、hysteria2、tuic、wireguard、socks5、http 等均可作为 type 取值,下面挑三种最常见的展开。

Shadowsocks(type: ss)

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

核心是加密参数:cipher 与 password 必须与服务端完全一致。常用 cipher 有 aes-256-gcm、chacha20-ietf-poly1305,以及新一代的 2022-blake3-aes-256-gcm(要求密码为 Base64 编码的定长密钥,不能随手填字符串)。加密参数不匹配的典型症状是连接立即断开且日志报解密错误。若服务端启用了插件(如 obfs),还需补 plugin 与 plugin-opts 两个字段。

VMess(type: vmess)

  - name: "JP-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 23ad6b10-8d1a-40f7-8ad0-e3e35cd38297
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ray
      headers:
        Host: jp01.example.com

身份凭证是 uuid,由服务端下发,一字不差照抄。alterId 在现代部署下固定为 0(启用 AEAD)。network 决定传输层形态:tcp 直连、ws 走 WebSocket(常配合 CDN 中转)、grpc 走 gRPC;选了 ws 就要在 ws-opts 里给出 path 与 Host 头,三者与服务端不一致都会握手失败。tls: true 时可用 servername 单独指定 SNI(用于 server 填 IP 而证书签给域名的场景)。

Trojan(type: trojan)

  - name: "SG-01"
    type: trojan
    server: sg01.example.com
    port: 443
    password: "your-password"
    sni: sg01.example.com
    skip-cert-verify: false
    udp: true

Trojan 天然运行在 TLS 之上,伪装为普通 HTTPS 流量。sni 应与服务端证书的域名一致;skip-cert-verify 控制是否跳过证书校验,保持 false 是底线——置 true 意味着放弃对服务器身份的验证,任何中间人都能冒充节点。只有自签证书的测试环境才有理由临时打开。代理链路上证书报错的成因与排查方法,详见文章《开启代理后 HTTPS 证书报错的几种成因》。

策略组是什么

proxy-groups 在节点与规则之间加了一层抽象:规则不直接指向某个节点,而是指向一个策略组;组内再按既定策略(手选、自动测速、故障转移等)决定实际出口。好处显而易见——换节点只需在组里换,几百条规则一行不动;订阅更新导致节点改名,也只影响组的成员列表。组的 proxies 成员可以是节点名、内置策略 DIRECT(直连)与 REJECT(拒绝),也可以是另一个组的名字,由此可以搭出"地区组 → 总出口组"的层级结构;唯一的限制是不能出现循环引用。

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - AUTO
      - HK-01
      - JP-01
      - DIRECT

  - name: "AUTO"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - HK-01
      - JP-01
      - SG-01

五种组类型逐一说明

自动类组(url-test/fallback/load-balance)依赖三个测速参数:url 指定探测地址,惯用返回 204 空响应的轻量端点;interval 为探测周期(秒),300 是常见平衡点,调得过小会产生持续的测速流量;tolerance 仅 url-test 使用,表示"新旧最优节点延迟差超过该毫秒数才切换",用于抑制两个延迟接近的节点来回抖动。lazy: true(mihomo 扩展)让组在未被使用时暂停探测,节点很多时能明显减少后台请求。load-balance 另有 strategy 字段:consistent-hashing 让同一目标站点尽量固定走同一节点(登录态友好),round-robin 则严格轮流。

组的组织建议

实践中推荐三层结构:最上层一个 select 总出口(规则主要指向它);中间按地区各建一个 url-test 自动组;底层是节点本身。再为流媒体、AI 服务这类有落地区域要求的业务单独建 select 组,成员引用地区组。这样日常零操作(自动测速接管),特殊业务可人工钉住地区,订阅更新的影响面也被隔离在地区组内部。

基本格式与匹配顺序

rules 数组的每个元素是一行字符串,格式为 类型,匹配值,策略 三段逗号分隔;策略段可以填组名、节点名或内置的 DIRECT/REJECT。内核对每条新连接自上而下逐条比对,命中第一条即停止——这条纪律决定了一切:精确规则(完整域名)必须写在宽泛规则(后缀、关键词、GEOIP)之前,否则永远轮不到;列表末尾以 MATCH 兜底,吸收所有未命中流量。规则数量对性能影响很小(域名规则走前缀树索引),但顺序错误造成的分流错误非常隐蔽,建议每次改动后用日志验证命中情况。

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,tracker,REJECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOSITE,category-ads-all,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

规则类型对照

no-resolve 与域名/IP 规则的相互作用

IP 类规则(IP-CIDR/GEOIP)有一个容易被忽略的副作用:当连接目标还是域名时,想比对 IP 就必须先解析——这次解析可能走本地 DNS,造成泄露,也拖慢匹配。给 IP 规则追加第四段 no-resolve,表示"目标本来就是 IP 才比对,是域名就跳过本条",内网网段规则应当一律带上。整体排序心法:域名类规则在前、IP 类在后、MATCH 收尾;广告拦截(REJECT)放在同类域名规则的最前面。规则书写的完整专题(含自定义规则应插在订阅规则之前还是之后)见文章《Clash 自定义规则怎么写》。

rule-providers:把规则外置

rule-providers:
  streaming:
    type: http
    behavior: classical
    format: yaml
    url: https://example.com/rules/streaming.yaml
    path: ./rules/streaming.yaml
    interval: 86400

rules:
  - RULE-SET,streaming,PROXY

成千上万条规则塞进主文件既难维护也难分享,rule-providers 允许从外部 URL 或本地文件加载规则集,按 interval 秒数周期刷新。behavior 声明集合内容形态:domain(纯域名列表)、ipcidr(纯网段列表)、classical(与 rules 相同的完整三段式)。behavior 与文件实际内容不匹配时集合会静默失效,这是外置规则"看起来加载了却不生效"的头号原因。

为什么不能直接改订阅文件

订阅型用户面对一个结构性矛盾:配置文件由服务商生成,每次更新订阅整份文件都会被重新下载覆盖——你在里面手工加的规则、改的端口,寿命只到下一次更新为止。正确的做法是把"服务商的基底配置"与"你自己的修改"分离存放,由客户端在加载时合并成最终配置。这套机制在不同客户端里叫法不一:覆写、Override、Merge、扩展配置,原理一致。

合并的基本语义

合并配置本身也是一份 YAML,只写你要改动的部分。语义分两类:标量与映射字段直接替换——覆写里写 mixed-port: 7891,最终配置的端口就是 7891,写一个完整的 dns: 块则整块替换基底的 dns;数组字段支持前插与追加——多数客户端约定 prepend- 前缀表示插到基底数组头部、append- 前缀表示接到尾部,这对 rules 至关重要:前插的规则优先级高于订阅规则,追加的则只能兜底。一份典型覆写:

mixed-port: 7891
log-level: warning

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

append-proxies:
  - name: "SELF-01"
    type: ss
    server: my.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

脚本覆写与 proxy-providers

当声明式合并不够用——例如要按名字批量过滤节点、给所有组统一插入某个成员——部分客户端(如 Verge Rev)支持 JavaScript 脚本覆写:脚本接收解析后的配置对象,返回修改后的对象,自由度最高,代价是出错时整份配置加载失败,应当小步修改、逐次验证。另一条思路是反过来:不用服务商的整份配置,只通过 proxy-providers 引用订阅的节点部分,策略组与规则完全自建。这样订阅更新只影响节点池,主配置永远是你自己的,适合已经读完本手册、愿意维护自有规则体系的用户:

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

proxy-groups:
  - name: "PROXY"
    type: select
    use:
      - airport

注意组通过 use 字段引用 provider(而不是 proxies),两者可以并用;health-check 让 provider 内的节点也参与可用性探测。

加载前:静态校验

改完配置不要直接重启碰运气。装有 mihomo 内核可执行文件的环境下,一条命令即可做纯语法与语义检查,不启动任何监听:

mihomo -d . -t -f config.yaml

-t 表示测试模式,-d 指定工作目录(GeoIP 数据等资源从这里找),-f 指定待检文件。输出 configuration file ... test is successful 即通过;报错信息会给出行号与原因,常见的有:缩进错误(yaml: line N)、节点重名(proxy N: name duplicated)、组引用了不存在的成员(proxy group ... proxy not found)、规则策略段拼写错误。图形客户端在导入时也会做同等校验,报错弹窗里的信息与命令行一致,照行号回文件定位即可。

加载后:验证分流是否符合预期

配置加载成功不等于行为正确。三步验证法:第一步看日志,把 log-level 临时调到 debug,访问目标网站,日志会打印这条连接命中的规则与最终出口,是判断"到底走了哪条规则"的唯一权威依据;第二步看连接面板,图形客户端的连接页实时列出活动连接的目标、命中规则与出口组,适合观察整体流量分布;第三步做外部验证,直连与代理状态下分别访问 IP 检测服务,确认出口地址确实随策略变化。若分流正确但特定应用不走代理,优先怀疑应用绕过了系统代理——Windows 商店应用的回环限制就是典型案例,解法见文章《Windows 商店应用不走代理的原因》。

高频故障速查

更多按症状组织的问答收录在常见问题页;若怀疑问题出在客户端本身而非配置,可到安装包页面换用其他客户端交叉验证——全平台首推 Clash Plus,同一份配置在不同客户端上的表现差异,往往能快速锁定问题层级。