配置进阶 预计阅读 14 分钟

Clash 配置文件结构解析：从端口设置到策略组逐段读懂 YAML

按配置顺序拆解基础设置、代理节点、策略组、规则集与 DNS 段落，说明字段之间的引用关系。

YAML Structure

先理解 YAML 的层级与数据类型

Clash 配置文件通常使用 YAML。阅读时不应只搜索某个节点名称，而要先看缩进所表达的父子关系。顶格字段一般是主要配置段，例如 proxies、proxy-groups、rules 与 dns；向内缩进的字段属于上一级对象。列表项以连字符开头，同一缩进深度的列表项彼此并列。

mode: rule
log-level: info

proxies:
  - name: "示例节点"
    type: ss
    server: example.com
    port: 443

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

这段配置包含两个标量字段、一个节点列表和一个策略组列表。name、type、server 都属于列表中的同一个节点对象；策略组里的 proxies 则是名称列表，其中的“示例节点”必须能在其他位置找到同名定义。

YAML 对缩进敏感，建议统一使用空格，不使用制表符。包含冒号、井号、特殊符号或容易被解释为布尔值的名称可以放在引号中。注释由 # 开始，只用于说明，不参与内核运行。配置中的字段名必须使用内核支持的写法，调整中文显示名称不会改变字段含义，但会影响名称引用。

General Settings

基础设置、工作模式与监听端口

文件开头常见的是端口、局域网访问、工作模式、日志级别和控制接口。这些字段决定程序如何接收流量以及客户端界面如何连接内核，但它们不负责决定某个域名最终走哪个节点。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "请设置独立控制密钥"

端口字段如何区分

  • port 通常表示 HTTP 代理监听端口。
  • socks-port 表示 SOCKS5 代理监听端口。
  • mixed-port 在同一端口接收 HTTP 与 SOCKS 流量，桌面客户端常采用这种形式。
  • redir-port、tproxy-port 面向特定透明代理方案，能否使用还取决于操作系统与网络规则。

多个监听端口不能与本机其他程序占用的端口冲突。桌面客户端往往会在界面设置中管理端口，因此直接修改订阅生成的 YAML 后，还要确认客户端是否存在覆盖设置。

mode: rule 表示按 rules 从上到下匹配；global 通常将流量统一交给全局策略；direct 则直接连接。界面中的“规则、全局、直连”切换可能在运行时修改模式，不一定会回写原始订阅文件。

allow-lan 控制局域网设备是否可以访问监听端口。开启后还应结合 bind-address、系统防火墙和实际网络边界进行限制。external-controller 是控制接口地址，图形客户端依靠它读取连接、策略与日志状态；如果接口需要被非本机地址访问，应设置 secret 并限制可达范围。

Proxy Sources

代理节点与代理提供器

proxies 保存静态节点定义。每个节点至少包含唯一名称、协议类型、服务器地址、端口以及该协议要求的认证字段。不同协议的参数不能混用：Shadowsocks 常见 cipher 与 password，Trojan 常见密码和 TLS 相关设置，VMess 与 VLESS 则有各自的身份、传输与加密字段。

proxies:
  - name: "Tokyo-A"
    type: trojan
    server: edge.example.com
    port: 443
    password: "example-password"
    sni: edge.example.com
    udp: true

server 是连接目标，sni 是 TLS 握手使用的服务器名称，两者可能相同，也可能由服务配置明确指定。不能因为连接失败就随意互换或删除 TLS 字段。协议参数应以订阅提供方给出的有效配置和当前 mihomo 文档为准。

节点数量较多时，配置常通过 proxy-providers 引入外部节点集合。提供器负责从指定来源读取节点并按计划更新，策略组再通过 use 引用它。这样可以将“节点从哪里来”和“节点如何参与选择”分开。

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

primary 是提供器键名，后面会被策略组引用。path 指定本地缓存位置，interval 是更新间隔。健康检查只是在指定条件下测试节点连通性或延迟，不等于实际业务网站必然可用，也不会自动修正认证参数。

Policy Groups

策略组如何连接节点与规则

proxy-groups 是整个配置的调度层。规则通常不会直接写某个服务器地址，而是把流量交给一个策略组；策略组再选择节点、内置策略或另一个策略组。理解这一层，才能解释界面中为什么会出现多级选择。

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

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

  - name: "媒体服务"
    type: select
    proxies:
      - "节点选择"
      - DIRECT

第一组使用 select，由使用者在界面中选择成员。第二组使用 url-test，从提供器 primary 的节点中按测试结果选择。第三组并不直接列出服务器，而是引用“节点选择”，因此它会继续沿引用关系得到最终出口。

proxies 用于列出静态节点、内置策略或其他策略组；use 用于引用 proxy-providers。两者都能构成成员来源，但对象类型不同。常见错误是把提供器名称放进 proxies，或把节点名称写进 use。

常见策略组类型

select
提供手动选择入口，适合总出口、应用分类和需要固定策略的场景。
url-test
按指定测试地址与周期检测成员，通常选择测试结果较优的节点。
fallback
按成员顺序检查可用性，前一成员不可用时切换到后续成员。
load-balance
按设定策略在多个成员间分配连接，适用性取决于业务会话特征。

DIRECT、REJECT 等是内置策略，不需要在 proxies 中定义。自定义名称则必须完全一致，包括大小写、空格和符号。策略组之间可以嵌套，但不能形成循环引用，否则内核无法得到明确出口。

Routing Rules

规则匹配顺序与规则集引用

rules 决定流量交给哪个策略。规则模式下，内核通常自上而下检查，命中一条后停止继续匹配。因此，具体域名与明确网段一般放在更宽泛的规则之前，兜底规则放在末尾。

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.net,节点选择
  - DOMAIN-KEYWORD,media,媒体服务
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

