Clash 配置文件结构拆解:从 port 到 rules 逐段读懂一份 YAML

先看 YAML 的层级与解析规则

Clash 配置文件通常使用 YAML。它不是一串彼此独立的开关，而是一棵有层级的配置树：顶层字段控制内核行为，缩进后的字段属于上一级对象，以短横线开头的内容则是列表项。读配置时应先确认缩进，再判断字段含义。只看字段名、不看所在层级，很容易把有效参数放到错误位置。

缩进、冒号与列表

• 缩进统一使用空格，常见写法是每层 2 个空格，不要混入 Tab。
• 键名后的冒号需要跟一个空格，例如 mode: rule。
• dns:、profile: 这类字段下面还有子项，子项必须继续缩进。
• proxies:、proxy-groups: 与 rules: 通常包含列表，每项以 - 开头。
• 包含冒号、井号、花括号等特殊字符的名称，建议使用单引号或双引号包裹。

mode: rule
log-level: info

profile:
  store-selected: true
  store-fake-ip: true

proxy-groups:
  - name: '节点选择'
    type: select
    proxies:
      - '自动选择'
      - DIRECT

上例中，store-selected 属于 profile，而 name、type 和 proxies 共同构成一个策略组对象。若把 type 与 name 的缩进错开，YAML 即使能被解析，也可能形成完全不同的数据结构。

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

配置文件开头常放置监听端口、运行模式、日志级别和控制端口。这些字段决定应用如何接收系统流量，以及图形客户端如何与 Clash Meta（mihomo）内核通信。

port: 7890
socks-port: 7891
mixed-port: 7893
redir-port: 7892
tproxy-port: 7895

allow-lan: false
bind-address: '*'
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: 'change-this-controller-secret'

多个端口分别接收什么流量

port

HTTP 代理监听端口。示例中的地址通常写为 127.0.0.1:7890。

socks-port

SOCKS5 代理端口。支持 SOCKS5 的命令行工具或应用可以连接 127.0.0.1:7891。

mixed-port

在同一端口接收 HTTP 与 SOCKS5 请求。客户端只需要暴露一个本地代理入口时，通常保留此项即可。

redir-port

用于 Linux 重定向场景，通常与 iptables 或兼容的流量转发规则配合。

tproxy-port

用于 Linux TPROXY 透明代理，可处理需要保留目标地址的转发流量。

这些端口不要求全部启用。桌面客户端使用系统代理时，常见组合是只启用 mixed-port: 7890 或分别启用 HTTP 与 SOCKS 端口。若日志出现 address already in use，应检查其他代理程序、旧内核进程或开发服务是否已经占用相同端口，再修改配置或结束冲突进程。

mode、allow-lan 与控制接口

• mode: rule 按 rules 从上到下匹配，是日常分流配置最常见的模式。
• mode: global 将连接交给全局策略组，不再按普通规则逐条分流。
• mode: direct 让连接直接访问，适合临时判断问题是否来自代理链路。
• allow-lan: true 允许局域网设备连接监听端口。启用时还要检查系统防火墙、监听地址和网络可信范围。
• external-controller 是 REST API 控制接口。只供本机客户端使用时，应绑定到 127.0.0.1；需要远程面板时，应设置有效的 secret 并限制网络访问范围。

bind-address: '*' 表示监听可用地址，但它是否真正向局域网开放还受 allow-lan 与防火墙控制。不要把“监听地址”“允许局域网”和“控制接口”当作同一个设置，它们分别管理代理入口、局域网访问许可和内核管理接口。

DNS 块：解析链路与 Fake-IP

DNS 配置决定域名如何被解析，也影响域名规则能否在连接阶段继续匹配。Clash Meta（mihomo）常见的增强模式包括 fake-ip 与 redir-host。前者会从保留地址段返回一个映射地址，并在内核中保留域名与连接的对应关系；后者更接近返回真实解析结果的流程。

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'
    - '*.local'
    - 'time.*.com'
    - 'time.*.gov'
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - 'https://dns.alidns.com/dns-query'
    - 'https://doh.pub/dns-query'
  fallback:
    - 'https://1.1.1.1/dns-query'
    - 'https://dns.google/dns-query'
  fallback-filter:
    geoip: true
    geoip-code: CN

三类 nameserver 的分工

