Clash 配置文件参考大全

01 / DOCUMENT SHAPE

YAML 结构总览：先看层级，再改字段

顶层区块怎样协同工作

一份可运行的 Clash Meta 配置并不是互不相关的字段集合，而是一条有明确引用方向的处理链。通用字段决定监听端口、运行模式和局域网访问边界；dns 决定域名如何解析；proxies 与 proxy-providers 提供可用代理；proxy-groups 把代理和其他策略组组织成选择、测速或故障转移关系；rule-providers 提供外部规则集合；最后的 rules 按书写顺序把连接交给某个策略组。只要其中一层名称没有对上，后面的结构即使语法正确，也可能在加载或运行阶段失效。

YAML 通过缩进表达父子关系，通常使用两个空格，不应混入制表符。冒号后需要空格，列表项以连字符开头，同级字段必须保持相同缩进。字符串是否加引号取决于内容：普通英文名称可以直接写；包含冒号、井号、花括号或容易被解释成布尔值的内容，使用引号更稳妥。策略组名称含空格和中文是允许的，但所有引用处必须逐字一致，包括大小写、空格和标点。

mixed-port: 7890
mode: rule
log-level: info
allow-lan: false

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: "示例节点"
    type: socks5
    server: 127.0.0.1
    port: 1080

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

rules:
  - DOMAIN-SUFFIX,example.com,节点选择
  - MATCH,DIRECT

映射、序列与标量的区别

dns: 后面跟随的是映射，也就是一组键值字段；nameserver: 后面是序列，每个上游服务器占一个列表项；mode: rule 中的 rule 则是标量。最常见的结构错误，是把本应属于某个列表项的字段退回到顶层，或者让第二个节点的字段仍然缩进在第一个节点内部。复杂节点建议采用“一个连字符开始一个完整对象”的排版，每个对象内部字段垂直对齐，修改时更容易发现错层。

YAML 锚点和别名可以复用片段，但订阅转换、客户端覆写和部分编辑器对高级 YAML 语法的处理并不完全一致。面向长期维护的配置，优先使用清晰的显式字段；只有大量节点确实共享一组参数，并且已经确认加载链支持锚点时，再引入 &name 与 *name。重复几行配置通常比隐藏的继承关系更容易排查。

最小配置与完整配置

最小配置可以只有监听端口、一个代理、一组策略和末尾规则，但实际使用通常还要加入 DNS、订阅提供器、规则集合、TUN 与持久化设置。建议先让最小骨架成功加载，再逐个增加区块。一次加入整份复杂配置后才开始排错，很难判断故障来自 DNS、节点参数还是规则引用。新增区块时以“加载成功、连接成功、规则命中正确”三个阶段分别验证，避免把所有异常都归为配置文件不能用。

配置文件中的注释以 # 开始，适合记录字段用途和变更原因，但不要把依赖注释来解释的关键名称频繁改写。订阅更新可能重建节点区和策略组区，本地注释也可能被覆盖。长期说明应保存在独立文档，配置内只留下能帮助现场排错的短注释，例如某条直连规则服务于局域网设备，或某个 DNS 上游只能通过代理访问。

02 / GENERAL

通用字段：端口、模式、监听与运行状态

端口字段如何选择

port 提供 HTTP 代理端口，socks-port 提供 SOCKS5 端口，mixed-port 则让同一个端口同时接收 HTTP 与 SOCKS5 请求。桌面客户端只需要向其他程序暴露一个代理地址时，使用 mixed-port 最直接；某些软件明确要求某种协议，或需要分别记录两类连接时，可以拆成独立端口。端口号只要没有被其他进程占用即可，不要求固定为某个常见值。

redir-port、tproxy-port 属于透明代理入口，通常配合 Linux 防火墙规则使用，不等同于系统代理端口。只写这两个字段不会自动接管流量，还需要路由表、策略路由及 nftables 或 iptables 规则协同。图形客户端的 TUN 模式通常由客户端负责创建虚拟网卡和路由，不应同时照搬路由器上的透明代理规则，否则可能形成重复转发或回环。

mode 决定规则是否参与处理

