Clash YAML 配置文件详解与标准配置模板

发布于 2026-03-01 · 最后更新 2026-11-12

什么是 Clash YAML 配置文件

在 ClashFX 以及基于 Mihomo（Clash Meta）核心的客户端中，所有的代理节点、分流策略、DNS 解析规则与运行参数都通过一个遵循 YAML 语法 的文本文件进行定义（通常为 config.yaml 或服务商提供的订阅文件）。

理解 Clash YAML 配置文件的层级结构，不仅可以帮助你排查「配置文件导入失败」或「分流不生效」等常见故障，还能让你根据日常工作流，定制低延迟策略组与去广告规则。

核心字段详细解析

一个标准的 Clash / Mihomo 配置文件通常由以下六大顶层板块构成：

├── 基础通用设置 (General Settings)
├── DNS 解析配置 (DNS Settings)
├── 代理节点定义 (Proxies)
├── 代理策略组 (Proxy Groups)
├── 外部规则集 (Rule Providers)
└── 路由分流规则 (Rules)

1. 基础通用设置 (General Settings)

控制 ClashFX 核心的监听端口、工作模式与运行权限：

# HTTP 与 SOCKS5 混合代理监听端口（macOS 常用 7890）
mixed-port: 7890

# 是否允许局域网设备连接（在家庭或办公室共享代理时开启）
allow-lan: false

# 绑定监听地址（默认仅本机）
bind-address: '*'

# 运行模式：rule（规则分流）、global（全局代理）、direct（全直连）
mode: rule

# 日志级别：info、warning、error、debug、silent
log-level: info

# 是否允许 IPv6 流量解析与路由
ipv6: false

# 外部控制面板端口与访问密钥（供面板或 API 控制）
external-controller: 127.0.0.1:9090
secret: ''

2. DNS 解析配置 (DNS Settings)

在开启 ClashFX 的增强模式 (TUN) 时，精准的 DNS 设置是避免 DNS 泄漏与加速域名解析的关键：

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  
  # 推荐模式：fake-ip（虚拟 IP 映射，极大提升首包解析速度）
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  
  # 不走 fake-ip 的纯直连域名（如 Apple 局域网服务、本地局域网等）
  fake-ip-filter:
    - '*.lan'
    - 'localhost.ptlogin2.qq.com'
    - '+.msftconnecttest.com'
    - '+.msftncsi.com'

  # 用于解析 DoH / DoT 上游服务器域名的基础 DNS
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29

  # 国内常规直连解析的上游 DNS
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query

  # 匹配境外代理规则时的备用与防污染 DNS
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query

3. 代理节点定义 (Proxies)

定义单个节点的连接协议、服务器地址、加密方式与证书：

proxies:
  - name: "香港 01 | 优质专线"
    type: shadowsocks
    server: hk01.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your_strong_password"

  - name: "日本 01 | VLESS Reality"
    type: vless
    server: jp01.example.com
    port: 443
    uuid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    network: tcp
    tls: true
    udp: true
    flow: xtls-rprx-vision
    servername: gateway.icloud.com
    reality-opts:
      public-key: "base64_encoded_public_key"
      short-id: "abcd1234"

4. 代理策略组 (Proxy Groups)

策略组用于将多个节点组合在一起，实现手动切换、按延迟自动优选或负载均衡：

• select：手动选择，用户可以在 ClashFX 菜单栏随时切换。
• url-test：自动测速，每隔一定时间向指定 URL 发送探测，自动路由至最低延迟节点。
• fallback：故障转移，按顺序检测健康状态，主节点异常时自动切换备用节点。
• load-balance：负载均衡，将并发连接分摊到不同节点。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - AUTO-FAST
      - 香港 01 | 优质专线
      - 日本 01 | VLESS Reality
      - DIRECT

  - name: AUTO-FAST
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - 香港 01 | 优质专线
      - 日本 01 | VLESS Reality

5. 路由分流规则 (Rules)

规则按从上到下的顺序匹配，一旦命中立即跳出：

