Clash 配置文件
参考大全

01 / DOCUMENT MAP

YAML 结构总览与读取顺序

顶层字段怎样组成一份配置

Clash 配置文件通常命名为 config.yaml，本质上是一棵由映射、列表和标量组成的数据树。顶层映射负责划分功能区域：端口和运行模式决定流量怎样进入内核，dns 控制域名解析，proxies 描述单个代理节点，proxy-groups 把节点组织成可选择或自动测试的策略，rules 则按顺序把连接送往某个策略组。mihomo 还可使用 proxy-providers、rule-providers、tun、sniffer 等扩展区域。

解析配置时，缩进表示父子关系。同一级字段必须使用一致的空格数量，常见写法是每层两个空格。列表项以连字符开头，连字符后的对象仍可继续包含子字段。YAML 允许字符串不加引号，但节点名称、密码、正则表达式、带冒号或特殊符号的值容易被误判，稳妥做法是给这些值添加引号。布尔值使用 true 和 false，数字端口保持数字类型，不要写成带额外说明的字符串。

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

proxies:
  - name: "示例节点"
    type: ss
    server: example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

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

rules:
  - DOMAIN-SUFFIX,example.org,节点选择
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

映射、列表与名称引用

dns: 后面是一组映射字段；proxies: 后面则是对象列表。策略组中的 proxies 也是列表，但它保存的是名称引用，而不是再次声明节点。名称必须逐字对应，包括大小写、空格和符号。若节点名为“香港 01”，策略组里写成“香港01”就会成为不存在的引用。规则的最后一段同样引用策略组名或内置策略，例如 DIRECT、REJECT。修改名称时，需要同步检查策略组、规则和界面覆写中的所有引用位置。

YAML 锚点和别名可以减少重复，但并非所有图形客户端的保存、转换和覆写流程都能完整保留锚点。用于长期维护的公开配置，优先采用清晰的显式字段。配置较大时，可把节点和规则拆到 provider 文件中，由主配置引用；这样比在单个文件里堆叠数千行更容易更新，也能把“节点数据”和“分流逻辑”分开维护。

最小配置与加载边界

一份能启动的最小配置不等于能正确联网。仅配置端口和模式时，内核可能正常监听，但规则引用的策略不存在、DNS 无法解析节点域名，仍会导致连接失败。检查顺序应从语法开始，再确认引用完整，最后验证网络行为。客户端提示“配置加载成功”只能说明结构基本可解析，不代表每条节点凭据、远程集合地址和规则目标都有效。

另外，不同内核维护阶段支持的字段范围并不完全相同。原版 Clash、Clash Meta 与当前 mihomo 的名称演变和兼容关系，可参考内核版本区别说明。如果客户端采用 mihomo 内核，可以使用其扩展字段；若配置要在多个客户端之间共用，应先确认各客户端实际搭载的内核，不要仅依据客户端界面名称判断。

02 / RUNTIME

通用字段：端口、模式与控制接口

mixed-port、port 与 socks-port

mixed-port 在同一个监听端口上接受 HTTP 和 SOCKS5 代理连接，适合桌面客户端和多数手动代理场景。port 只提供 HTTP 代理，socks-port 只提供 SOCKS5。三者可以按需组合，但不要让多个字段占用同一个端口，也不要与本机其他程序的监听端口冲突。若图形客户端已经接管端口设置，界面值可能在启动时覆盖配置文件，因此排查时要同时查看界面和实际运行日志。

应用填写代理地址时，运行在同一台设备上的程序通常连接 127.0.0.1。局域网其他设备需要连接 Clash 所在设备的局域网地址，同时还要开启 allow-lan，并确认系统防火墙允许对应端口。开放局域网监听会扩大可访问范围，应通过 bind-address 限定接口，并在需要时设置认证信息。端口设置完成后，可通过操作系统的网络连接信息确认监听状态，而不是反复修改端口碰运气。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

rule、global 与 direct 模式