DOMAIN 匹配完整域名，DOMAIN-SUFFIX 匹配指定域名及其子域，DOMAIN-KEYWORD 按域名中的关键词匹配。IP-CIDR 根据目标 IPv4 网段判断，IPv6 可使用对应的 IPv6 规则类型。GEOIP 依赖地理数据库判断 IP 所属区域。MATCH 是最终兜底，应放在规则末尾。

规则最后一段通常是目标策略名称，例如“节点选择”“媒体服务”、DIRECT 或 REJECT。如果目标名称在 proxy-groups 中不存在，即使规则语法看似完整，也会在载入阶段报错或无法按预期工作。

大量规则可以放入 rule-providers。规则提供器定义来源、缓存路径、行为类型和更新周期，主规则区使用 RULE-SET 调用。

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

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

behavior 描述规则集内容的匹配形态，常见值包括 domain、ipcidr 与 classical。规则文件实际内容必须与该行为相符。classical 可以承载较完整的经典规则表达式；domain 与 ipcidr 更侧重对应类型的数据集合。

DNS Pipeline

DNS 段落如何参与域名解析

DNS 配置并不是简单填写两个服务器地址。它会影响域名如何解析、规则在域名与 IP 之间如何关联，以及 TUN 场景下流量能否稳定进入内核。mihomo 常见字段包括启用状态、监听地址、解析模式、默认解析器、主要解析器、备用解析器与按域名分流的名称服务器策略。

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

default-nameserver 常用于解析 DoH 或 DoT 服务器自身的域名，因此通常填写可以直接访问的 IP 地址解析器。nameserver 是主要查询来源；fallback 是否参与以及如何筛选结果，还取决于当前内核版本和相关过滤配置。

enhanced-mode: fake-ip 会向应用返回保留地址范围中的映射地址，内核据此保持域名信息并完成后续转发。这有利于域名规则判断，但部分局域网服务、设备发现、游戏平台或依赖真实地址的程序可能需要加入 fake-ip-filter。另一种常见模式是 redir-host，其处理路径不同，具体选择应结合操作系统、客户端实现和应用兼容性。

DNS 失败不一定表现为“无法解析”。有时浏览器已经得到结果，但连接被错误规则送到不可用策略；也可能系统 DNS、浏览器安全 DNS和内核 DNS 同时存在，导致实际查询没有经过预期链路。排查时应分别确认应用请求入口、DNS 监听状态、解析日志与最终规则命中。

Traffic Capture

TUN 模式与系统代理的配置边界

系统代理只影响遵循操作系统代理设置的应用。部分命令行工具、游戏、独立网络栈程序或 UDP 流量可能绕过系统代理。TUN 模式通过虚拟网络接口接收更多系统流量，再交给 DNS、规则和策略组处理。

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

stack 决定 TUN 网络栈实现，可用值和推荐选择会随平台与 mihomo 版本变化。auto-route 尝试自动配置路由，auto-detect-interface 用于识别默认网络接口。启用 TUN 通常需要相应系统权限，客户端可能通过服务模式或辅助组件完成权限操作。

TUN 只是流量入口，不会替代规则与策略组。流量进入内核后，仍要经过域名解析、嗅探设置、规则匹配和策略选择。若开启 TUN 后局域网设备无法访问，应检查私有网段直连规则、路由排除设置以及 DNS 劫持范围，而不是直接删除全部分流规则。

系统代理和 TUN 可以由客户端统一管理。实际使用中应避免同时运行多个接管网络的工具，也要留意休眠唤醒、网络切换和 VPN 接口变化后默认路由是否更新。关闭 TUN 后如果网络仍异常，可以检查客户端是否已恢复系统代理和路由状态。

Validation

修改配置后的验证与排错流程

配置文件能够被文本编辑器打开，不代表内核能够载入。可靠的调整方式是一次只改一个逻辑单元，并保留可恢复版本。若客户端提供配置检查、内核日志或覆写预览，应先确认合并后的最终 YAML，而不是只检查某个片段。

  1. 检查 YAML 结构：确认缩进、列表连字符、引号和冒号位置，没有重复覆盖关键顶层字段。
  2. 检查名称引用：逐一核对规则目标、策略组成员、use 提供器名称与 RULE-SET 名称。
  3. 检查外部资源：确认代理提供器和规则提供器可更新，本地缓存路径可写，下载内容格式符合声明。
  4. 检查运行日志：载入错误通常会指出字段或对象名称；连接错误则需要结合 DNS、规则命中和节点握手信息判断。
  5. 进行最小测试：先测试 DIRECT，再测试单个静态节点，然后测试策略组与规则集，逐层缩小问题范围。

几类高频错误

  • 策略组引用了已经改名或被订阅更新删除的节点。
  • 规则指向不存在的策略组，或名称中多出空格。
  • proxy-providers 已定义，但策略组没有通过 use 引入。
  • RULE-SET 名称与 rule-providers 的键名不一致。
  • 宽泛规则排在具体规则之前，导致后面的规则永远没有机会命中。
  • DNS 监听端口冲突，或应用请求没有进入内核管理的解析链路。
  • 直接编辑订阅缓存，更新后自定义内容被新的订阅结果替换。

完整配置可以理解为一条引用链：应用流量先由系统代理、透明代理或 TUN 进入内核；DNS 段落处理域名解析；rules 与规则提供器确定目标策略；proxy-groups 从静态节点或代理提供器中选出出口；最终由具体协议节点建立连接。按照这条链路阅读，比逐个背字段更容易发现配置中的断点。

下载Clash