进阶配置 预计阅读 9 分钟

Clash 配置文件 YAML 结构逐段解析:从端口设置到 rules 规则段

按 config.yaml 从上到下的顺序讲清每一段的作用:通用端口与模式、dns、proxies、proxy-groups、rules,标注常见缩进错误与字段拼写陷阱。

Clash 与 Clash Meta(mihomo)的核心配置文件都是一份 YAML 文档,习惯上命名为 config.yaml。它由若干顶层段落拼接而成,每一段各自负责一件事——端口和运行模式、DNS 解析方式、节点列表、策略组、分流规则。理解这几段的先后关系与字段含义,比死记某个"万能配置"更有用,因为订阅提供的远程配置经常需要手动核对或合并本地设置,读不懂结构就很容易改错一个缩进导致整份文件失效。本文按文件从上到下的顺序逐段拆解,并在每一段列出实际踩过的坑。

通用设置段:端口、模式与允许局域网

文件最上方通常是一批平铺的键值对,负责定义客户端本身的行为,与具体节点无关。常见字段如下:

port: 7890
socks-port: 7891
redir-port: 7892
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

port 是 HTTP 代理端口,socks-port 是 SOCKS5 代理端口,两者互不影响,可以同时开启也可以只留一个。redir-port 用于透明代理场景,普通桌面用户很少需要它。allow-lan 决定是否允许局域网内其他设备通过本机 IP 走代理,给手机或路由器共享上网时需要改成 true,同时要注意防火墙放行对应端口。

mode 有三个取值:rule 表示按规则段分流,global 表示所有流量强制走某个节点(常用于排查节点本身是否可用),direct 表示全部直连不走代理。日常使用应保持 rule,临时测试节点连通性时才切到 global,测完记得切回来,否则会发现"明明配置了规则却全部走了代理"这种误会。external-controller 开启后客户端会暴露一个本地 API 端口,给 Dashboard 面板或第三方工具读取运行状态用,不需要这项功能的话可以留空或删除该行。

dns 段:解析方式决定分流是否精准

dns 段控制域名解析行为,写得不合适会直接影响规则分流的准确度,尤其是启用 TUN 模式时。一段常见的写法:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - tls://dns.rubyfish.cn:853
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - localhost.ptlogin2.qq.com

default-nameserver 是用来解析下面 nameserver 里那些 DoH/DoT 地址本身的域名的服务器,必须填纯 IP,不能再填域名地址,否则会出现"解析服务器的域名"这种循环依赖导致启动报错。nameserver 是真正对外提供解析的服务器列表,fallback 是当 nameserver 判断结果可能被污染时启用的备用列表,常搭配 fallback-filter 按地理位置或返回的 IP 段判断。

fake-ip-range 与 TUN 模式配合使用,客户端会给域名分配一个假 IP 段内的地址,再在流量层面还原真实域名去匹配规则,这样可以让基于域名的分流规则在全局代理模式下依然生效。fake-ip-filter 里列出的域名(比如内网域名、局域网设备名)不会被分配假 IP,而是走真实 DNS 解析,写错这一项常见后果是局域网设备(NAS、打印机、路由器管理页)突然无法访问。

注意:如果不打算使用 TUN 模式,也不确定 fake-ip 的影响范围,可以把 dns 段整体保持默认或直接沿用订阅方给出的配置,不要随意精简字段,DNS 配置错误往往表现为"某些网站能开某些不能开",排查成本较高。

proxies 段:节点列表的字段规范

proxies 是一个数组,每个元素描述一个节点,字段随协议类型不同而不同。以最常见的 ss(Shadowsocks)和 vmess 举例:

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example-node.invalid
    port: 8443
    cipher: aes-256-gcm
    password: "your-password-here"

  - name: "SG-02"
    type: vmess
    server: sg02.example-node.invalid
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ws

几个高频出错点:name 是给人看的标识,proxy-groups 引用节点时靠这个名字精确匹配,改名之后如果没同步改 proxy-groups 里的引用,该节点就会在策略组里"消失";type 决定该条目后续字段的解析方式,拼错(比如把 vmess 写成 vmes)会导致这个节点被整体忽略,通常客户端不会报错,只是节点列表里少了一个,排查起来容易被忽略;password、uuid 建议加英文引号包裹,尤其密码里含有 :、# 等 YAML 特殊字符时,不加引号会被解析成别的结构导致节点整条失效。

如果节点由订阅链接自动生成,proxies 段一般不需要手动编辑,客户端会在导入订阅时自动填充;只有自建节点或手工添加单个节点时才会直接改这一段。