mode: rule 按 rules 从上到下匹配，是日常使用的主要模式。global 把可代理流量统一交给全局策略，适合临时验证某个节点是否可用，但它会绕过原本的分流意图。direct 则让流量直接连接，常用于快速判断问题是否由代理链路引起。界面切换模式后，部分客户端会只修改运行状态而不改写 YAML；重启后是否保留取决于客户端设置。

定位故障时可做一组对照：规则模式失败而全局模式成功，通常说明规则目标、规则顺序或策略组引用有问题；全局模式也失败，则应继续检查节点、系统代理、TUN、DNS 或网络环境；直连模式仍无法访问本地服务，问题可能与 Clash 配置无关。模式切换只是诊断手段，完成测试后应恢复规则模式，避免长期丢失域名和区域分流。

日志、IPv6 与外部控制器

log-level 常用值包括 silent、error、warning、info 和 debug。日常使用选择 info 即可；遇到规则命中或连接阶段不明确的问题，可暂时切到 debug，收集完信息后再恢复，避免日志快速增长。日志中重点观察目标域名、命中的规则、最终策略、DNS 错误和连接超时，不要只看最后一行。

ipv6 控制内核是否处理 IPv6 相关能力，但 DNS 区域也有独立的 IPv6 选项。网络具备稳定 IPv6 且节点链路支持时可开启；若本地获得 IPv6 地址却缺少可用出口，可能出现应用优先尝试 IPv6 后等待超时的现象。排查时应分别确认系统网络、DNS 返回结果、Clash 顶层开关和 DNS 子项，避免只改一个字段。

external-controller 为控制面板和客户端前端提供 API，例如 127.0.0.1:9090。若监听范围超出本机，应设置 secret 并限制防火墙访问。控制接口不是代理端口，浏览器或应用不能把它当作 HTTP 代理使用。external-ui 指向静态面板文件目录，路径应由运行环境实际目录决定，不宜把某台设备的绝对路径直接同步到其他系统。

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"
external-ui: ui

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

profile.store-selected 用于保存策略组的选择结果，重启时继续使用上次选项；store-fake-ip 则与 Fake-IP 映射持久化有关。配置跨设备同步时，不应假设运行状态也会随 YAML 一起同步。订阅、覆写和私有仓库三种同步路径的边界，可继续阅读Clash 多设备配置同步。

03 / DNS PIPELINE

DNS 配置与 Fake-IP 解析流程

DNS 请求经过哪些阶段

Clash 的 DNS 模块不只是把域名转发给某个服务器。启用后，它会接收应用查询，根据 nameserver-policy、fallback 等规则选择上游，并把解析结果交给规则匹配和连接流程。节点服务器本身如果使用域名，还涉及 bootstrap 解析：内核必须先获得节点域名的地址，才能建立加密连接。因此 DNS 故障既可能表现为网页域名打不开，也可能表现为所有域名节点同时超时。

listen 指定 DNS 服务监听地址。桌面图形客户端通常已经处理系统 DNS 或 TUN 劫持，不一定需要用户把系统 DNS 手动改到该端口。路由器或局域网网关场景则常会把客户端查询转发到这里。若监听 0.0.0.0，应结合防火墙限制访问范围；只在本机使用时，优先监听回环地址。

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query
  direct-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "+.stun.*.*"

default-nameserver 与 nameserver 的区别

default-nameserver 主要负责解析加密 DNS 上游自身的域名，通常填写可直接访问的 IP 形式 DNS 地址，避免形成“要访问 DoH 先解析 DoH 域名，但解析又依赖 DoH”的循环。nameserver 是主要查询上游，可以填写 UDP、TCP、DoT 或 DoH 地址。上游数量并非越多越好；混入行为差异很大的解析器会让结果难以预测，也增加排错分支。

proxy-server-nameserver 可专门用于解析代理节点服务器域名，避免节点域名沿错误路径查询。direct-nameserver 用于直连域名解析，适合将本地区域流量交给距离较近的解析器。启用 respect-rules 后，DNS 查询会更多地参考规则路径，此时需要确保代理节点域名有独立的解析出口，否则可能发生策略依赖循环。

