配置文件整体结构与阅读顺序

Clash 的 config.yaml 是一个 YAML 格式的文本文件,客户端启动时按顺序读取顶层字段。理解它的最佳方式,是把文件从上到下分成四段:通用设置、DNS 配置、节点定义、策略组与规则。

YAML 的语法约束很直接:缩进用空格(禁止 Tab),同级字段缩进必须一致,键与值之间用英文冒号加空格分隔。字段顺序本身不影响解析,但 proxies、proxy-groups、rules 之间存在引用关系:策略组引用的节点名必须先在 proxies 里定义,规则引用的策略组名必须先在 proxy-groups 里定义。按「通用 → DNS → proxies → proxy-groups → rules」的顺序书写,既符合阅读直觉,也避免引用未定义名称的报错。

一个最小可用配置的骨架:

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

dns:
  enable: true
  nameserver:
    - 223.5.5.5

proxies:
  - name: "示例节点"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-256-gcm
    password: "example-password"

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

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

这个骨架省略了 ipv6、external-controller 等可选字段,但已经能完成「启动 → 走代理 → 规则分流」的完整链路。

通用字段:端口、模式与日志

顶层通用字段控制客户端的基础行为,下表列出最常用的几个:

字段 示例值 作用
port 7890 HTTP 代理监听端口
socks-port 7891 SOCKS5 代理监听端口
allow-lan false 是否允许局域网设备连接
mode rule 运行模式:rule / global / direct
log-level info 日志级别:silent / error / warning / info / debug
ipv6 false 是否启用 IPv6 流量
external-controller 127.0.0.1:9090 外部控制 API 监听地址

mode 是三个取值最容易混淆的字段。rule 模式按 rules 区规则逐条匹配,命中即转发,这是日常使用最常见的模式;global 模式让所有流量都走 proxy-groups 里第一个策略组,绕过 rules 匹配;direct 模式让所有流量直连,相当于全局绕过代理,适合排查节点故障。

port 与 socks-port 可以同时监听,也可以只开其中一个。如果本机 7890 被其他程序占用,启动日志会提示 bind: address already in use,把端口改成 7897 之类未占用的值即可。

external-controller 提供 RESTful API,Clash Verge 的面板、Yacd、Metacubexd 都通过这个地址读取与修改配置。默认绑定 127.0.0.1 只允许本机访问;如果设置了 secret 字段,访问 API 时需要带上对应的请求头。

log-level 建议日常用 info,排查问题时临时切成 debug。debug 会输出每条连接的规则命中信息:

[TCP] dial Match(DomainSuffix): github.com → PROXY
[UDP] dial Match(GEOIP): 8.8.8.8 → DIRECT

这类日志能直接告诉你流量被哪条规则接走,是调试分流最有效的抓手。

DNS 配置段:nameserver 与 fallback 的分工

dns 段决定域名解析走哪条路径,是配置里第二重要的部分。核心字段如下:

字段 示例值 作用
enable true 是否接管系统 DNS
listen 0.0.0.0:53 DNS 服务监听地址
nameserver 223.5.5.5, 119.29.29.29 默认解析服务器
fallback 8.8.8.8, 1.1.1.1 备用解析服务器
fallback-filter geoip: true 触发 fallback 的条件
default-nameserver 223.5.5.5 解析节点域名所用的服务器

nameserver 负责解析大多数域名,一般填国内公共 DNS,例如 223.5.5.5(阿里)与 119.29.29.29(腾讯),响应快且没有污染问题。

fallback 用于处理被污染的域名:当 nameserver 返回的 IP 被 geoip 判定为保留地址时,客户端会用 fallback 里的服务器重新解析一次。简单场景下,把 fallback 填成 8.8.8.8 与 1.1.1.1 即可。

这里有一个容易踩的坑:如果 proxies 里的节点使用域名而不是 IP,客户端解析节点域名时也会走 dns 段。一旦节点域名被污染,所有节点都会连不上。所以 default-nameserver 必须填一个可靠的国内 DNS,并且不要把节点域名解析交给 fallback 流程。TUN 模式下,dns 段的 enable 必须为 true,否则开启 TUN 后系统流量无法正确解析域名。

proxies 节点:每种协议怎么定义

proxies 是一个数组,每个元素定义一个代理节点。不同协议共享 name、type、server、port 四个基础字段,协议专属字段各不相同。

SS 节点的字段最少:

- name: "SS-东京"
  type: ss
  server: 203.0.113.10
  port: 443
  cipher: aes-256-gcm
  password: "your-password"

cipher 常见取值有 aes-256-gcm、chacha20-ietf-poly1305、2022-blake3-aes-256-gcm 等。密码必须与订阅服务商提供的一致,否则握手阶段会直接失败。

VMess 节点多出 uuid、alterId 与传输层字段:

- name: "VMess-新加坡"
  type: vmess
  server: 203.0.113.20
  port: 443
  uuid: "550e8400-e29b-41d4-a716-446655440000"
  alterId: 0
  cipher: auto
  network: ws
  ws-opts:
    path: "/path"
    headers:
      Host: "example.com"

alterId 在较新的服务端实现里通常为 0。network 为 ws 时必须配合 ws-opts 的 path 与 Host 使用,两者与订阅服务商的配置一一对应,填错会导致 TLS 握手后无法建立隧道。

