YAML 参考 预计阅读 14 分钟

Clash 配置文件 YAML 结构解析：从基础字段到规则段的完整顺序

按实际加载顺序拆解端口、DNS、代理节点、策略组与规则字段，并说明缩进、引用和字段覆盖关系。

先读结构：YAML 顺序与配置依赖不是同一件事

Clash、Clash Meta 及其后续 mihomo 内核通常使用 YAML 文件描述运行参数。一个完整配置可能同时包含监听端口、运行模式、DNS、代理节点、策略组、规则集和流量嗅探等内容。YAML 映射本身不依靠书写先后表达业务优先级，因此把 rules 写在文件前部，不会让规则比端口字段更早生效。

实际排查时仍然建议按依赖关系阅读：先确认基础监听与运行模式，再确认 DNS，随后检查节点来源、策略组引用，最后检查规则如何把请求送入策略组。这个顺序不是 YAML 解析器的强制加载顺序，而是一条更容易定位错误的检查链路。

  1. 基础字段决定客户端如何监听本机流量，以及采用规则、全局还是直连模式。
  2. DNS 字段决定域名查询入口、上游服务器和 Fake-IP 映射方式。
  3. proxies 与 proxy-providers 提供可用代理节点。
  4. proxy-groups 把节点或其他策略组组织成可选择的出口。
  5. rule-providers 提供远程规则集合，rules 决定最终匹配顺序。

基础字段：端口、局域网访问与运行模式

基础段通常放在文件顶部，便于快速确认客户端正在开放哪些入口。不同客户端会通过图形界面覆写其中一部分内容，所以文件中的值不一定等于运行时最终值。检查问题时，应同时查看配置文件与客户端当前状态页。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090

mixed-port 同时接收 HTTP 与 SOCKS 代理连接，适合只配置一个本地代理端口的场景。部分配置也会分别使用 port 和 socks-port。同一种入口无需重复开放多个冲突端口；如果端口已被其他程序占用，内核可能无法启动监听。

allow-lan 控制局域网设备能否连接本机代理端口。设置为 true 时，还要检查系统防火墙和监听地址。bind-address 决定监听网卡范围，但具体可用行为要以内核版本为准。仅供本机使用时，保持局域网访问关闭更容易控制入口。

mode 常见值为 rule、global 和 direct。规则模式逐条匹配 rules；全局模式把流量交给全局策略选择；直连模式绕过代理。图形客户端中的模式切换经常直接改变运行时设置，未必回写订阅文件。

字段 主要作用 检查重点
mixed-port 接收 HTTP 与 SOCKS 代理连接 端口是否占用，应用是否指向同一端口
allow-lan 允许或阻止局域网设备接入 监听地址、防火墙与设备所在网段
mode 选择规则、全局或直连模式 客户端运行状态是否覆写文件值
log-level 设置日志详细程度 排错时是否能看到 DNS、规则和连接信息

DNS 段：查询入口、上游与 Fake-IP 映射

DNS 配置不是简单的服务器地址列表。启用内置 DNS 后，内核需要确定监听入口、解析模式、默认解析服务器和实际上游。使用 TUN 接管时，DNS 劫持与路由设置还会影响请求是否进入内核。

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query

default-nameserver 主要用于解析加密 DNS 上游自身的域名，通常填写可直接访问的 IP 地址。nameserver 则承担常规域名查询。部分 mihomo 配置还会使用 proxy-server-nameserver 专门解析代理服务器域名，或通过 nameserver-policy 为指定域名选择不同上游。

enhanced-mode: fake-ip 会先为域名分配虚拟地址，再在连接发生时恢复域名信息并执行规则匹配。这样可减少应用自行解析导致的匹配偏差。局域网主机名、某些设备发现协议、特定游戏或依赖真实地址返回结果的域名，可能需要加入 fake-ip-filter。过滤规则应针对实际异常添加，不宜把大范围域名全部排除。

代理节点与策略组：先定义成员，再建立出口

proxies 保存直接写入文件的节点。每个节点至少包含名称、协议类型、服务器地址、端口以及协议要求的认证参数。不同协议字段差异较大，不能把一种协议的参数直接复制到另一种协议。订阅转换工具生成的节点也应以内核实际支持字段为准。

proxies:
  - name: "节点 A"
    type: socks5
    server: proxy.example.com
    port: 1080
    username: account
    password: passphrase
    udp: true

proxy-groups:
  - name: "节点选择"
    type: select
    proxies:
      - "自动测速"
      - "节点 A"
      - DIRECT

  - name: "自动测速"
    type: url-test
    proxies:
      - "节点 A"
    url: https://www.gstatic.com/generate_204
    interval: 300

名称是引用键。策略组中的 节点 A 必须与节点名称逐字一致，包括空格、大小写和全角符号。策略组也可以引用另一个策略组，因此可以先建立“自动测速”，再把它作为“节点选择”的成员。引用形成循环时，内核无法得到有效出口，应调整层级。

select 由用户手动选择成员；url-test 按测试结果自动选择延迟较低的可用节点；fallback 更关注按顺序选择可用成员；load-balance 按策略在多个成员间分配连接。延迟测试地址只用于可用性和响应时间测试，不代表所有目标站点的实际速度。