mode: rule 按 rules 从上到下匹配，是日常分流的主要模式。global 会让连接统一进入全局策略，适合临时确认某个节点是否可用，但它会绕开原有规则逻辑；direct 则让连接直接访问目标，适合判断故障是否由代理链引起。排查“规则没有命中”时，第一步就是确认当前运行模式仍为 rule，因为图形客户端界面的模式切换可能覆盖配置文件中的初始值。

log-level 控制日志详细程度。正常运行可以使用 info，定位规则与连接问题时临时提高到 debug，完成排查后再调回，避免日志量持续增长。日志中的规则命中、DNS 查询、拨号失败和超时信息需要分开看：命中某个策略组只说明分流结果已经确定，并不能证明组内最终节点连接成功。

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

局域网访问与监听边界

allow-lan 决定其他设备能否访问 Clash 的监听端口。设为 true 后，还要确认操作系统防火墙放行对应端口，并使用运行 Clash 设备的局域网地址作为代理服务器。bind-address 用于限制监听地址；只供本机使用时维持回环访问边界，供局域网共享时才扩大监听范围。共享代理不应直接暴露到公网接口，尤其是云服务器或具有公网地址的网卡环境。

external-controller 提供控制接口，图形客户端和 Web 面板会通过它读取连接、日志和策略状态。控制接口与代理端口用途不同，不能把它当成浏览器代理地址。若控制接口允许非本机访问，应设置访问凭据并限制防火墙来源。配置中的控制凭据属于本地敏感信息，不应提交到公开仓库或发到公开问题区。

ipv6 影响内核是否处理和返回 IPv6 地址，但它不是简单的网络加速开关。上游网络、代理节点和目标站点任一环节的 IPv6 路径不完整，都可能表现为部分连接等待后回退。没有可用 IPv6 网络时关闭更容易保持行为一致；确实具备完整双栈环境时再启用，并分别检查 DNS 返回与实际连接路径。

03 / DNS PIPELINE

DNS 配置：解析路径、Fake-IP 与分流关系

DNS 区块解决的不是单一解析问题

Clash 的 DNS 模块既负责把域名解析为地址，也为域名规则、Fake-IP 映射和按策略选择上游提供基础。关闭内置 DNS 后，应用通常直接使用系统解析结果，内核可能只看到目标 IP，导致原本依赖域名的规则无法稳定命中。启用 DNS 后，应让需要接管的请求真正进入其监听地址；仅在配置里写 dns.enable: true，但系统仍向其他服务器发送查询，并不能形成完整的解析链。

listen 指定 DNS 服务监听位置和端口。桌面 GUI 的 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
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  proxy-server-nameserver:
    - https://223.5.5.5/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.local"

default-nameserver、nameserver 与代理节点域名

nameserver 是主要解析上游，可以填写传统 UDP 地址，也可以填写加密 DNS 地址。加密 DNS 自身也是域名时，内核必须先知道该域名对应的地址，因此需要 default-nameserver 完成引导解析。引导服务器通常填写可直接访问的 IP 地址，避免出现“需要解析上游域名才能访问上游，而解析又依赖该上游”的循环。

proxy-server-nameserver 用于解析代理服务器自身的域名。这个路径应优先选择在当前网络中可直接访问、结果稳定的上游，因为代理节点尚未建立之前，节点域名必须先完成解析。如果把节点域名的解析强制交给一个只能通过该节点访问的服务器，同样会形成启动依赖环。节点表现为全部超时，而 IP 形式节点正常时，应优先检查这一层。

respect-rules 让 DNS 查询参考规则选择出口，适合需要对解析流量也做分流的配置。不过开启后必须确保引导解析、代理节点解析和主解析之间没有相互等待。配置复杂时，先关闭规则感知并验证基本解析，再逐步启用，是比一次堆入全部 DNS 选项更稳妥的调试顺序。

Fake-IP 与 Redir-Host 的差异

fake-ip 模式会从保留地址池返回一个映射地址，应用连接该地址后，内核根据映射表还原原始域名并执行规则。它能够让域名信息在连接阶段继续保留，也减少应用先获得真实地址再发起连接时产生的分流偏差。地址池只在本机或受控网络内部作为映射使用，不是目标网站的真实地址，看到保留网段结果不等于 DNS 解析故障。