• default-nameserver 通常填写可直接访问的 IP 地址，用于解析 DoH 或 DoT 服务器自身的域名，避免启动阶段形成循环依赖。
• nameserver 是主要解析器，可以使用普通 UDP DNS，也可以填写 DoH、DoT 等加密解析地址。
• fallback 是备用解析器。是否采用其结果，会受到 fallback-filter 等条件影响。

listen: 127.0.0.1:1053 只让本机访问 DNS 监听端口。若客户端已自动接管系统 DNS，通常不必手工把操作系统 DNS 改到这个端口。TUN 模式下，内核还可能通过 DNS 劫持接收 53 端口请求，具体行为由客户端生成的 TUN 配置决定。

fake-ip-filter 应该放什么

局域网域名、设备发现域名、部分时间同步域名，以及依赖真实地址返回结果的应用域名，可以加入 fake-ip-filter。不要把大范围通配符随意加入过滤列表，否则大量域名会绕过 Fake-IP 映射，域名规则的命中方式和首次连接延迟都可能发生变化。

proxies：单个节点如何定义

proxies 是静态节点列表。每个节点至少需要名称、协议类型、服务器地址和端口，之后再按协议填写认证与传输参数。节点字段必须与服务端实际配置一致；协议名称相同，不代表端口、加密方式、TLS 主机名或 WebSocket 路径可以互换。

proxies:
  - name: '示例-Trojan'
    type: trojan
    server: edge.example.com
    port: 443
    password: 'example-password'
    udp: true
    sni: edge.example.com
    skip-cert-verify: false

  - name: '示例-VMess'
    type: vmess
    server: vm.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000001
    alterId: 0
    cipher: auto
    udp: true
    tls: true
    servername: vm.example.com
    network: ws
    ws-opts:
      path: /connect
      headers:
        Host: vm.example.com

节点名称是后续引用键

name 不只是界面显示文字，策略组还会通过完全相同的字符串引用节点。若节点名是 示例-Trojan，策略组中写成 示例 Trojan 就会变成不存在的引用。重命名节点时，要同步检查所有 proxy-groups、规则目标和链式代理配置。

TLS 与传输层字段要对应

• server 是建立连接时使用的服务器地址。
• sni 或 servername 用于 TLS 握手中的服务器名称，应按节点提供方给出的值填写。
• skip-cert-verify: false 表示正常验证服务端证书。
• network: ws 表示使用 WebSocket 传输，对应参数位于 ws-opts。
• udp: true 表示允许该节点处理 UDP，最终能否通信还取决于协议、服务端与网络环境。

从订阅导入时，节点经常不是直接写在 proxies 中，而是由客户端转换后生成，或者通过 proxy-providers 加载。两种方式可以同时存在，但同名节点会增加策略组引用与排错难度。

proxy-providers 与 proxy-groups：从节点到策略

proxy-providers 负责从本地文件或远程地址载入一批节点，proxy-groups 则把节点组织成可选择、可测速或可故障转移的策略。规则通常指向策略组，而不是直接指向某个具体节点。

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

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

常见策略组类型

• select：手工选择节点或另一个策略组。适合放在规则最终引用的位置。
• url-test：定期请求测试地址，并在候选节点中选择延迟较低者。示例每 300 秒检测一次，tolerance: 80 用于减少延迟接近时的频繁切换。
• fallback：按可用性选择候选项，当前连接路径失效时切换到后续可用节点。
• load-balance：按策略在多个节点间分配连接。它不等于把单个下载任务的带宽直接叠加。

proxies 用于显式列出节点或策略组名称，use 用于引用 provider。策略组之间可以继续嵌套，例如“节点选择”包含“自动选择”，而“自动选择”再从 provider 中取节点。检查配置时，应沿引用关系逐层确认名称存在，避免形成自己引用自己的循环。

rules：按顺序执行的分流表

rules 是配置末尾最关键的列表之一。Clash 按从上到下的顺序匹配，命中一条后通常不再继续向下检查。因此，更具体的域名、进程或网段规则应放在前面，范围较大的 GeoIP、GeoSite 与兜底规则放在后面。

rules:
  - DOMAIN-SUFFIX,example.org,节点选择
  - DOMAIN,api.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
  - GEOSITE,CN,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,节点选择

规则由匹配器、值与目标组成