rules:
  # 常用类型：DOMAIN-SUFFIX（域名后缀）、DOMAIN-KEYWORD（关键词）
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-KEYWORD,github,PROXY
  
  # GEOIP 匹配（由 Mihomo 的 GeoIP 数据库提供）
  - GEOIP,CN,DIRECT
  
  # 兜底匹配：未被上方规则命中的全部流量走 PROXY 或 DIRECT
  - MATCH,PROXY

标准开箱即用配置模板

以下是一个适配 ClashFX 1.1.11（Mihomo 核心）的标准精简配置模板。你可以直接将其复制到 ~/.config/clashfx/config.yaml 中，并替换 proxies 中的节点信息即可使用：

# ==========================================
# ClashFX 标准基础配置模板 (Mihomo 核心)
# ==========================================

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

# DNS 模块配置（推荐 fake-ip，配合增强模式更佳）
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'
    - '+.msftconnecttest.com'
    - '+.msftncsi.com'
  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://8.8.8.8/dns-query

# 代理节点列表（请替换为你的实际服务商节点）
proxies:
  - name: "示例 Shadowsocks 节点"
    type: ss
    server: server1.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "Password_Here"
    udp: true

# 策略组设计
proxy-groups:
  - name: 节点选择
    type: select
    proxies:
      - 自动优选
      - 示例 Shadowsocks 节点
      - DIRECT

  - name: 自动优选
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - 示例 Shadowsocks 节点

  - name: 国外媒体
    type: select
    proxies:
      - 节点选择
      - 自动优选
      - DIRECT

# 分流路由规则
rules:
  # 本地回环与局域网
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,172.16.0.0/12,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT

  # 常见开发与国际服务走代理
  - DOMAIN-SUFFIX,github.com,节点选择
  - DOMAIN-SUFFIX,githubusercontent.com,节点选择
  - DOMAIN-SUFFIX,google.com,节点选择
  - DOMAIN-SUFFIX,youtube.com,国外媒体
  - DOMAIN-SUFFIX,twitter.com,节点选择
  - DOMAIN-SUFFIX,openai.com,节点选择

  # 国内常见服务直连
  - DOMAIN-SUFFIX,baidu.com,DIRECT
  - DOMAIN-SUFFIX,qq.com,DIRECT
  - DOMAIN-SUFFIX,alipay.com,DIRECT
  - DOMAIN-SUFFIX,taobao.com,DIRECT
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT

  # 最终兜底规则
  - MATCH,节点选择

常见 YAML 语法陷阱与排查技巧

在编辑或手动编写 Clash 配置文件时，YAML 解析器对格式非常敏感，以下是 90% 用户的报错根源：

1. 严禁使用制表符（Tab 键）

YAML 语法规范严格禁止使用 Tab 制表符进行对齐。所有层级缩进必须使用纯空格（空格数通常保持为统一的 2 个空格）。在文本编辑器中输入了 Tab 往往会导致 mapping values are not allowed here 或 found character that cannot start any token 错误。

2. 键值冒号后必须包含半角空格

正确的语法是 key: value（冒号后紧跟一个空格）。如果写成 mixed-port:7890 或 mode:rule，解析器会将其视作一个未分割的字符串而报错。

3. 特殊字符与纯数字密码必须加引号

如果节点的密码中含有 #（YAML 注释符号）、@、:、! 等特殊符号，或者密码是一串纯数字（如 password: 12345678），必须用单引号或双引号包裹（如 password: "12345678#abc"），否则会被识别为注释或整型导致连接失败。

使用 ClashFX 内置编辑器修改与验证

ClashFX 免费核心内置了专业的 YAML 配置编辑器，具备以下开发辅助特性：

1. 语法高亮着色：对键名、字符串、布尔值和注释有鲜明的色彩区分，迅速发现未闭合引号或拼写失误。
2. 实时行号标注：当核心日志报告「第 45 行解析失败」时，可直接定位到对应行号。
3. 安全保存与重新加载：保存（快捷键 Cmd + S）后，ClashFX 会立即向 Mihomo 核心提交新配置，无需繁琐重启客户端。

如需开始编辑，点击 macOS 菜单栏的 ClashFX 图标 → 配置 → 编辑当前配置 即可立即调用内置编辑器。