redir-host 返回真实解析地址，兼容依赖真实 IP 的局域网服务、部分游戏和特殊网络检测，但域名与后续连接的关联能力相对受限。遇到打印机发现、局域网主机名、设备投屏或特定应用登录异常时，可以先把对应域名加入 fake-ip-filter，不必直接切换整个增强模式。过滤列表应尽量精确；把范围写得过大，会让大量域名绕过映射，降低域名规则的一致性。关于映射过程和筛选边界，可继续阅读Fake-IP 模式原理详解。

nameserver-policy 的定向解析

nameserver-policy 可以让特定域名使用指定 DNS 上游。例如内部域名交给局域网 DNS，某一类公共域名交给另一组解析器。策略键可以使用域名规则集合或域名匹配形式，值可以是一个上游，也可以是一组上游。它解决的是“某类域名应在哪里解析”，不是“连接最终走哪个代理”；连接出口仍由 rules 和策略组决定。

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "+.corp.example":
      - 192.168.1.1
    "rule-set:private-domain":
      - 192.168.1.1

04 / PROXY OBJECTS

代理节点字段：连接对象、协议参数与提供器

节点对象的共同骨架

proxies 是节点对象列表。每个对象至少需要名称、类型、服务器地址和端口，认证、传输与加密字段则由协议决定。name 是其他区块引用节点的唯一标识，不应出现重复名称；当两个节点同名时，界面展示和策略引用都会变得难以判断。server 可以是 IP 或域名，填写域名时要同时保证 DNS 区块能够在节点连接前解析它。

协议字段不能跨类型照搬。一个字段在某种协议下有效，不代表放进另一种节点也会产生同样效果；未知字段可能被忽略，也可能导致配置检查失败。整理订阅时应保留协议要求的必要参数，删除转换链遗留但内核不识别的装饰字段。节点连接失败时，先核对类型、服务器、端口和认证四项，再检查 TLS、传输层与服务器名称，不要先修改策略组或规则。

proxies:
  - name: "办公 SOCKS"
    type: socks5
    server: 192.168.1.10
    port: 1080
    username: "proxy-user"
    password: "your-password"
    udp: true

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

TLS 与服务器名称

带 TLS 的协议通常涉及 tls、服务器名称和证书验证。服务器名称用于握手阶段选择证书和虚拟主机，它可能与节点连接地址相同，也可能由服务端单独指定。连接地址写成 IP 时，如果服务端证书签发给域名，就更需要正确填写服务器名称。证书错误不应通过长期关闭验证来掩盖，应先核对系统时间、节点信息、服务器名称和中间网络。代理开启后遇到浏览器证书提示，可以参考HTTPS 证书报错逐项排查。

WebSocket、gRPC 等传输层还会带路径、Host 或服务名。这些值由服务端部署决定，客户端无法通过猜测得到。路径中的斜杠、大小写和空字符都可能影响握手，订阅转换时也要避免把嵌套字段错误展开。若 TCP 已能连接服务器端口，但很快被关闭，日志出现握手失败，排查重点通常应从网络可达性转向 TLS 和传输层参数。

proxy-providers 管理动态节点集合

节点数量较多或来源需要定期刷新时，可使用 proxy-providers。提供器负责从文件或远端地址读取节点，并可配置健康检查；策略组通过 use 引用整个提供器，而不是把每个节点名称手工写入 proxies。这种结构能减少订阅更新后策略组漏掉新节点的问题，也便于把不同来源拆成独立集合。

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

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

path 是提供器内容的本地缓存位置，运行用户必须对其父目录有写入权限。容器和系统服务环境中，相对路径以进程工作目录为基准，不一定是配置文件所在目录；出现提供器下载成功但缓存写入失败时，应检查实际工作目录和挂载路径。远端地址中的访问参数属于敏感配置，分享日志或配置片段前要移除。

健康检查只回答测试地址能否经该节点完成请求，并不代表所有目标都能访问，也不等同于带宽测试。检查地址应稳定、响应体小，并与日常流量的协议需求相近。检查频率过高会持续建立连接，节点多时会带来额外资源消耗；频率过低则可能让故障状态更新不及时。应根据节点数量和切换需求取平衡，而不是单纯追求更短间隔。