Fake-IP 与 Redir-Host 怎样选择

enhanced-mode: fake-ip 会从保留地址段分配临时地址给域名。应用先获得这个映射地址，连接到来时内核再还原原始域名并执行域名规则。其优点是能在连接阶段保留域名信息，减少“先解析成 IP 后只能命中 IP 规则”的情况。Fake-IP 并不代表连接目标真的位于该保留网段，它只是内核内部的域名映射标识。

redir-host 返回真实解析地址，再由透明代理或嗅探能力补充域名信息。某些依赖局域网发现、局域网域名、特殊认证或直接检查解析地址的程序更适合真实地址模式，但规则精度和缓存行为需要结合具体平台评估。大多数桌面和移动端常规代理场景可先使用 Fake-IP，再把不兼容域名加入 fake-ip-filter，而不是一遇到局部问题就整体切换模式。

排除项应尽量具体。*.lan、*.local 常用于本地设备发现，时间同步、STUN、游戏平台和部分企业内网域名也可能需要真实结果。过宽的通配符会让大量域名绕过 Fake-IP，降低规则匹配一致性。有关映射、规则命中和排除项的完整流程，可查看Fake-IP 模式原理。

DNS 泄漏与解析故障的定位方法

所谓 DNS 路径异常，通常要拆成三个问题：查询由哪个组件发出、请求送到了哪个上游、最终连接采用哪条策略。浏览器可能启用自己的安全 DNS，系统服务可能绕开应用代理，TUN 也可能通过 DNS 劫持接管查询。只看网页显示的解析器名称，无法直接断定全部流量路径。应先关闭不参与测试的浏览器独立 DNS，再观察 Clash 日志中的查询与规则记录。

遇到订阅可更新但节点全部显示域名解析失败时，先检查 default-nameserver 和节点域名解析；普通网站失败但 IP 地址可连接时，再检查主要 nameserver、监听端口和系统 DNS 接管；少数局域网设备失效时，检查 Fake-IP 排除项。若出现间歇性超时，可暂时只保留一个确认可达的上游，排除并发上游差异、网络阻断和缓存影响，再逐项恢复。

04 / PROXY OBJECTS

代理节点字段与协议对象

所有节点共有的识别字段

proxies 中的每个对象至少要有 name、type、server 和 port，其他字段由协议决定。name 是配置内部的唯一标识，也会显示在客户端界面。名称重复时，策略组引用和界面选择可能产生歧义，因此应在生成配置时保证唯一。server 可以是域名或 IP；使用域名有利于服务端切换地址，但会增加节点域名解析这一前置步骤。

udp 表示节点是否允许承载 UDP，具体可用性还取决于协议、服务端和客户端入口。游戏、语音、QUIC 和部分 DNS 流量可能依赖 UDP。开启字段不代表链路必然支持，若服务端或中间网络不支持，日志中可能出现握手成功但 UDP 无响应。interface-name 和 routing-mark 属于更偏向多网卡或 Linux 路由的控制字段，普通桌面配置不必主动添加。

Shadowsocks 与 Trojan 示例

proxies:
  - name: "SS-示例"
    type: ss
    server: ss.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojan-示例"
    type: trojan
    server: trojan.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false
    udp: true
    network: tcp

Shadowsocks 的 cipher 必须与服务端一致，密码也按原始内容填写。不要因为字段名相同，就把不同协议的凭据互换。Trojan 依赖 TLS，sni 用于指定握手中的服务器名称，通常应与服务端证书覆盖的域名一致。skip-cert-verify: false 表示执行证书验证，是正常配置的优先选择。若验证失败，应检查设备时间、证书域名、SNI 和服务端证书链，而不是长期关闭验证。

network 描述底层传输，例如 TCP、WebSocket 或 gRPC。选择 WebSocket 时还需提供路径和请求头；选择 gRPC 时通常需要服务名。传输字段必须与服务端入口完整对应。常见错误是只复制了协议、地址和密码，却遗漏传输层路径，结果 TCP 能到达端口但握手持续失败。

