进阶配置 2026-05-08 预计阅读 9 分钟

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

一份完整的 Clash 配置由通用字段、DNS、proxies、proxy-groups、rules 等段落组成。本文按从上到下的顺序逐段说明每个字段的作用、常用取值与易错的缩进格式问题。

配置文件的基本结构与加载方式

Clash 系列客户端(包括原版 Clash、Clash Meta 及其分支内核 mihomo)读取的核心配置是一份 YAML 格式文本,通常命名为 config.yaml。无论配置来自订阅链接自动下载,还是手工导入本地文件,客户端最终都会把这份文本解析成结构化数据,再按其中声明的端口、代理节点、策略组、规则依次初始化对应模块。理解这份文件的段落划分,是排查“规则不生效”“节点分组显示为空”等问题的前提。

一份配置文件按惯例自上而下分为五大段落:通用运行参数、DNS 解析设置、proxies 节点列表、proxy-groups 策略组、rules 规则表。段落之间没有强制的顺序要求,内核解析时是按字段名匹配而非按行号匹配,但绝大多数订阅生成工具与主流模板都遵循这个顺序,本文也按此顺序讲解,方便对照实际文件逐段核对。

YAML 本身是一种依赖缩进表达层级关系的格式,不使用花括号或结束标签,这意味着同一段落内,子字段的缩进空格数必须完全一致,且不能用 Tab 字符代替空格。这是新手手工修改配置时最容易踩坑的地方,后文会单独用一节展开说明。

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

文件最顶部通常是一组独立的键值对,不属于任何嵌套结构,常见字段如下:

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

各字段的作用分别是:

  • port / socks-port:分别声明 HTTP 代理端口与 SOCKS5 代理端口,系统或应用手动配置代理时需要用到具体数值。
  • mixed-port:一个端口同时支持 HTTP 与 SOCKS5 协议的混合监听,配置了它之后前两项可以省略,大多数图形化客户端默认只用这一项。
  • allow-lan:是否允许局域网内其他设备通过本机代理端口连接,手机、平板共享同一台电脑的代理时需要开启。
  • mode:全局运行模式,常见取值 rule(按规则表分流)、global(全部流量走同一个代理)、direct(全部直连不经代理)。日常使用应选 rule,只有排查问题时才临时切换到另外两种做单变量测试。
  • log-level:日志详细程度,取值 silent、error、warning、info、debug,排查连接失败时把它临时调到 debug 能看到更完整的握手过程。
  • external-controller:开放给外部管理面板(如内置 Dashboard)调用的 API 地址与端口,图形化客户端多数已内置管理界面,普通用户无需改动。
  • secret:访问上述 API 的鉴权密码,留空表示不设密码,仅限本机使用时可以不填,若开放给局域网访问建议设置。

此外,TUN 模式相关字段也放在这一段:

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

TUN 模式让 Clash 建立一张虚拟网卡,从系统网络层面接管全局流量,不再依赖应用逐一设置 HTTP/SOCKS 代理,常用于处理不支持代理设置的客户端软件或系统级流量。stack 决定虚拟网卡使用的协议栈实现,system 依赖系统自带能力,兼容性较好;gvisor 是用户态实现,某些平台下性能更稳定。开启 TUN 模式通常需要客户端以管理员或 root 权限运行,这是独立于代理端口设置之外的另一套流量接管机制。

DNS 段配置详解