05 / POLICY LAYER

策略组字段：选择、测速、故障转移与嵌套

策略组是规则与节点之间的调度层

规则通常不直接指向某个固定节点，而是指向策略组。这样节点发生变化时，只需调整组内成员或当前选择，不必重写整套规则。select 组由用户手动选择成员；url-test 根据测试结果自动选择；fallback 按成员顺序寻找可用项；load-balance 在多个可用成员之间分配连接。不同类型解决的问题不同，不能仅凭界面显示的延迟判断哪一种更合适。

proxies 列表既可以放节点，也可以放另一个策略组，还可以使用 DIRECT 与 REJECT 等内置策略。嵌套让“业务分类”和“节点选择”分离，例如流媒体规则指向“媒体服务”，媒体服务再引用“节点选择”。但嵌套层数过深会增加判断成本，甚至形成循环引用。设计时应保证依赖方向单向向下，任何组都不能直接或间接包含自己。

proxy-groups:
  - name: "节点选择"
    type: select
    proxies:
      - "自动选择"
      - "故障转移"
      - "示例节点"
      - DIRECT

  - name: "自动选择"
    type: url-test
    proxies:
      - "示例节点"
      - "备用节点"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "故障转移"
    type: fallback
    proxies:
      - "示例节点"
      - "备用节点"
    url: https://www.gstatic.com/generate_204
    interval: 300

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

测速结果应怎样理解

url-test 测量的是从客户端经节点访问指定测试地址的完成时间，包含建立连接和请求响应，并不是所有网站的通用延迟。测试地址所在网络、节点对该地址的路由以及本地 DNS 都会影响结果。某节点测试值较低，却在实际下载中速度较慢，可能是带宽、拥塞、目标站路由或连接复用差异，而不是策略组计算错误。速度问题可按节点、线路和本地设置三层分别验证。

tolerance 用于避免两个结果接近的节点频繁切换。当新结果只比当前节点略好时，保持现有连接通常比反复重选更稳定。interval 控制周期检查，lazy 可让不活跃的策略减少测试。参数应围绕使用方式调整：桌面设备偶尔连接与常开路由器的资源预算不同，节点数量也会直接放大健康检查的请求量。

fallback 与 load-balance 的边界

fallback 重视顺序和可用性，前面的成员可用时保持使用，适合主备关系明确的线路。它并不以最低延迟为唯一目标，因此备用节点延迟更低也不一定被选中。load-balance 面向多连接分配，不等于把单条下载连接拆到多个节点；单个 TCP 或 UDP 会话通常仍保持固定出口，以免源地址变化破坏会话。

负载均衡策略还要考虑同一目标是否需要固定出口。登录、支付、验证码或对来源地址敏感的服务，如果相邻请求落到不同节点，可能触发重新验证。此时应使用能维持目标映射的策略，或让相关域名进入固定节点组。对普通用户而言，清晰的手动选择组配合一个自动测速组，通常比多层负载均衡更容易维护。

名称设计影响长期维护

策略组名称既出现在规则末尾，也出现在客户端界面。建议按用途命名，例如“节点选择”“故障转移”“媒体服务”“即时通信”，不要把节点地区、协议和业务用途全部塞入同一个长名称。规则提供器与策略组之间可以一对多或多对一，但名称应保持稳定；频繁重命名会让旧覆写、脚本和本地规则同时失效。

订阅提供的策略组可能在更新时被重建。本地需要长期保留的组，应放在客户端支持的覆写层，并明确插入位置。若一个规则指向本地组，而覆写执行顺序晚于规则合并，最终配置中可能暂时出现未定义引用。检查时不要只看某个片段是否存在，而要确认最终文件里策略组已经定义，并且定义发生在内核加载同一份配置的范围内。

06 / RULE ENGINE

规则语法：从上到下匹配，首条命中生效

规则顺序就是实际优先级

rules 是有序列表。连接从第一条开始检查，遇到首条匹配规则后立即采用该规则指定的策略，后续规则不再参与。因此，精确域名和需要特别处理的业务通常放在前面，较宽的域名后缀、IP 网段和地域集合放在中间，MATCH 放在最后接住其余连接。把宽范围规则提前，是“明明写了规则却不生效”的主要原因之一。