VMess 与 VLESS 的层级字段

proxies:
  - name: "VLESS-WS-示例"
    type: vless
    server: edge.example.com
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    network: ws
    tls: true
    servername: service.example.com
    udp: true
    ws-opts:
      path: /network-path
      headers:
        Host: service.example.com

  - name: "VMess-gRPC-示例"
    type: vmess
    server: grpc.example.com
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    alterId: 0
    cipher: auto
    tls: true
    servername: grpc.example.com
    network: grpc
    grpc-opts:
      grpc-service-name: proxy-service

VLESS 和 VMess 都使用 UUID 形式身份信息，但协议行为和字段集合不同。ws-opts、grpc-opts 是与 network 对应的嵌套映射，缩进错位会让参数落到节点对象的错误层级。TLS 场景中，连接地址、SNI 或 servername、HTTP Host 可以不同：连接地址决定实际连向哪里，SNI 用于 TLS 证书和虚拟主机选择，Host 则属于 HTTP 或 WebSocket 请求头。三者是否相同由服务端部署决定，不能凭经验互相替换。

示例 UUID 和域名只用于展示字段结构，不能直接用于连接。实际节点数据应来自用户有权使用的服务配置。订阅生成的节点通常不建议手动逐项重写，因为一个遗漏的传输字段就会造成难以识别的差异；更适合通过 provider 加载，再用策略组和规则管理。

Reality、证书与指纹相关字段

mihomo 支持的部分 VLESS 配置会包含 Reality 参数，例如公钥、短标识和客户端指纹。字段名称与层级必须遵循当前内核支持格式，并与服务端配置对应。由于这类能力在旧内核或旧客户端中可能缺失，把配置同步到其他设备前应确认其内核兼容性。遇到“字段不支持”或“配置解析失败”时，先查看客户端使用的内核类型，再决定是调整字段还是更换支持该配置的客户端。

client-fingerprint 影响 TLS 客户端指纹模拟，但它不是修复所有握手问题的通用开关。证书名称错误、系统时间偏差、SNI 不匹配和网络阻断仍应分别处理。对于客户端选型，桌面与移动平台均优先从安装包页面选择 Clash Plus；需要其他界面或系统适配时，再比较 Clash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、Surfboard、ClashX Meta 与归档的 Clash for Windows。

05 / POLICY GROUPS

策略组字段与选择逻辑

select：把选择权交给用户

策略组是规则和节点之间的中间层。规则不宜直接指向某个会变化的节点名称，而应指向稳定的策略组，例如“节点选择”“流媒体”或“下载服务”。节点更新时只需调整策略组成员，规则结构可以保持不变。select 组由用户手动选择一个成员，成员既可以是节点，也可以是另一个策略组或内置策略。

proxy-groups:
  - name: "节点选择"
    type: select
    proxies:
      - "自动选择"
      - "故障转移"
      - "香港节点"
      - "日本节点"
      - DIRECT

  - name: "香港节点"
    type: select
    use:
      - subscription-main
    filter: "(?i)港|hk|hong kong"

proxies 引用静态节点或其他组，use 引用 proxy-providers。两者可以按内核能力组合使用。filter 通常以正则表达式筛选 provider 中的节点名称，命名习惯会直接影响结果。订阅若把地区名称改成其他格式，原有筛选可能得到空组。维护配置时应把筛选表达式看作依赖订阅命名的数据规则，更新后检查组内是否仍有成员。

url-test：按探测结果自动选择

url-test 会定期访问指定 URL，根据测试结果在组内选择表现合适的节点。url 应指向体积小、响应稳定且符合使用路径的测试资源；interval 是测试周期；tolerance 用于减少结果接近时频繁切换。测速只能反映探测目标在某一时刻的响应情况，不等同于下载速度、视频吞吐或所有站点的体验。

  - name: "自动选择"
    type: url-test
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80
    lazy: true
    expected-status: 204