以 DOMAIN-SUFFIX,example.org,节点选择 为例，第一段是规则类型，第二段是待匹配值，第三段是命中后使用的策略。策略名称必须与 proxy-groups 中的名称完全一致，也可以使用 DIRECT 或 REJECT 这类内置目标。

• DOMAIN 精确匹配一个完整域名。
• DOMAIN-SUFFIX 匹配指定域名及其子域名，适合按站点范围分流。
• DOMAIN-KEYWORD 按域名中的关键词匹配，范围较宽，应避免使用过短关键词。
• IP-CIDR 与 IP-CIDR6 分别匹配 IPv4 和 IPv6 地址段。
• GEOIP 依赖地理 IP 数据库判断目标地址所属区域。
• GEOSITE 依赖域名分类数据库；可用类别取决于当前 mihomo 版本与数据文件。
• MATCH 匹配此前未命中的流量，应放在规则列表末尾。

no-resolve 表示这条 IP 类规则不为匹配目的额外触发域名解析。它常用于局域网网段或 GEOIP 规则，但是否添加要结合前面的 DNS 模式与规则需求判断。把它加到域名规则没有意义。

规则顺序错误的典型表现

1. 把 MATCH 放在中间，后续规则永远没有机会执行。
2. 先写宽泛的 DOMAIN-KEYWORD，导致后面的精确域名规则无法命中。
3. 局域网网段没有提前直连，访问路由器、NAS 或开发服务器时被送入代理。
4. 规则目标名称已修改，但规则表仍引用旧策略组，载入时提示找不到代理或策略。
5. 使用 GEOSITE、GEOIP，却没有准备对应数据库，导致规则载入或匹配异常。

TUN 与 profile：常见的尾部配置

TUN 模式通过虚拟网络接口接管更多系统流量，适合不能主动读取系统代理设置的程序。它和 mixed-port 并不冲突：前者从网络层接管，后者仍可供明确支持 HTTP 或 SOCKS5 的应用使用。

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

profile:
  store-selected: true
  store-fake-ip: true

auto-route 让内核自动配置路由，auto-detect-interface 用于识别当前出口网卡。不同操作系统对 TUN 驱动、管理员权限和路由设置的要求不同，图形客户端通常会在「设置」→「网络」或「设置」→「TUN 模式」中生成并管理这些参数。若客户端已经托管 TUN 配置，不应同时在多个覆写层重复声明同名字段。

store-selected: true 用于保存策略组选择，重启后继续使用上次选中的项目。store-fake-ip: true 保存 Fake-IP 映射，有助于减少重启后映射变化带来的连接中断。这两个字段属于 profile，不是 dns 的子项。

从载入到命中的完整检查顺序

一份配置能通过 YAML 语法检查，不代表节点一定可连接；节点可连接，也不代表规则与 DNS 已按预期工作。排查时按照固定顺序前进，比同时修改多个段落更容易定位问题。

1. 检查 YAML 解析。先看客户端配置页或内核日志，确认没有缩进、重复键、未知字段和类型错误。
2. 检查本地监听。确认 7890、7891、7893、9090、1053 等实际启用端口未被其他进程占用。
3. 检查节点握手。在代理页选择单个节点进行延迟测试，再查看 TLS、认证、超时或网络不可达日志。
4. 检查策略组引用。确认规则目标、策略组成员和 provider 名称完全一致。
5. 检查 DNS。观察域名查询是否超时，DoH 服务器域名能否通过 default-nameserver 完成初始解析。
6. 检查规则命中。打开连接或日志页面，查看目标域名命中了哪条规则、最终选择了哪个策略组和节点。
7. 最后启用 TUN。先确认普通系统代理工作正常，再开启 TUN，便于区分节点问题与路由接管问题。

一份配置的阅读路线

阅读陌生配置时，可以从顶层端口开始，依次看 dns、proxies 或 proxy-providers、proxy-groups、rules，最后检查 tun 与 profile。这条路线正好对应流量处理过程：应用先进入本地端口或 TUN，域名经过 DNS 解析，规则选择策略组，策略组再选中具体节点。

真正决定配置是否可维护的，不是字段数量，而是引用关系是否清楚。节点名、provider 名、策略组名和规则目标构成一条连续链路。修改其中任意名称，都要沿链路检查后续引用。完成修改后，使用客户端的配置校验功能重新载入，再通过连接日志确认实际命中结果。