规则通常由类型、匹配值和策略名称组成，使用英文逗号分隔。策略名称必须对应已定义策略组、节点或内置策略。部分规则还可以附加选项，例如 IP 规则使用 no-resolve，表示匹配时不为了获得地址而额外触发解析。规则中的逗号属于结构分隔符，包含特殊内容时不能简单依赖 YAML 引号改变 Clash 的规则解析方式。

rules:
  - DOMAIN,api.example.com,节点选择
  - DOMAIN-SUFFIX,example.com,节点选择
  - DOMAIN-KEYWORD,example,节点选择
  - PROCESS-NAME,example.exe,DIRECT
  - DST-PORT,22,DIRECT
  - 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 只匹配完整域名，适合单个接口或主机；DOMAIN-SUFFIX 匹配某个域名及其子域，适合一整个站点体系；DOMAIN-KEYWORD 只要域名中包含指定片段就可能命中，覆盖范围最宽，也最容易误伤。可以用后缀规则时，不应为了省几行改用关键词规则。比如关键词过短，可能匹配到与目标服务无关的域名。

域名匹配依赖内核在连接阶段知道原始主机名。HTTP、TLS 的服务器名称、Fake-IP 映射或嗅探都可能提供域名信息；如果应用直接连接 IP，域名规则自然无法命中。此时需要判断应用本身行为，而不是重复添加同一域名的多种写法。启用流量嗅探可以补充部分连接的域名识别，但它有适用协议和端口边界，也不应取代正确的 DNS 接管。

IP、端口与进程规则

IP-CIDR 和 IP-CIDR6 按目标地址范围匹配，适合局域网、保留地址和明确的服务网段。公共服务的地址可能变化或由多个业务共用，手工维护大量公共 IP 往往不如域名或规则集合稳定。GEOIP 按地址数据库分类，结果依赖本地数据文件；数据过旧时，新分配地址可能落入预期外分类，因此数据库更新属于规则维护的一部分。

DST-PORT 按目标端口匹配，不能区分同一端口上的不同网站。现代 Web 流量大量共用 443 端口，把整个端口交给某个策略通常过宽。进程规则可按程序名或路径匹配，但支持情况与操作系统、运行权限和接管方式相关：网关设备看不到终端上的进程，部分沙盒应用也无法提供完整进程信息。跨平台配置不应把关键分流完全建立在进程规则上。

rule-providers 拆分大型规则集

rule-providers 把规则内容放到本地文件或远端资源中，主规则列表通过 RULE-SET 引用。提供器需要声明行为类型、格式、缓存路径和更新间隔。domain 类型用于域名集合，ipcidr 用于地址网段，classical 可包含多种经典规则。行为类型必须与文件内容匹配，否则即使下载成功，也可能无法按预期解析。

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

  private-ip:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./rules/private-ip.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,private-ip,DIRECT,no-resolve
  - MATCH,节点选择

规则提供器的更新失败不一定会让内核立即停止运行，已有缓存仍可能继续使用。因此“配置加载成功”与“规则已更新”是两件事。排查新增域名未命中时，要检查提供器状态、缓存文件修改时间、下载响应内容以及行为类型。远端资源如果返回网页错误页而不是规则文件，网络请求可能显示成功，但解析阶段仍会失败。

末尾策略体现配置的默认立场。以 MATCH,节点选择 收尾表示未分类流量交给代理选择，以 MATCH,DIRECT 收尾则表示只有明确列出的目标使用代理。两种设计都可以成立，关键是规则库覆盖范围与用户预期一致。修改末尾策略会影响所有未命中连接，应单独验证，而不是把它当作修复某个网站的临时开关。

07 / MERGE LAYERS

覆写与合并：订阅更新后保留本地配置

先识别配置的来源层级

图形客户端中的最终配置通常由多个来源组成：远端订阅提供节点和基础策略，本地覆写修改通用字段或增加规则，客户端自身设置再决定系统代理、TUN、控制端口等运行参数。界面上的“订阅内容”往往只是其中一层。要判断某个字段为什么被改写，必须知道合并顺序以及同名字段发生冲突时采用覆盖、追加还是深度合并。