lazy: true 表示策略实际被使用时再按需进行测试，有助于减少闲置组的探测请求。测试地址如果在当前网络被重定向、阻断或返回不同状态，全部节点可能被误判为不可用。此时应先直接检查测试 URL 的可达性，再更换为稳定资源，而不是删除整个自动策略。自动选择组适合普通网页流量，但需要固定出口地址的登录会话、远程管理或白名单服务，更适合手动选择并保持节点。

fallback 与 load-balance

fallback 按列表或探测结果维护可用顺序，当前节点失败时切换到其他成员，重点是连续可用性。它不保证每次都选到延迟最低的节点。load-balance 把不同连接分配到多个节点，适合可接受多出口的并发请求；如果网站把同一登录过程中的出口变化视为异常，负载均衡反而会影响会话。

  - name: "故障转移"
    type: fallback
    proxies:
      - "香港节点 01"
      - "日本节点 01"
      - "新加坡节点 01"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: "并发分配"
    type: load-balance
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 600
    strategy: consistent-hashing

负载均衡策略中，一致性哈希会尽量让相同目标落到稳定节点，轮询则更强调连接分散。使用前需要明确业务是否允许出口变化，不应把“同时使用多个节点”简单理解为单连接带宽叠加。单个 TCP 连接通常仍由一个节点承载，多个节点主要分担不同连接。

策略组嵌套与环路防止

组可以引用组，因此能构建“业务策略 → 地区策略 → 节点”的层级。例如视频规则指向“流媒体”，该组再允许选择“香港节点”或“日本节点”。这种结构能减少重复，但层级过深会增加排查难度。更重要的是不能形成循环引用：A 包含 B，B 又包含 A，会导致配置校验失败或运行逻辑无法确定。

命名应表达功能而非临时节点状态。规则目标用“即时通信”“开发服务”“兜底代理”等稳定名称，地区组用“香港节点”“日本节点”，具体节点名留在最底层。这样订阅更新、节点增删或地区筛选变化时，上层规则不需要改写。若策略选择在重启后丢失，检查 profile.store-selected 和客户端自身的配置持久化方式，而不是把选中节点硬编码到所有规则中。

06 / ROUTING RULES

规则语法、匹配顺序与兜底

规则是从上到下的首次匹配

rules 是有顺序的列表。连接到来后，内核从第一条开始检查，命中后立即采用该条指定的策略，不再继续向下寻找“更具体”的规则。因此具体域名、业务规则和特殊直连通常放在前面，较宽的域名后缀、IP 区域规则放在后面，最后使用 MATCH 处理剩余流量。规则顺序写反，是“规则看起来存在但从未生效”的主要原因之一。

标准规则通常以逗号分隔：规则类型、匹配内容、目标策略，部分类型还可附加参数。例如 DOMAIN-SUFFIX,example.com,节点选择 匹配该域名及其子域名；DOMAIN,api.example.com,DIRECT 只匹配完整域名；DOMAIN-KEYWORD,example,节点选择 匹配包含关键词的域名，范围更宽，应避免使用过于普通的关键词。

rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,example.cn,DIRECT
  - DOMAIN-SUFFIX,example.com,节点选择
  - DOMAIN-KEYWORD,video,流媒体
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

域名规则的精度差异

DOMAIN 精确匹配一个完整域名，适合单独处理 API、下载域名或局域网主机。DOMAIN-SUFFIX 按域名边界匹配主域及子域，是维护站点规则时最常用的形式。DOMAIN-KEYWORD 只要域名中出现指定文本就可能命中，容易误伤其他站点，应放在精确规则之后，并选择足够独特的关键词。

如果同一服务使用多个域名，仅添加首页域名通常不够。网页还可能请求登录、接口、图片、媒体和静态资源域名。应从连接日志中观察实际请求，再补充规则，而不是根据页面标题猜测。对于持续变化的大型服务，使用维护良好的 rule-provider 比手工追加大量域名更合理。

IP-CIDR、GEOIP 与 no-resolve

