Clash 配置文件结构详解:YAML 每一段字段的作用与写法

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

Clash 与 Clash Meta(mihomo 内核)的配置文件都是一份 YAML 文本,通常命名为 config.yaml。订阅链接背后其实也是同一份格式的文件,客户端下载后会把它保存到本地目录再解析加载。整份文件按顶层键组织,常见的顶层键包括 port、socks-port、mixed-port、allow-lan、mode、log-level、dns、proxies、proxy-groups、rules,以及 Meta 内核特有的 tun。这些键处于同一缩进层级,谁也不包含谁,顺序理论上不影响解析,但为了排查方便,大多数配置习惯把运行参数放最前,规则放最后。

YAML 靠缩进表达层级关系,不认 Tab 键,只认空格,且同一层级的缩进空格数必须完全一致。字符串大多数时候不需要加引号,但如果值里包含冒号、井号或者以数字开头却要当字符串处理,就应该加上英文引号。列表项用短横线加空格开头,字典项用冒号加空格分隔键值。这几条规则看起来简单,却是后面所有报错的根源,建议在改配置前先记熟。

基础运行段:端口、局域网与运行模式

配置文件最上方一般是一组控制客户端自身行为的字段,决定监听端口、是否允许局域网设备接入,以及流量的处理模式。

port: 7890
socks-port: 7891
mixed-port: 7893
allow-lan: true
bind-address: "*"
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

• port:HTTP 代理监听端口,系统代理设置里填的就是这个值。
• socks-port:SOCKS5 代理端口,部分命令行工具或游戏客户端需要单独配置这个协议。
• mixed-port:同一端口同时接受 HTTP 与 SOCKS5 请求,现在的图形客户端大多只用这一个端口,和 port/socks-port 可以只保留其一。
• allow-lan:是否允许同一局域网内的其他设备通过本机代理上网,默认为 false,给手机、平板共享代理时需要改成 true。
• mode:核心工作模式,rule 按规则分流是最常用的选择,global 全局走同一个节点,direct 则完全不代理,只用于临时调试。
• log-level:日志详细程度,排查问题时可以临时改成 debug,日常使用建议保持 info 或 warning,避免日志面板信息过多影响查看。

DNS 段:字段含义与常见取值

dns 段控制域名解析的方式,配置得当能减少域名泄露与解析延迟,配置不当则容易出现网页打不开或者解析到错误地址的情况。一段常见写法如下:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.example-provider.net/dns-query
    - tls://dot.example-provider.net:853
  fallback:
    - https://fallback-doh.example-provider.net/dns-query
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

• enable:是否启用内置 DNS 服务器接管解析,关闭后会退回系统自身的 DNS 设置。
• default-nameserver:用来解析 nameserver 里那些 DoH/DoT 地址本身的域名,必须填纯 IP,不能再填域名地址,否则会出现「解析服务器的域名」这一先有鸡还是先有蛋的问题。
• nameserver:实际用于解析日常域名的服务器列表,支持传统 UDP 地址,也支持 https:// 开头的 DoH 与 tls:// 开头的 DoT,加密解析能减少被运营商劫持的概率。
• fallback:当 nameserver 判断某个域名可能被污染时,转而使用的备用解析列表,常配合 fallback-filter 一起使用。
• enhanced-mode:增强模式,fake-ip 会给域名分配一个虚构的内网地址再在出口还原成真实域名,兼容性好也是大多数客户端的默认值;redir-host 则是较老的兼容方案,一般不再推荐。
• fake-ip-filter:排除在 fake-ip 之外的域名列表,局域网设备名、公司内网域名等建议加入这个列表,否则可能出现无法访问内网服务的情况。

proxies 段:节点字段怎么填

proxies 是一个列表,每一项描述一个可用的代理节点,常见协议包括 ss(Shadowsocks)、vmess、trojan 以及 Meta 内核额外支持的 hysteria2。字段因协议不同略有差异,但都会包含名称、服务器地址、端口这三项基础信息。

proxies:
  - name: "示例-香港-01"
    type: ss
    server: node1.example-relay.net
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

  - name: "示例-日本-01"
    type: vmess
    server: node2.example-relay.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /path
      headers:
        Host: node2.example-relay.net

• name:节点在客户端界面显示的名称,后面 proxy-groups 引用节点时靠这个名字匹配,改名后要同步检查分组里的引用是否还对得上。
• type:协议类型,决定后面需要填哪些额外字段。
• server / port:节点服务器地址与端口,直接从订阅商提供的信息里获取。
• udp:是否为该节点开启 UDP 转发,游戏联机、部分语音通话依赖 UDP,若客户端支持建议保持开启。
• tls / network / ws-opts:传输层与 TLS 相关设置,涉及 WebSocket 路径、伪装域名等,通常照抄订阅商给出的参数即可,手动改动前建议先备份原文件。