不同客户端对覆写的命名和能力并不完全相同。有的支持 YAML 片段，有的支持脚本，有的区分前置规则与后置规则。迁移客户端时，不应直接假定旧覆写能够原样执行。Clash Plus 适合作为普通用户的首选图形入口；需要换用其他客户端时，可在下载页按平台比较 Clash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、Surfboard 与归档客户端。

映射覆盖与列表追加不是同一操作

对 mode、log-level、dns.enable 这类单值字段，覆写通常以新值替换旧值。对 rules、proxies、proxy-groups 这类列表，简单覆盖会删除订阅原有内容，简单追加又可能让新规则落在 MATCH 之后永远无法命中。因此列表修改必须明确位置：自定义精确规则一般插到宽范围规则之前，兜底规则始终保留在最后。

映射的深度合并也有边界。若只想增加一个 fake-ip-filter 项，但合并器把整个 dns 对象替换掉，原有 nameserver 和监听字段就会消失。反过来，如果预期完全替换 DNS，而工具执行逐键合并，订阅遗留的策略字段仍会存在。使用覆写前应阅读客户端对对象和数组的处理方式，并通过最终配置确认结果，而不是只看覆写片段本身语法正确。

# 本地覆写片段示意
mode: rule
log-level: info

dns:
  enable: true
  fake-ip-filter:
    - "*.lan"
    - "+.local"

rules:
  - DOMAIN,internal.example,DIRECT
  - DOMAIN-SUFFIX,example.com,节点选择

规则插入位置决定覆写是否有效

假设订阅末尾已有 MATCH,节点选择，本地规则若直接追加到列表尾部，永远不会被执行。正确做法是在兜底规则之前插入，或者由覆写工具提供“前置规则”能力。若订阅包含较宽的 DOMAIN-SUFFIX、GEOIP 或规则集，本地精确例外还要放在这些宽规则之前。规则本身没有显式优先级数字，位置就是优先级。

策略组覆写还要处理成员引用。新增一个名为“开发服务”的组并不够，规则必须指向它，它内部引用的“节点选择”也必须在最终配置中存在。订阅方重命名策略组后，本地覆写可能继续成功合并，却在加载时出现未定义策略。更稳妥的做法是减少对订阅自定义名称的依赖，或在每次订阅结构变化后检查最终引用图。

脚本覆写适合条件修改，但要限制复杂度

脚本可以遍历节点、重建策略组或根据名称插入规则，适合处理订阅每次更新都可能变化的列表。不过脚本也引入新的失败层：字段可能不存在、节点名称可能含特殊字符、客户端升级后输入结构可能变化。脚本应先检查对象类型和数组存在性，避免假定所有订阅都具有同一骨架；发生异常时应保留原配置并输出明确日志，而不是返回半成品。

复杂脚本需要像普通代码一样版本管理和测试。每次修改只解决一类问题，保留输入样例，并对空节点列表、缺少策略组、已有同名规则等边界进行处理。若需求只是修改端口或添加两条规则，YAML 覆写通常比脚本更透明。只有当重复操作确实无法通过声明式片段表达时，再使用脚本。

内核直跑时的合并策略

直接运行 mihomo 时，可以在部署流程中使用模板或配置生成工具完成合并，但生成结果仍应是一份可独立检查的 YAML。服务启动前先生成到临时文件，检查成功后再原子替换正式配置，可避免合并中断留下半份文件。路由器与旁路由环境的目录权限、持久化分区和开机顺序还会影响规则下载与缓存恢复，相关架构可参阅路由器与旁路由部署概览。

08 / VALIDATION

检查与排错：从载入失败到分流异常

先做静态检查，再观察运行日志

配置故障应按层级处理。第一层是 YAML 能否解析，包括缩进、冒号、列表和引号；第二层是 Clash 配置语义能否成立，包括节点类型、必填字段、策略引用和规则格式；第三层才是运行时网络问题，例如 DNS 不通、节点握手失败、系统代理没有启用或透明代理路由缺失。若第一层尚未通过，就没有必要测试节点延迟或修改防火墙。