IP-CIDR 根据 IPv4 网段匹配，IP-CIDR6 用于 IPv6。内网、回环和特定服务地址常通过 CIDR 直连。规则末尾的 no-resolve 表示匹配该 IP 规则时不要为了获得地址而额外触发 DNS 解析，适合连接本身已经有目标 IP 的情况。若规则需要从域名解析出 IP 才能判断，就不应机械添加该参数。

GEOIP 根据 IP 数据库判断区域。它发生在获得目标 IP 之后，不能完全替代域名规则。CDN 可能按网络环境返回不同地区地址，同一站点也可能使用跨区域基础设施，因此“域名属于某地区”和“当前 IP 被数据库归到某地区”不是同一件事。对明确服务优先使用域名或规则集合，GEOIP 更适合作为靠后的大范围分流。

进程、端口与逻辑组合规则

支持相应能力的平台和内核可使用 PROCESS-NAME、PROCESS-PATH、DST-PORT、SRC-IP-CIDR 等规则。进程规则依赖系统提供进程信息，在移动端、容器、权限受限环境或 TUN 实现差异下可能不可用。端口规则只说明目标端口，不代表应用类型；大量服务共用 443 端口，仅按端口代理会覆盖过宽。

mihomo 的逻辑规则可用 AND、OR、NOT 组合多个条件，适合表达“某进程访问某网段”这类条件。但逻辑表达式越复杂，越需要清楚括号、引号和参数分隔方式。实际维护时，应先用普通规则验证每个条件是否能单独命中，再组合，避免把语法错误、平台能力和逻辑结果混在一起排查。

rules:
  - PROCESS-NAME,example-client,节点选择
  - DST-PORT,22,开发服务
  - AND,((NETWORK,TCP),(DST-PORT,443)),节点选择
  - OR,((DOMAIN-SUFFIX,example.org),(DOMAIN-SUFFIX,example.net)),开发服务
  - MATCH,兜底代理

规则命中不符合预期时怎样定位

第一步查看连接日志中的目标域名或 IP、命中规则和最终策略。第二步确认命中规则上方是否有更宽的规则提前截获。第三步检查规则目标策略组当前选中了什么成员。第四步确认 DNS 模式是否保留了域名信息；若应用直接连接 IP，域名规则自然不会命中。最后再检查 rule-provider 是否更新成功、行为类型是否与文件内容匹配。

临时测试可以把一条精确规则放到列表最前面，重载配置后重新发起新连接。已有连接可能继续复用旧链路，因此只刷新页面未必足够，必要时关闭应用连接或清理连接列表。验证完成后，将规则移动到合理层级。区域分流的完整 YAML 编排示例可继续阅读Clash 规则分流配置实战。

07 / PROVIDERS

代理集合、规则集合与远程更新

proxy-providers 把节点数据移出主配置

proxy-providers 用于加载远程或本地节点集合。主配置只保留 provider 名称、来源、更新周期和健康检查，策略组通过 use 引用集合。这样订阅更新只改变节点层，端口、DNS、策略组和规则仍由本地配置控制。与把订阅直接当作完整配置相比，这种结构更适合维护固定的分流逻辑。

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

proxy-groups:
  - name: "节点选择"
    type: select
    use:
      - subscription-main
    proxies:
      - DIRECT

type: http 表示从远程地址获取，path 是下载后的本地保存位置，interval 是自动更新间隔。proxy 决定更新请求经过哪个策略；首次启动时代理策略可能还没有可用节点，因此通常先用 DIRECT，若订阅地址在当前网络无法直连，再结合客户端提供的订阅更新代理功能处理。不要让 provider 的更新依赖它自身尚未加载的节点，否则容易形成启动依赖。

健康检查只是在固定 URL 上验证节点响应，不会修复订阅下载错误。订阅更新失败应区分 HTTP 状态、网络超时、地址失效、返回内容不是 YAML、文件写入失败和解析失败。客户端提示相同的“更新失败”时，日志中的阶段信息才是定位依据。常见处理路径也可在常见问题中查阅。