DIRECT、REJECT 等是内置动作，不需要在 proxies 中重复声明。DIRECT 表示直连，REJECT 表示拒绝连接。规则目标也可以直接指向这些动作，但把常用出口统一指向策略组，通常更方便在客户端中切换。

规则段：从上到下命中，首条结果生效

与 YAML 顶层映射不同，rules 是有顺序的列表。内核通常从第一条开始检查，命中后停止继续匹配。因此具体规则应放在宽泛规则之前，兜底规则放在末尾。把 MATCH 提到前面，会让后续域名与 IP 规则失去作用。

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

DOMAIN 匹配完整域名；DOMAIN-SUFFIX 匹配指定域名及其子域；DOMAIN-KEYWORD 按关键词匹配，范围通常更宽。IP-CIDR 对目标 IP 网段生效，附加 no-resolve 可避免为了匹配该规则额外触发域名解析，但只有在连接上下文已有目标 IP 时才能直接判断。

GEOIP 依赖地理数据库把 IP 归类。mihomo 还支持 GeoSite、规则集合和更多规则类型，但是否可用取决于内核版本、数据库文件与配置方式。规则目标必须是已存在的策略组、节点名称或内置动作。若日志提示找不到策略，优先检查规则末列与 proxy-groups 名称。

规则模式只负责选择出口，不会自动把所有设备流量送入 Clash。浏览器或系统需要先使用系统代理，或者由 TUN 虚拟网卡接管流量。遇到“规则没有生效”时，应先确认连接是否出现在客户端日志中；日志中完全没有该连接，通常应检查流量入口，而不是继续修改规则顺序。

远程集合：proxy-providers 与 rule-providers

节点数量较多时，可以使用 proxy-providers 从远程地址或本地文件加载节点集合，再由策略组通过 use 引用。规则集合则由 rule-providers 定义，并在 rules 中通过 RULE-SET 调用。两者名称相近，但提供的数据类型不同，不能互换。

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

proxy-groups:
  - name: "订阅节点"
    type: select
    use:
      - provider-main

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

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,订阅节点

path 是远程内容下载后的本地存放位置。运行环境需要允许内核写入对应目录。interval 通常以秒为单位，表示更新间隔；健康检查间隔与订阅更新间隔是两个独立设置。健康检查只测试已有节点，不会代替订阅更新。

规则提供器的 behavior 必须与内容结构对应，例如域名集合、IP 网段集合或经典规则格式。不同 mihomo 版本对 format、二进制规则集和行为类型的支持可能不同。加载远程规则失败时，应查看日志中的下载状态、文件格式和解析错误，不要只检查 URL 能否在浏览器中打开。

缩进、引号与 YAML 类型：最常见的解析边界

YAML 使用缩进表达层级，推荐统一使用空格，不要混入制表符。同一级字段保持相同缩进，列表项使用连字符。下面两段看似接近，但第二段把 enable 放到了 dns 外部，含义已经改变。

dns:
  enable: true
  enhanced-mode: fake-ip

dns:
enable: true
enhanced-mode: fake-ip

包含冒号、井号、前后空格或容易被识别为布尔值的文本，适合使用引号。节点名称与策略组名称只要保持一致，可以使用中文。端口应写成数字，开关应写成 true 或 false，不要把所有值都包成字符串。某些字段允许字符串形式，但类型是否兼容应以内核文档和错误日志为准。

YAML 锚点与引用可以减少重复配置，但复杂订阅经过客户端覆写、格式转换或重新导出后，锚点结构可能被展开。手动维护文件时可以谨慎使用；需要频繁经过订阅转换链路时，明确写出关键字段更容易排查。

字段覆盖关系与完整检查流程

运行时配置可能来自多个层级：远程订阅原文、客户端本地覆写、用户在界面中的临时选择，以及内核启动参数。最终生效值取决于客户端如何合并这些来源。相同字段被重复定义时，不应仅凭文件位置猜测结果，应查看客户端生成的最终配置或运行状态。

策略组的当前选择通常保存在客户端或内核缓存中。订阅更新后，只要组名和成员关系仍可用，原选择可能继续保留；如果节点改名或被删除，客户端可能回退到组内其他成员。规则更新不会自动证明节点可用，节点健康检查通过也不代表规则目标正确。

  1. 验证 YAML 语法：确认缩进、冒号、列表符号和引号完整，先排除无法解析的问题。
  2. 检查本地入口：确认 mixed-port、系统代理或 TUN 状态，观察目标连接是否进入日志。
  3. 检查 DNS 链路：确认查询被内核接收，上游可达，Fake-IP 排除范围合理。
  4. 检查节点来源：确认静态节点或代理提供器加载成功，服务器域名可以解析。
  5. 检查名称引用：从规则目标追到策略组，再从策略组追到节点或提供器。
  6. 检查规则顺序：具体规则放前，宽泛规则放后，末尾保留明确兜底。
  7. 检查运行时覆盖：确认客户端界面中的模式、端口和策略选择没有覆盖预期配置。

一个可加载、可接管、可解析、可选路的配置才算形成完整链路。遇到故障时，按“入口 → DNS → 节点 → 策略组 → 规则 → 出口”逐段确认，比一次修改多个字段更容易定位原因。每次只调整一个环节，并结合日志验证结果，可以避免语法问题、网络问题和规则问题互相干扰。

下载Clash