绝大多数用户不需要手写这一整段——订阅链接更新时,客户端会自动重新生成这部分内容,手动编辑更多用于本地调试单个自建节点或者临时修正某个字段的错误取值。

proxy-groups 段:分组类型与写法

proxy-groups 决定节点如何被归类展示,以及切换、测速的行为逻辑。每个分组至少要有 name、type、proxies 三项。

proxy-groups:
  - name: "自动选择"
    type: url-test
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50
    proxies:
      - "示例-香港-01"
      - "示例-日本-01"

  - name: "节点选择"
    type: select
    proxies:
      - "自动选择"
      - "示例-香港-01"
      - "示例-日本-01"
      - DIRECT

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

• select:手动选择型分组,界面上呈现为一个下拉列表,适合放在最外层给用户手动切换。
• url-test:自动测速型分组,按 interval 设定的周期(单位秒)访问 url 测试延迟,自动选用延迟最低且优于 tolerance 容差范围的节点。
• fallback:故障转移型分组,按列表顺序尝试,当前节点不可用时自动切到下一个,适合对稳定性要求高于速度的场景。
• load-balance:负载均衡型分组,按策略把请求分摊到多个节点,适合多节点带宽叠加的场景。

分组的 proxies 列表里既可以填具体节点名,也可以填另一个分组的名字,还可以填 DIRECT(直连)或 REJECT(拒绝)这两个内置策略名,这也是「节点选择」分组里嵌套「自动选择」分组的常见写法。

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

rules 段是分流真正生效的地方,每一行格式固定为「规则类型,匹配内容,目标策略」,自上而下逐条匹配,命中第一条就停止,后面的规则不会再生效,所以顺序很重要。

rules:
  - DOMAIN-SUFFIX,example-streaming.com,节点选择
  - DOMAIN-KEYWORD,example-ads,REJECT
  - DOMAIN,api.example-tool.dev,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

• DOMAIN / DOMAIN-SUFFIX / DOMAIN-KEYWORD:分别是精确匹配、匹配域名后缀、匹配域名中包含的关键词,后缀匹配最常用,一条规则能覆盖一个域名下的所有子域名。
• IP-CIDR / IP-CIDR6:按 IP 段匹配,常用于把局域网地址、内网地址直接放行,no-resolve 表示不对域名做额外解析,直接按目标 IP 判断,可以减少不必要的 DNS 查询。
• GEOIP:按目标 IP 所属国家或地区匹配,GEOIP,CN,DIRECT 是几乎所有配置都会保留的一条,让国内地址直连,减少代理带来的多余绕行。
• MATCH:兜底规则,放在最后一行,代表前面所有规则都没匹配上的流量该怎么处理,遗漏这一行会导致未命中的流量走向不确定。

规则里出现的策略名必须和 proxy-groups 里的 name 完全一致,包括大小写与中文全角/半角字符,这是新手最容易忽略的细节之一——分组明明存在,规则却提示策略不存在,往往就是名字打错了一个字。

常见缩进与语法错误排查

手动改配置文件报错,九成以上是缩进或标点问题,可以按下面的顺序自查:

1. 检查是否混用了 Tab 与空格,建议用文本编辑器把 Tab 统一替换成两个或四个空格,并全文保持一致。
2. 检查同一层级的列表项是否对齐,比如 proxies 下每一个 - name: 前面的空格数必须相同。
3. 检查字符串是否需要加引号,像 UUID、密码里包含冒号或者以数字开头的字符串,建议统一加上英文双引号,避免被 YAML 解析成非字符串类型。
4. 检查规则行里的逗号是否用了中文全角逗号,全角逗号在 YAML 里不会被当作分隔符,规则会整体失效或报错。
5. 如果一时定位不到具体哪一行出错,可以把配置分段注释掉再逐段还原,快速缩小出错范围。

改完之后怎么验证

保存配置后,大多数客户端支持在界面上直接「重新加载配置」,不需要重启整个程序。加载失败时,客户端一般会在日志面板或者弹窗里提示具体出错的行号,对照上面的排查顺序基本能找到问题。加载成功后,建议按以下几点确认修改确实生效:

• 在代理页面查看目标分组下的节点列表是否和刚才编辑的一致。
• 切换到日志页面,把日志级别调到 debug,访问一个用于测试的域名,观察是否命中了预期的规则和策略。
• 用命令行工具访问一个已知的检测地址,确认返回的出口信息和预期节点一致,再把日志级别改回日常使用的 info。