rule-providers 与 behavior

rule-providers 把大量规则拆成独立文件，主规则列表用 RULE-SET 引用。关键字段 behavior 描述集合内容的形态。domain 适合域名类条目，ipcidr 适合 IP 网段，classical 则保存完整的经典规则表达式。behavior 与文件内容不匹配时，集合可能加载失败或无法按预期命中。

rule-providers:
  local-services:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example.com/local-services.yaml"
    path: ./ruleset/local-services.yaml
    interval: 86400

  private-networks:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-networks.yaml

rules:
  - RULE-SET,private-networks,DIRECT
  - RULE-SET,local-services,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

domain behavior 的 YAML 文件通常以 payload 保存域名条目；ipcidr 文件保存网段；classical 文件中的每项则类似主配置中的完整规则，但通常不在条目里写最终策略，因为策略由主配置的 RULE-SET 行指定。引用层负责决定去向，集合文件负责描述匹配对象，这种分工允许同一集合在不同配置中指向不同策略。

payload:
  - "+.example.cn"
  - "api.example.net"
  - "download.example.org"

更新周期、缓存与失败回退

更新间隔应根据数据变化频率设置。节点订阅可能需要较短周期，稳定的规则集合可以按天更新。过短间隔会增加远程请求和配置重载频率，也会在网络不稳定时产生大量错误日志。远程更新失败时，内核通常会尝试继续使用本地缓存文件，因此 path 所在目录需要可写，并且不能被系统清理工具频繁删除。

如果首次加载就失败，本地尚无缓存，引用该 provider 的组或规则集可能不可用。部署到新设备前，应测试远程地址可达、返回格式正确、保存目录可创建。跨平台同步配置时，优先使用相对路径；Windows、macOS、Android、iOS 和 Linux 的配置根目录不同，写死某个平台的绝对路径会让其他设备加载失败。

订阅凭据与配置分层

订阅地址通常包含访问凭据，不应放入公开仓库、公开日志或公开截图。需要多设备同步时，可把不含凭据的主配置、策略组和规则放入私有维护路径，把订阅地址通过客户端本地覆写或设备专用文件加入。这样既能共享分流逻辑，也能避免所有设备被迫使用完全相同的运行参数。

配置分层可按四部分理解：主配置负责运行方式，provider 负责节点或规则数据，策略组负责可选出口，设备覆写负责本机差异。任何更新都尽量只修改所属层。若把端口、节点、规则和设备路径全部塞进一份订阅生成文件，更新冲突和排错成本会明显增加。

08 / OVERRIDE & DEBUG

覆写、合并、校验与故障定位

为什么订阅更新会覆盖手工修改

很多图形客户端把远程订阅转换成运行配置。用户直接编辑转换后的文件，下一次更新时客户端会重新生成内容，因此新增规则、端口和 DNS 设置可能消失。覆写功能的目的，是在订阅更新之后、内核加载之前，把本地调整重新应用到生成结果。不同客户端可能把它称为覆写、扩展、脚本、混入或配置合并，具体支持的合并规则也不同。

简单标量字段通常采用后值覆盖前值，例如本地 mixed-port 替换订阅中的端口。映射字段可能递归合并，例如只修改 dns.ipv6 而保留其他 DNS 项。列表最容易出现差异：有的实现整体替换 rules，有的支持前置、后置和删除操作，有的需要脚本返回完整数组。使用前应查看客户端的覆写说明，并通过最终生成配置验证结果。

# 本地覆写示意：具体文件入口由客户端决定
mixed-port: 7890
mode: rule
log-level: info

dns:
  enable: true
  ipv6: false

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

规则合并应明确前置还是后置

由于规则采用首次匹配，添加位置会改变含义。局域网直连、单个域名修正和需要压过订阅默认行为的规则，通常应前置；作为补充但不希望影响已有精确规则的条目，可以放在订阅规则之后、最终 MATCH 之前。直接把新规则追加到 MATCH 后面不会生效，因为所有剩余连接已经被 MATCH 截获。