DNS 段决定域名解析请求如何处理,直接影响分流准确性与解析速度,是最容易被忽视却又最容易出问题的部分:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://dns.google
  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、fallback 字段里那些 DoH/DoT 服务器域名本身,必须是纯 IP 地址,不能再套一层域名解析,否则会出现循环依赖。
  • nameserver:实际用于解析普通域名的服务器列表,支持传统 UDP、DoH(https://)、DoT(tls://)等多种协议前缀。
  • fallback:当按规则判断某个域名应该走代理时使用的备用解析服务器,通常填写境外或加密解析服务,避免污染。
  • fake-ip-range:开启 fake-ip 模式后,给域名临时分配的虚拟 IP 段,客户端拿到这个虚拟 IP 后再由内核在建立连接时还原成真实目标,这是规则按域名匹配却要在 IP 层转发之间的一层桥接机制。
  • fake-ip-filter:声明哪些域名不走 fake-ip、直接返回真实 IP,常见于局域网设备发现、直播弹幕等对真实 IP 有依赖的场景,漏配会导致这类功能异常。

DNS 配置错误的典型表现是:规则表看起来完全正确,但某些网站依然走错了出口,或者出现能连上却经常超时的情况。这类问题往往不是规则写错,而是域名解析阶段就已经拿到了不合预期的结果,建议排查顺序是先看 DNS 段再看 rules 段。

proxies 与 proxy-groups 段:节点与策略组的关系

proxies 是一个列表,每一项描述一个具体的代理节点,包含协议类型、服务器地址、端口、加密方式等连接参数,示例:

proxies:
  - name: "HK-01"
    type: ss
    server: example-hk.example.com
    port: 8443
    cipher: aes-256-gcm
    password: "your-password"
  - name: "SG-02"
    type: vmess
    server: example-sg.example.com
    port: 443
    uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    alterId: 0
    cipher: auto

常见的 type 取值包括 ss(Shadowsocks)、vmess、trojan、socks5、http 等,不同协议要求填写的字段不完全相同,缺少必填字段会导致该节点在客户端里显示为不可用或直接被跳过加载。这部分内容如果来自订阅链接,通常不需要手工编写,由订阅提供方生成;手工添加节点时才需要逐项核对字段名是否与协议匹配。

proxy-groups 段把上面列出的节点组织成可供规则调用的“策略组”,规则表引用的是策略组名称,而不是单个节点名称,这样切换出口时只需要在策略组内部调整,不需要改动规则表。常见策略组类型:

type 取值行为说明典型用途
select手动在多个节点/子策略组之间切换,不做自动判断日常手动选线
url-test定时向指定 URL 发起测速,自动选用延迟最低的节点自动择优
fallback按列表顺序探测可用性,首个可用节点失效才切下一个主备容错
load-balance按哈希或轮询算法在多个节点间分摊连接多节点分摊负载
 
proxy-groups:
  - name: "自动选择"
    type: url-test
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300
  - name: "手动选择"
    type: select
    proxies:
      - 自动选择
      - HK-01
      - SG-02
      - DIRECT

注意策略组也可以互相嵌套引用(如上面“手动选择”把“自动选择”当作一个选项列进去),但不能出现循环引用,否则内核加载配置时会直接报错拒绝启动。

rules 规则段:书写顺序与匹配逻辑

rules 段是一份从上到下顺序匹配的列表,内核对每一条网络请求按顺序逐条比对规则,命中第一条匹配的规则后立即执行对应策略,不再继续往下比对。这意味着规则的排列顺序本身就是逻辑的一部分,顺序写错会导致后面精确的规则永远轮不到。

rules:
  - DOMAIN-SUFFIX,google.com,自动选择
  - DOMAIN-KEYWORD,github,自动选择
  - DOMAIN,ad.example.com,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,手动选择

常见匹配类型包括 DOMAIN(精确域名)、DOMAIN-SUFFIX(域名后缀,能连带匹配子域名)、DOMAIN-KEYWORD(域名中包含关键词即匹配)、IP-CIDR(按 IP 段匹配)、GEOIP(按 IP 所属国家/地区库匹配)、MATCH(兜底规则,放在最后一行,匹配所有未命中前面规则的请求)。缺少 MATCH 兜底行是配置文件常见的疏漏,会导致部分请求找不到对应策略而走向不可预期的默认行为。

规则右侧填写的目标必须是已在 proxy-groups 里定义好的策略组名称,或是内置的 DIRECT(直连)、REJECT(拒绝连接,常用于屏蔽广告域名)。策略组名称大小写敏感,且不能包含规则表里未声明过的空策略组,否则同样会在加载阶段报错。

注意 NOTICE 规则集(rule-provider)引用的远程规则文件本质上也是按上述几种匹配类型逐行组成,只是被单独存放并可定期更新。使用 RULE-SET 类型规则前,需要先在 rule-providers 段声明对应规则集的来源地址与本地缓存路径,否则规则表加载时会因引用不存在的规则集而失败。

常见缩进错误与排查方法

YAML 对缩进的要求比多数配置格式更严格,以下几类问题在手工编辑配置文件时最常出现:

  1. 同级字段缩进空格数不一致

    同一个列表下的多个条目,前面的空格数量必须完全相同,哪怕只差一个空格,内核也会判定为层级错误而拒绝加载整份文件,而不是仅跳过出错的那一行。

  2. Tab 与空格混用

    多数文本编辑器默认按 Tab 缩进,但 YAML 标准不接受 Tab 字符,建议使用支持“将 Tab 转换为空格”功能的编辑器,并统一采用两个空格为一级缩进。

  3. 冒号后缺少空格

    YAML 的键值对要求冒号后跟一个空格再写值,例如 name:HK-01 缺少空格会被解析成一个不合法的键名,应写作 name: HK-01。

  4. 字符串未加引号导致误判类型

    密码、UUID 等字段如果以数字开头或包含特殊符号,建议显式加双引号,否则可能被解析成数字或布尔值而不是字符串,导致连接鉴权失败。

排查这类问题最直接的方法,是把修改后的配置文件放进任意在线 YAML 语法校验工具里先跑一遍缩进检查,确认语法层面无误后再交给客户端加载;客户端启动日志(或调整 log-level 为 debug 后的输出)通常也会明确指出加载失败的具体行号,按行号定位比逐段肉眼检查效率更高。修改配置文件建议先备份原文件,改动后如果客户端无法正常加载,可以直接回退到备份版本,避免因排查耗时导致长时间无法联网。

下载客户端