Trojan 节点结构与 VMess 类似,但没有 uuid:

- name: "Trojan-洛杉矶"
  type: trojan
  server: 203.0.113.30
  port: 443
  password: "your-password"
  sni: "example.com"
  skip-cert-verify: false

sni 用于 TLS 的 SNI 扩展,必须与证书域名一致。skip-cert-verify 默认 false,不建议改成 true,除非节点证书本身不合法且你确认风险可接受。

Hysteria2 节点额外需要 up 与 down 带宽参数:

- name: "Hysteria2-香港"
  type: hysteria2
  server: 203.0.113.40
  port: 443
  password: "your-password"
  up: "50 Mbps"
  down: "200 Mbps"
  sni: "example.com"

up/down 声明客户端可用带宽,数值偏小会限制传输速度,偏大可能导致拥塞。

proxy-groups 策略组:选择逻辑如何嵌套

proxy-groups 定义策略组,组内 proxies 列表可以引用节点,也可以引用其他策略组。四种常用类型:

类型 行为 适用场景
select 手动选择一个节点 日常主力,手动切换
url-test 定时测速,自动选延迟最低的节点 追求自动择优
fallback 按列表顺序使用,故障时切换下一个 需要固定优先级
load-balance 在多个节点间均衡分配流量 多节点聚合带宽

select 类型最直观:

- name: PROXY
  type: select
  proxies:
    - "SS-东京"
    - "VMess-新加坡"
    - "Trojan-洛杉矶"
    - DIRECT
    - REJECT

url-test 需要额外配置测速地址与间隔:

- name: Auto
  type: url-test
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  tolerance: 50
  proxies:
    - "SS-东京"
    - "VMess-新加坡"

interval 单位是秒,300 表示每 5 分钟测一次速。tolerance 表示延迟差小于 50ms 时不切换,避免频繁抖动。

策略组可以嵌套,这是进阶写法:

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - "SS-东京"
      - DIRECT
  - name: Auto
    type: url-test
    proxies:
      - "SS-东京"
      - "VMess-新加坡"

这里 PROXY 组的第一个选项是 Auto 组,选中 Auto 后实际流量由 url-test 自动决定。嵌套层数没有硬性限制,但建议不超过两层,否则排查「当前走的哪个节点」会变得困难。

rules 规则区:匹配顺序决定流量走向

rules 是配置的最后一节,也是流量分流的核心。Clash 按顺序逐条匹配,命中第一条就停止,不再继续往下看。因此规则顺序非常关键。

常用规则类型:

规则前缀 匹配对象 示例
DOMAIN 完整域名 DOMAIN,www.google.com,PROXY
DOMAIN-SUFFIX 域名后缀 DOMAIN-SUFFIX,google.com,PROXY
DOMAIN-KEYWORD 域名关键字 DOMAIN-KEYWORD,github,PROXY
IP-CIDR IPv4 网段 IP-CIDR,192.168.0.0/16,DIRECT
GEOIP 国家或地区 GEOIP,CN,DIRECT
PROCESS-NAME 进程名 PROCESS-NAME,wechat.exe,DIRECT
MATCH 兜底 MATCH,PROXY

一个生产可用的 rules 示例:

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,youtube.com,PROXY
  - DOMAIN-KEYWORD,github,PROXY
  - MATCH,PROXY

注意上面这个顺序:局域网与国内流量先被 DIRECT 接走,再匹配国外域名走 PROXY,最后 MATCH 兜底。如果把 DOMAIN-SUFFIX,google.com,PROXY 放到 GEOIP,CN,DIRECT 前面,google.com 的解析结果如果是国内 IP(例如被 CDN 调度到国内节点),就会错误地直连。

规则名(最后一个字段)必须是 proxy-groups 里定义的组名,或者 DIRECT、REJECT 这两个内置目标。引用不存在的组名,配置校验会直接报错。

规则顺序即优先级。Clash 从 rules 第一条开始逐条匹配,命中即停止。把宽泛规则(如 GEOIP,CN,DIRECT)放在具体规则(如 DOMAIN-SUFFIX,google.com,PROXY)之前,后者将永远没有机会命中。

校验配置与常见错误

写完 config.yaml 后,先用命令行校验语法,再启动客户端,能省下大量排查时间。mihomo 内核的校验命令:

./mihomo -t -f config.yaml

输出 configuration file ... test is successful 表示通过。Clash Verge 的「设置」→「参数设置」里也提供配置检查入口,本质上调用的是同一条校验逻辑。

常见错误按出现频率排序:

  1. 缩进用了 Tab。YAML 只认空格,编辑器里勾选「将 Tab 转为空格」即可避免。
  2. 冒号后漏空格。port:7890 会被解析成字符串键,而不是端口字段。
  3. 密码等特殊字符未加引号。密码含 #、:、* 等字符时必须用双引号包裹,否则 YAML 会把它当成注释或结构符号。
  4. 引用了未定义的节点名或策略组名。检查 proxies 的 name 与 proxy-groups 的 proxies 列表是否完全一致。
  5. 重复定义同名节点。后一个定义会覆盖前一个,容易造成「改了配置但行为没变」的假象。

把校验命令的输出与上面这张清单对照,绝大多数配置问题都能在 5 分钟内定位。