进阶配置 预计阅读 13 分钟

Clash 配置文件 YAML 各段字段逐段解析

从 port、mode、dns 到 proxies、proxy-groups、rules,按配置文件的书写顺序逐段说明每个字段的含义、取值范围与改错后的典型报错。

Clash 配置文件通常使用 YAML 编写。它把监听端口、运行模式、DNS、代理节点、策略组和分流规则放在同一个文档中。字段的排列顺序一般不影响内核读取，但按“基础参数 → DNS → 节点 → 策略组 → 规则”的顺序书写，更容易定位引用关系和缩进错误。

本文以 Clash for Windows 0.20.39 常见配置结构和 mihomo v1.19 系列配置语义为参照。不同内核支持的协议、TUN 参数和 DNS 扩展字段并不完全相同。修改订阅生成的配置前，建议另存一份本地副本，避免下一次订阅更新覆盖手工内容。

YAML 语法与顶层结构

缩进、列表与键值

YAML 使用空格表达层级，不能用 Tab 代替缩进。常见习惯是每层缩进 2 个空格。冒号后要留一个空格，列表项以短横线开头。节点、策略组和规则位于不同的顶层键下，层级错一格就可能让整个文件无法载入。

port: 7890
mode: rule

proxies:
  - name: "示例节点"
    type: ss
    server: 203.0.113.10
    port: 443

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

rules:
  - MATCH,节点选择

port: 7890 是一个键值；proxies: 后面是列表；每个以 - name: 开始的项目都是一个节点对象。包含冒号、井号、星号或容易被识别为布尔值的名称，最好用引号包住。例如节点名写成 "HK: 01"，可避免冒号被当作映射分隔符。

常见解析错误

端口、局域网与运行模式字段

文件开头通常是入站监听和基础运行参数。以下示例给 HTTP、SOCKS5 和混合代理分别设置了端口。实际使用时不必同时开启三种端口，桌面客户端最常用的是 mixed-port。

port: 7890
socks-port: 7891
mixed-port: 7892
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "change-this-controller-secret"

三个代理端口有什么区别

同一个 IP 和端口不能被两个程序同时监听。如果日志出现 address already in use 或 bind: Only one usage of each socket address，应先检查端口是否被旧的 Clash 进程、其他代理工具或本地开发服务占用。Windows 可在终端执行 netstat -ano | findstr :7890 查找对应 PID。

allow-lan 与 bind-address

allow-lan: false 表示不向局域网设备提供代理入口。改为 true 后，手机或其他电脑可以把代理服务器填写为当前电脑的局域网地址，例如 192.168.1.20:7890。此时还要允许对应端口通过 Windows 防火墙。

bind-address 决定监听地址。只供本机使用时，绑定 127.0.0.1 更明确；需要局域网访问时可按内核支持情况使用 * 或指定网卡地址。仅修改 allow-lan 不代表其他设备一定能连接，防火墙、访客网络隔离和路由器 AP 隔离也会阻断访问。

mode、log-level 与控制端口

DNS 段：监听、解析器与增强模式

DNS 段决定域名如何解析。它既会影响规则匹配，也会影响 TUN 模式下的域名接管。一个常见的基础结构如下：

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.msftconnecttest.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://1.1.1.1:853
  fallback:
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enable、listen 与 default-nameserver

enable 控制内置 DNS 模块。listen 是 DNS 服务监听地址，示例使用本机 UDP/TCP 端口 1053。如果另一个本地 DNS 程序已占用该端口，日志会显示监听失败。

default-nameserver 主要用于解析 DoH、DoT 等上游服务器自身的域名，也常被称为引导 DNS。为避免循环依赖，这里通常填写可直接访问的 IP 地址，而不是另一个需要先解析的域名。

nameserver、fallback 与策略解析

nameserver 是主要解析器，既可以是普通 DNS 地址，也可以是 DoH 或 DoT 地址。fallback 和 fallback-filter 是经典 Clash 配置中常见的备用解析结构。mihomo 还支持 nameserver-policy、proxy-server-nameserver、direct-nameserver 等细分字段，可按域名规则或代理节点解析用途选择不同上游。

不要把“写了多个 DNS”理解成所有请求都会同时采用全部答案。内核会依据字段语义、过滤条件和响应结果选择解析路径。遇到域名可以解析但网站打不开时，应同时查看 DNS 日志、规则命中和节点连接，不能只根据浏览器报错判断。

fake-ip 与 redir-host

proxies：单个代理节点字段

proxies 保存手工定义的节点。订阅通常会自动生成这一段。不同协议字段不同，但每个节点至少要有唯一名称、协议类型、服务器地址和端口。

proxies:
  - name: "SS-HK-01"
    type: ss
    server: hk.example.net
    port: 443
    cipher: aes-128-gcm
    password: "example-password"
    udp: true

  - name: "VMess-JP-01"
    type: vmess
    server: jp.example.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    servername: jp.example.net
    network: ws
    ws-opts:
      path: /gateway
      headers:
        Host: jp.example.net

通用字段与协议字段

节点能出现在列表中，只说明 YAML 已被解析，不代表连接参数正确。认证信息错误常表现为握手失败；服务器地址无法解析会显示 DNS 错误；WebSocket 路径或 Host 不一致通常表现为连接建立后立即断开。排查时应在客户端进入「日志」并把级别临时切到 debug，再针对一个节点发起延迟测试。