proxy-groups 段:把节点组织成可选择的策略组

proxy-groups 决定用户在客户端界面上能看到、能切换的选项,以及规则段最终引用的分流出口。三种最常用的类型:

proxy-groups:
  - name: "自动选择"
    type: url-test
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300

  - name: "故障转移"
    type: fallback
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300

  - name: "节点选择"
    type: select
    proxies:
      - 自动选择
      - HK-01
      - SG-02
      - DIRECT

url-test 按延迟自动挑选当前最快节点,fallback 按列表顺序优先使用第一个可用节点,select 是手动选择,允许用户在客户端界面里点选。注意 select 类型的 proxies 列表里可以直接引用另一个策略组的名字(如上面的"自动选择"),这是嵌套策略组的常见写法,方便把"自动测速"包装成"节点选择"里的一个选项。proxies 列表里的名字必须与 proxies 段里的 name 或另一个策略组的 name 完全一致,大小写、全角半角字符都要对齐,写错一个字符会导致该策略组启动时报错或该选项被静默剔除。

interval 是测速间隔,单位秒,数值过小会增加测速频率、耗费额外流量与耗电;url 建议用连通性判断专用的检测地址,不要填普通网站地址,否则测速结果可能被网站本身的响应速度干扰。

rules 段:分流规则的匹配顺序与写法

rules 是文件最后一段,也是逐行从上往下匹配、匹配到第一条就停止的段落,顺序错误是最常见也最难自查的问题。基本语法:

rules:
  - DOMAIN-SUFFIX,google.com,节点选择
  - DOMAIN-KEYWORD,github,节点选择
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

每一行由「匹配类型,匹配内容,出口策略组」三段组成,部分类型还带第四个可选参数(如 no-resolve 表示不对该规则做 DNS 解析,常用在 IP 段规则上以提升效率)。DOMAIN-SUFFIX 匹配域名及其子域名,DOMAIN-KEYWORD 匹配域名中包含的关键词,IP-CIDR 匹配 IP 段,GEOIP 匹配 IP 所属国家/地区,MATCH 是兜底规则,必须放在整个 rules 段的最后一行,代表"以上都不匹配时走这里"。

由于是顺序匹配,如果把一条宽泛规则(比如某个 GEOIP,CN,DIRECT)写在具体规则前面,后面针对特定域名的规则永远不会被触发,表现为"明明配了某个网站走代理但实际没生效"。正确的组织顺序应该是:先写具体的域名/应用规则,再写宽泛的地区/IP 段规则,最后以 MATCH 收尾。

建议:规则数量较多时,可以把规则集拆分成远程规则集(rule-providers)引用,减少手写行数,同时便于统一更新,具体写法可参考客户端自带的示例配置或官方文档中的 rule-providers 段说明。

常见缩进错误与字段拼写陷阱

YAML 对缩进极其敏感,以下几类错误在实际使用中反复出现:

  • 混用空格与 Tab:YAML 规范不允许用 Tab 缩进,文本编辑器如果自动把缩进转成 Tab,客户端会在启动时直接报语法错误,建议用支持"以空格代替 Tab"的编辑器打开配置文件。
  • 同级字段缩进不一致:同一个数组元素内的字段必须严格对齐同一列,哪怕多出一个空格也会被解析成子层级,导致该字段被忽略或整个节点解析失败。
  • 字符串未加引号导致的类型误判:密码、UUID 中含有会被 YAML 当作特殊符号的字符(冒号、井号、方括号)时必须加引号,否则解析结果和预期不符。
  • 字段名拼写错误但不报错:多数客户端对未知字段采取"忽略"而非"报错"的策略,比如把 allow-lan 拼成 allow_lan,配置文件依然能正常加载,只是这项设置悄悄失效,排查时容易被忽略,建议改动关键字段后重新检查客户端日志或用官方示例核对字段名。
  • proxy-groups 引用的节点名不存在:节点改名、删除后没有同步更新引用,策略组会缺一个选项甚至加载失败,建议改动 proxies 段后用全文搜索确认该节点名在 proxy-groups 里的引用也同步更新。

把这几段结构和常见坑点对照着看一遍配置文件,基本可以定位大多数"订阅能导入但规则不生效""改了端口却没起作用"之类的问题。如果手动改动后客户端无法启动,优先检查最近改动的那一段缩进,再确认字段名拼写与官方文档一致,通常问题就出在这两类原因里。

下载客户端