内核直跑时，可使用配置检查参数验证指定目录中的配置。实际命令中的可执行文件路径和配置目录应按部署位置调整。图形客户端通常也提供配置检查、重新载入或日志入口；如果界面只显示“加载失败”，应打开详细日志定位到具体字段。检查前先保存文件，确认编辑器没有把制表符或不可见字符写入。

mihomo -t -d /path/to/config-directory
mihomo -d /path/to/config-directory

检查命令通过，只表示配置结构可以被内核接受，不表示所有远端节点、DNS 上游和规则提供器都能访问。启动后还应观察提供器更新、DNS 请求、连接拨号和规则命中。日志级别临时设为 debug 可以提供更多上下文，但分析时要围绕一次明确请求，避免在大量后台连接中寻找线索。

载入失败的常见分支

错误指向某一行时，实际原因可能位于上一行，例如漏写引号导致后续内容被错误解析，或上一级缩进已经改变。应从报错行向上检查到最近的顶层字段。出现“找不到策略”一类错误时，搜索规则末尾的名称，再搜索策略组定义，逐字比较空格和符号。出现重复名称时，不仅要检查手写节点，还要考虑提供器展开后是否与静态节点同名。

配置在一个客户端可用、换到另一个客户端后失败，通常与支持字段、内核能力或覆写格式有关。应先导出最小配置，只保留一个基础节点、一个选择组和两条规则，确认目标客户端能载入，再逐区块恢复。不要通过连续删除随机字段碰运气；每轮只改变一个区块，并记录是语法检查、启动还是实际连接阶段出现变化。

连接成功但页面打不开

节点测试成功而网页打不开时，应把 DNS、规则和应用接管分开验证。先用明确指定 mixed-port 的命令访问一个简单地址，确认代理端口工作；再检查浏览器或系统代理是否指向同一地址；随后观察目标域名命中了哪条规则。如果日志完全没有该应用的连接，问题位于接管层；如果有连接但规则不符，问题位于规则或域名识别；如果策略正确但拨号失败，再回到节点和传输层。

部分网站正常、部分网站长时间等待时，要注意 IPv6、UDP、HTTP/3 与 MTU。应用可能优先尝试 IPv6 或 QUIC，失败后才回退到其他路径。TUN 环境中的 MTU 过大也可能让小请求正常而大响应卡住。排查时可以临时关闭单一能力进行对照，但确认原因后应回到网络条件和协议支持上修正，不要长期堆叠互相矛盾的临时开关。

TUN 与透明代理的额外检查

TUN 接管依赖虚拟网卡、路由和权限。桌面系统上，客户端可能需要系统授权才能创建网卡；Linux 上还涉及内核能力、转发设置与策略路由。TUN 已显示开启但应用流量没有进入日志时，应查看默认路由和排除网段，而不是只重启内核。局域网网段、虚拟机网络、容器网络与公司内网通常需要明确直连，否则访问本地服务可能被错误送入代理。

网关透明代理还要防止内核自身流量再次被转发。节点连接、DNS 上游请求和规则下载若重新进入同一透明代理链，会形成回环。常见处理方式是按运行用户、进程标记或路由标记排除，但具体方法取决于 nftables、iptables 和系统路由设计。配置文件只能提供监听端口与 TUN 参数，不能替代操作系统层的完整回环排除。

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

形成可重复的排错记录

有效的排错记录至少包括：当前客户端或内核运行方式、配置来源、故障出现在哪一步、一次请求对应的日志、已验证正常的环节，以及最近改动。分享配置片段前应移除订阅地址、认证信息、控制凭据和节点密码，但保留字段结构、策略名称和规则顺序。只提供“不能用”或整段无关日志，很难判断错误层级。

修复完成后，把临时调高的日志级别、测试规则和绕过项清理掉，再重新载入并复测。对于长期运行的路由器或服务器，还应重启服务验证开机路径、工作目录和缓存权限，避免当前终端会话可用而系统服务失败。局域网共享场景可继续查阅mixed-port 与 allow-lan 设置指南，确认监听地址、防火墙和设备代理参数处于同一条链路。