proxy-providers 与 proxy-groups

节点提供器 proxy-providers

proxy-providers 可以从本地文件或远程地址载入一组节点。与直接把全部节点写入 proxies 相比，提供器更适合把节点来源和策略组结构分开管理。

proxy-providers:
  provider-main:
    type: http
    url: "https://example.com/subscription"
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

interval: 3600 表示每 3600 秒检查一次更新；健康检查的 interval: 600 表示每 10 分钟执行一次测试。提供器下载失败时，应检查订阅地址可访问性、系统时间、代理启动阶段是否存在循环依赖，以及保存路径是否可写。

策略组的类型与引用

proxy-groups:
  - name: "节点选择"
    type: select
    proxies:
      - "自动选择"
      - "故障转移"
      - DIRECT
    use:
      - provider-main

  - name: "自动选择"
    type: url-test
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "故障转移"
    type: fallback
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300

tolerance: 80 表示延迟差距在 80 毫秒以内时，自动选择组不必频繁切换。数值过小可能导致节点在轻微网络波动中反复变化；数值过大则可能继续保留明显变慢的节点。家庭宽带可从 50 至 100 毫秒开始调整。

rules 与 rule-providers：分流的匹配顺序

rules 决定连接交给哪个策略组。规则从上到下匹配，命中第一条后停止继续检查，因此越具体的规则通常越靠前，兜底规则放在最后。

rules:
  - DOMAIN,api.example.com,节点选择
  - DOMAIN-SUFFIX,example.net,节点选择
  - DOMAIN-KEYWORD,stream,自动选择
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

常见规则类型

no-resolve 用于避免某些 IP 规则为了匹配而额外触发域名解析。它不是所有规则都需要的通用后缀。若把 MATCH 放在第一行，后面的规则永远没有机会命中；若规则引用了不存在的策略组，载入时可能直接报错，也可能在连接处理时显示找不到策略。

规则提供器 rule-providers

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    url: "https://example.com/rules/private-network.yaml"
    path: ./ruleset/private-network.yaml
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,节点选择

behavior 要与规则集内容匹配，常见值包括 domain、ipcidr 和 classical。把域名规则集声明成 ipcidr 会导致内容无法正确解析。mihomo 的规则集还涉及 format，远端文件采用 YAML、文本或二进制格式时必须填写对应值。

TUN 段与透明代理参数

TUN 模式建立虚拟网络接口，用于接管没有单独代理设置的应用流量。它与系统代理不是同一个入口。常见的 mihomo 配置如下：

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-detect-interface: true
  strict-route: false

启用 TUN 后出现“浏览器能开、游戏断网”或“局域网设备不可访问”，应依次检查运行权限、路由表、DNS 接管、局域网网段直连规则和其他 VPN。不要同时开启多个会创建默认路由的网络工具。Windows 上还可执行 route print 查看默认路由与接口优先级。

一份可读的最小配置与排错流程

下面的结构省略了真实认证信息，但保留了从入口到规则的完整引用链。检查配置时，可以从最后一行的策略组反向追踪：规则引用“节点选择”，“节点选择”引用“示例节点”，“示例节点”包含服务器参数。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

proxies:
  - name: "示例节点"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-128-gcm
    password: "replace-with-valid-password"
    udp: true

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

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

按错误类型逐层检查

  1. 文件无法载入：先查 Tab、缩进、冒号、引号和重复键。此时不要先测试节点，因为内核还没有成功读取配置。
  2. 配置载入但策略组为空：检查 proxies 是否有节点、use 的提供器名称是否正确，以及 provider 文件是否下载成功。
  3. 节点测试失败：核对 server、port、认证字段、TLS 名称和传输参数，再检查服务器域名能否解析。
  4. 只有部分网站打不开：查看连接日志中的规则命中、目标域名、策略组和实际节点，确认规则顺序是否把流量提前送到 DIRECT 或 REJECT。
  5. 系统代理有效但其他程序不走代理：确认程序是否遵循系统代理；不遵循时再评估 TUN，不要通过重复添加宽泛规则掩盖入口问题。
  6. 更新订阅后改动消失：把本地 DNS、TUN 或规则调整迁移到客户端支持的覆写或合并配置中。

字段兼容性与维护建议

Clash for Windows 0.20.39 使用的 Clash 内核配置，与持续更新的 mihomo 配置并非完全等价。较新的订阅可能包含旧内核不认识的协议、规则集格式或 DNS 字段。遇到 field not found、unsupported proxy type 一类错误时，应先确认客户端实际调用的内核及版本，而不是只看界面名称。

日常维护可以把配置分成三类：订阅负责节点，规则提供器负责可更新的规则集，本地覆写负责端口、DNS 和 TUN。这样既能减少手工合并，也能让问题落在明确区域。每次修改只调整一个主题，例如先改 DNS 并重载，确认解析正常后再启用 TUN。

配置文件的核心关系并不复杂：入站端口接收流量，DNS 提供域名信息，规则决定策略组，策略组选择节点，节点建立远端连接。沿着这条链检查，比反复切换节点或一次替换整份 YAML 更容易找到具体字段。

查看客户端下载