如果客户端只支持整体替换列表，就需要在覆写中保留完整规则顺序，或改用 rule-provider，把自定义集合放在主配置中稳定引用。不要依赖“合并工具会自动判断更具体的规则”，YAML 合并只处理数据结构，不理解分流语义。每次合并后都应打开最终配置，搜索自定义规则的位置，并确认只有一个合理的兜底项。

rules:
  # 本机服务与局域网规则前置
  - DOMAIN,router.local,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

  # 自定义规则集合
  - RULE-SET,development-services,开发服务

  # 通用区域与兜底规则
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

加载前的语法与引用校验

语法校验先看 YAML 是否能解析，再看 Clash 字段是否合法。通用 YAML 工具能发现缩进、冒号和引号错误，却不了解 proxy-groups 是否引用了不存在的节点。内核的配置测试则能继续检查字段类型、策略引用、provider 定义和规则格式。图形客户端通常在导入或重载时显示错误位置；Linux 命令行部署可使用所安装内核提供的配置测试参数，实际命令以该内核帮助信息为准。

看到行号时，不要只检查该行。YAML 解析器常在“发现结构无法继续”时报告位置，真正原因可能是前几行少了引号、缩进或列表连字符。排查方法是从报错行向上找到最近的同级字段，比较缩进；对长配置可二分注释最近新增的区域，快速判断错误落在哪一段。

# Linux 环境示意：先查看实际安装的内核参数
mihomo -h

# 常见配置测试形式，路径按本机目录调整
mihomo -t -f ./config.yaml

一套可重复的故障定位流程

第一阶段确认内核是否启动。查看配置加载结果、监听端口和控制接口，若启动前就失败，集中处理 YAML、字段兼容和文件权限。第二阶段确认流量是否进入 Clash：检查系统代理、应用代理、TUN 状态以及日志中是否出现对应请求。没有请求记录时，不应先修改节点或规则，因为流量尚未到达内核。

第三阶段确认 DNS 和节点。用日志判断目标域名是否解析、节点服务器是否可达、TLS 或协议握手在哪一步失败。将模式临时切到全局并选择一个确认可用的节点，可以把规则问题与节点问题分离。第四阶段检查策略和规则：记录命中的规则、目标策略组、组内当前选择以及 provider 状态。第五阶段才处理应用特例，例如浏览器独立代理、安全 DNS、QUIC、进程识别和局域网发现。

安全回退与变更记录

每次只修改一个功能区域，并保留一份能加载的配置。端口、DNS、TUN 和规则同时改变时，故障出现后很难确定来源。较稳妥的流程是：复制原配置，记录修改目标，完成一组改动，执行语法测试，重载后观察新连接；确认稳定再继续下一组。配置进入私有版本库时，提交说明应写清行为变化，例如“局域网域名改为真实解析”或“开发服务规则前置”，而不是只写“更新配置”。

回退时不仅要恢复 YAML，还要考虑客户端保存的策略选择、Fake-IP 缓存、provider 缓存和系统代理状态。若恢复文件后现象不变，可重载配置并建立新连接，必要时重启内核，以排除旧连接继续占用原策略。不要先清空所有缓存和配置；保留现场信息更利于判断究竟是哪一层发生变化。

从手册回到实际配置

首次搭建建议采用小步结构：先配置 mixed-port、规则模式和一个可用节点，再建立“节点选择”策略组，加入基础直连和 MATCH 规则；确认流量正常后，再开启 DNS 增强模式、引入 provider 和业务规则集合。这样每一步都有明确验证结果，也能避免把订阅、DNS、TUN 和复杂规则同时引入。

需要安装或更换客户端时，从Clash 安装包页面按系统选择，桌面与移动平台优先使用 Clash Plus；只想完成订阅导入、模式选择和连接验证时，回到Clash 使用教程。遇到端口占用、订阅更新失败、系统代理未恢复或特定平台权限问题，可在常见问题按故障类别查找。Linux 桌面、命令行和 systemd 服务部署则可参考Linux 部署 Clash。