CONFIG FILE REFERENCE

Clash 配置字段

按 YAML 的依赖关系查阅端口、DNS、代理节点、策略组、规则与覆写。示例采用可直接检查的结构，具体服务器参数仍应以订阅服务提供的配置为准。

YAML 加载顺序 通用字段与 DNS 代理与策略组 规则与覆写

SECTION SELECTOR

章节目录

CHAPTER 01 / INPUT

YAML 结构总览与加载关系

Clash 配置文件是一个 YAML 文档。它不是按行执行的脚本，而是一组经过解析后交给内核的键值、列表和对象。顶层字段决定监听端口、运行模式、DNS 行为与控制接口；代理节点放在 proxies 或由 proxy-providers 引入；策略组通过名称引用节点和其他策略组；规则列表再把域名、IP、进程或网络类型送入指定策略。阅读配置时，应先确认对象是否存在，再确认引用名称是否完全一致，最后检查规则顺序。只盯着某一条规则，很容易忽略它引用的策略组根本没有加载。

YAML 依靠缩进表达层级。推荐统一使用两个空格，不使用制表符。列表项以前导短横线表示，短横线之后仍要保留一个空格。冒号用于分隔键和值，冒号后通常也要有空格。包含冒号、井号、方括号或特殊布尔字样的名称，适合使用引号包裹。注释从 # 开始，只用于说明，不会传递给内核。缩进正确但字段放错层级时，解析器可能不会在期望位置读取该字段，因此“文件能打开”不等于“字段已经生效”。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: 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: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

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

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

上面的最小结构展示了完整引用链：rules 中的“节点选择”必须与 proxy-groups 的名称逐字相同；策略组中的“示例节点”又必须与 proxies 中的节点名称一致。名称区分字符、空格和全角半角符号。复制配置片段时，如果只复制规则而漏掉策略组，或者只复制策略组而漏掉节点，最终都会形成悬空引用。某些客户端会在导入阶段给出提示，另一些客户端只在启动内核时记录错误，因此查看客户端日志是必要步骤。

顶层字段的推荐排列

YAML 规范不要求固定的顶层顺序，但为了维护，建议按“运行入口、DNS、节点来源、节点、策略组、规则来源、规则”排列。这样的顺序与数据依赖接近：先决定流量如何进入内核，再决定域名如何解析，然后准备可用出口，最后执行匹配。订阅生成器可能采用不同顺序，只要缩进和引用正确，通常不影响结果。人工维护时保持稳定顺序，可以减少合并时的误删，也便于比较更新前后的差异。

层级 常见字段 检查重点
运行入口 mixed-port、mode、allow-lan 端口冲突、监听范围、模式是否符合预期
解析层 dns、hosts 增强模式、上游地址、排除域名
出口层 proxies、proxy-providers 节点名称、协议参数、来源更新
决策层 proxy-groups、rules 引用关系、匹配顺序、最终兜底

从订阅导入的配置通常会被客户端保存为本地副本。直接编辑副本虽然便于测试，但下一次订阅更新可能重新生成文件。需要长期保留的本地规则，应放入客户端支持的覆写、合并或脚本入口，而不是依赖修改缓存文件。若当前目标只是完成首次连接，应先按快速上手流程验证订阅可用，再回到本页调整结构。这样可以把“订阅本身不可用”和“自定义字段写错”分开处理。

CHAPTER 02 / RUNTIME

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

通用字段决定内核如何接收应用流量以及如何暴露管理能力。桌面客户端通常会在图形界面中管理这些值，但配置文件仍是最终参考。最常见的入口是 mixed-port，它在同一个端口上接收 HTTP 与 SOCKS5 代理请求，适合系统代理和手动填写代理地址的应用。旧配置也可能分别使用 port 与 socks-port。如果同时定义多个入口，要确认端口号没有重复，也没有被其他程序占用。

mixed-port: 7890
redir-port: 7892
tproxy-port: 7893

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

redir-port 和 tproxy-port 主要用于透明代理场景，通常由路由规则、网关脚本或特定客户端自动接入。普通桌面系统只使用系统代理时，不需要为了字段齐全而强行开启。TUN 模式也有自己的流量入口和路由过程，不能仅靠增加一个监听端口完成。需要比较系统代理与 TUN 的覆盖范围，可阅读TUN 模式和系统代理区别，再根据应用是否读取系统代理决定接管方式。

运行模式与规则行为

mode 常见值为 rule、global 和 direct。规则模式按照 rules 从上到下匹配，是日常使用的主要方式；全局模式把流量交给全局策略选择，适合临时测试节点是否可用；直连模式绕过代理出口，适合排除本地网络问题。模式切换不会改写规则内容，只会改变决策入口。排错时可短暂切到全局模式：如果全局模式可以访问，而规则模式失败，重点检查规则命中和策略组；如果全局模式也失败，则应先检查节点、协议参数和系统接管状态。

allow-lan 控制局域网设备是否可以访问本机监听端口。设置为 true 后，还要结合 bind-address、操作系统防火墙和局域网地址使用。开放监听意味着同一网络中的设备可能向该端口发送请求，因此只应在明确需要共享代理时开启，并为控制接口配置访问限制。仅在本机使用时保留 false 更容易维护。若客户端界面提供“允许局域网连接”开关，应避免同时在多个覆写层反复设置，以免界面显示与最终配置不一致。

控制接口与配置存储

external-controller: 127.0.0.1:9090
secret: "your-dashboard-password"
external-ui: dashboard
profile:
  store-selected: true
  store-fake-ip: true

external-controller 提供控制 API，图形客户端和面板可通过它读取策略组、切换节点或重载配置。本机管理时绑定 127.0.0.1 即可。若绑定到所有网络接口，必须同步考虑访问控制、防火墙和实际使用环境。secret 用于控制接口鉴权，示例值应替换为本地自定内容。external-ui 指向面板静态文件目录，它不是网络节点来源，也不会改变代理规则。

profile.store-selected 用于保存策略组选择，使内核重启后可以恢复上次选择。store-fake-ip 用于保存 Fake-IP 映射，减少重启后映射变化带来的影响。是否由客户端接管这些字段取决于客户端实现；图形客户端可能把状态写入自身数据库，而不是同一份 YAML。遇到“修改后重启又恢复”的情况，应先判断字段来自订阅、覆写还是客户端偏好设置，不能只重复编辑同一个缓存文件。

端口占用检查

内核启动失败并提示地址已被使用时，先关闭重复启动的客户端实例，再检查同一配置中是否让多个监听字段使用了相同端口。改变端口后，还要同步更新系统代理或应用内手动代理设置。

log-level 常用于控制日志详细程度。日常运行可使用 info；排查规则命中、DNS 请求或连接建立过程时，可以临时提高日志详细度，完成后再恢复，避免大量记录遮住关键错误。ipv6 决定内核相关功能是否处理 IPv6，但它不能单独保证本地网络具备可用的 IPv6 路由。开启后出现连接等待时，应分别检查本地网络、DNS 返回和规则覆盖，避免把所有问题归因于单一开关。

CHAPTER 03 / RESOLUTION

DNS 字段：上游解析、Fake-IP 与回退规则

Clash 的 DNS 模块位于域名请求与规则匹配之间。它可以接收本机或 TUN 接管的 DNS 查询，再按配置选择上游服务器。DNS 配置的目标不是简单堆叠地址，而是明确三个问题：查询从哪里进入、使用哪组上游、解析结果怎样配合规则。系统代理模式下，部分应用仍可能直接使用系统 DNS；TUN 模式配合 DNS 劫持时，覆盖范围通常更完整。若浏览器可用而其他应用解析失败，应先确认该应用的 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"
    - "*.local"
    - "time.*.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
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query

enable 控制内置 DNS 是否启用，listen 指定监听地址。监听到 0.0.0.0 时会涉及局域网访问范围，应结合实际网络环境处理；只供本机使用时，可采用本地回环地址或由客户端自动配置。default-nameserver 通常使用可直接访问的 IP 地址，用于解析 DoH 上游自身域名等基础任务。它不是全部查询的主要出口。常规域名查询主要交给 nameserver，代理服务器域名可由 proxy-server-nameserver 单独解析，避免建立代理连接前出现循环依赖。

Fake-IP 与 Redir-Host 的处理差异

enhanced-mode: fake-ip 会为域名返回保留地址段中的映射地址。应用随后连接该地址时，内核根据映射恢复原域名，再执行域名规则和代理决策。这个过程有利于保留域名信息，也便于 TUN 场景统一处理。fake-ip-range 应使用专门的保留网段，不应改成局域网正在使用的地址范围。映射地址不是远程服务器的真实地址，因此使用抓包工具观察连接时，看到保留地址属于正常现象。

部分局域网设备发现、时间同步、游戏或依赖真实地址返回的应用不适合 Fake-IP。此时可将相关域名加入 fake-ip-filter，让它们使用真实解析结果。过滤项应尽量具体，先从确认异常的域名开始，不要直接加入过宽的顶级匹配，否则会削弱域名规则的可见性。关于映射流程和排除场景，可继续阅读Clash Fake-IP 模式原理。

redir-host 更接近传统解析流程，内核取得真实 IP 后再处理连接。它对依赖真实地址的程序较直观，但域名信息可能在后续 IP 连接阶段丢失，规则匹配会更多依赖解析缓存或嗅探。两种模式没有适用于所有网络的固定答案。普通网页访问、TUN 全局接管和大量域名规则通常适合先测试 Fake-IP；存在局域网服务、特殊游戏或企业内网域名时，应逐项补充过滤，而不是立刻改动整个 DNS 架构。

回退、策略与分流解析

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    domain:
      - "+.example.net"
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

fallback 与 fallback-filter 用于按照条件选择备用结果。配置时需要理解客户端所用内核对并发查询、结果过滤和 Geo 数据的处理方式，不能把“填写了备用地址”理解为所有失败都会自动按固定顺序重试。nameserver-policy 可按域名或规则集合指定解析服务器，适合内外网络、家庭域名和工作域名需要不同解析路径的情况。策略键引用 geosite 时，本地 Geo 数据必须可读取，否则对应匹配无法按预期工作。

DNS 排错顺序

先确认内置 DNS 已监听，再确认查询确实进入该端口；随后检查上游域名能否通过基础 DNS 解析，最后核对 Fake-IP 过滤和规则命中。只更换上游地址，无法修复监听、劫持或路由层的问题。

常见故障可以按现象分支处理：所有域名失败但直接访问 IP 正常，重点检查监听和上游；只有代理节点域名失败，检查 proxy-server-nameserver 与基础解析；局域网名称失败，检查搜索域、hosts 和 Fake-IP 排除；规则命中与预期不同，检查是否保留域名信息以及 Geo 数据是否加载。修改后应重载配置并查看日志，不要同时改动增强模式、上游地址和 TUN 劫持三个层面，否则难以判断哪一项真正生效。

CHAPTER 04 / ENDPOINTS

代理节点字段：名称、协议参数与传输层

proxies 是代理节点对象列表。每个对象至少需要名称、协议类型、服务器地址、端口以及对应协议的认证参数。节点名称不仅用于显示，还会被策略组引用，因此必须保持唯一。服务器可以是域名或 IP；使用域名时，建立连接前需要完成 DNS 解析。端口必须是服务端实际监听端口，不能与本机代理入口端口混淆。订阅生成的节点参数通常已经成套给出，人工修改某一个字段可能破坏服务端与客户端的协商。

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

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

Shadowsocks 节点使用 cipher 与 password。加密方式必须与服务端一致，字段拼写和大小写也要符合内核支持范围。Trojan 节点通常通过 TLS 建立连接，sni 用于指定握手中的服务器名称。skip-cert-verify 设为 false 时会执行证书验证，正常公开证书场景应保留验证。若证书名称与连接域名不一致，应先核对服务端配置和订阅内容，而不是把关闭验证作为长期修复办法。

VMess、WebSocket 与 TLS

proxies:
  - name: "VMess WS 示例"
    type: vmess
    server: proxy.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: proxy.example.com
    network: ws
    ws-opts:
      path: /service
      headers:
        Host: proxy.example.com

VMess 的 uuid、alterId、传输网络和 TLS 参数必须与服务端匹配。WebSocket 配置放在 ws-opts 下，路径和 Host 头属于传输层协商内容。字段缩进错到节点对象外时，YAML 仍可能解析，但内核不会把它当成该节点的 WebSocket 参数。使用 gRPC、HTTP 或其他传输时，应改用对应选项，不能保留无关的 ws-opts 期待自动转换。

TLS 相关字段在不同协议对象中可能使用 sni 或 servername。复制片段前应对照当前内核支持的字段，不要仅按字段名字相近进行替换。服务端地址、TLS 服务器名称和 HTTP Host 可以相同，也可能承担不同作用：服务器地址决定连接目标；SNI 参与 TLS 握手；Host 头由应用层传输使用。排查握手失败时，应分别检查这三层，而不是只测试域名能否解析。

UDP、接口与链式出口

udp: true 表示节点允许处理 UDP，但最终是否可用还取决于协议、服务端和本地接管方式。应用发出 UDP 请求不代表系统代理会自动接管；很多系统代理设置主要覆盖 TCP。TUN 或透明代理场景更容易统一处理 UDP，但也需要正确的路由和 DNS 配置。游戏、语音或 QUIC 连接异常时，应先确认流量是否进入内核，再判断节点是否支持，不能仅凭节点对象中的布尔值下结论。

interface-name、routing-mark 等字段用于约束出口接口或配合系统路由，主要出现在多网卡、服务器和路由器环境。配置错误可能让代理连接再次进入代理入口，形成循环。链式代理可通过 dialer-proxy 等机制指定拨号出口，但被引用的节点或策略组必须先存在，而且要防止互相引用。普通客户端配置没有明确链路需求时，不建议增加这些字段。

字段组 决定内容 常见错误
基础连接 server、port、type 地址不可解析、端口与服务端不一致
认证参数 password、uuid、cipher 复制不完整、协议字段混用
TLS 层 sni、servername、证书验证 名称不匹配、用关闭验证掩盖配置问题
传输层 network、ws-opts 等 路径错误、选项缩进到错误层级

订阅导入后不应通过猜测修改协议参数。先执行客户端提供的配置更新，再检查节点名称是否进入策略组。节点列表为空时，问题通常发生在订阅拉取、格式转换或提供者加载阶段；节点存在但连接失败时，再检查协议参数、DNS 和系统时间。客户端下载与平台差异可在客户端下载页核对，停更客户端迁移可参考配置转移步骤。

CHAPTER 05 / POLICY

策略组字段：手动选择、自动测试与故障转移

proxy-groups 把节点、内置出口和其他策略组组织成可被规则引用的决策对象。规则通常不直接写某个节点名，而是写策略组名，这样订阅更新或节点变化时不必重写全部规则。常见内置出口包括 DIRECT 和 REJECT。前者直接连接目标，后者终止匹配流量。策略组名称同样需要唯一；如果名称与节点重复，阅读和维护都会变得困难，建议使用“节点选择”“自动选择”“故障转移”等能表达用途的名称。

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

  - name: "自动选择"
    type: url-test
    proxies:
      - "SS 示例"
      - "Trojan 示例"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "故障转移"
    type: fallback
    proxies:
      - "SS 示例"
      - "Trojan 示例"
    url: https://www.gstatic.com/generate_204
    interval: 300

Select、URL-Test 与 Fallback

select 用于手动选择。它适合作为顶层入口，让用户在自动组、故障组、单个节点和直连之间明确切换。url-test 会按照测试地址检查候选项，并依据测试结果选择。测试结果只反映到指定 URL 的连接表现，不等同于所有网站、所有协议和所有时间段的体验。tolerance 用于减少候选项在结果接近时频繁切换，数值单位及具体处理由内核实现决定。

fallback 按列表顺序选择可用项，当前项不可用时再切换到后续项，适合出口优先级明确的场景。load-balance 用于把连接分配到多个候选项，但需要考虑会话一致性：登录、支付或依赖固定出口的服务可能不适合在不同连接间改变出口。自动测试和负载分配都不是“节点越多越好”，候选项过多会增加检测请求和维护成本。应先按地区、用途或协议筛选，再建立规模可控的策略组。

使用代理提供者填充策略组

proxy-providers:
  airport:
    type: http
    url: "https://example.com/api/v1/client/subscribe?token=xxxx"
    path: ./providers/airport.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "提供者节点"
    type: select
    use:
      - airport

proxy-providers 将远程节点集合保存为本地提供者文件。type: http 表示通过地址更新，path 指定本地缓存位置，interval 指定周期更新间隔。示例订阅地址使用明显的测试值，实际地址应从订阅服务复制，并避免在公开文档或截图中暴露。health-check 用于提供者级可用性检查，它与策略组自己的测试机制可以同时存在，但两者间隔过短会产生重复检测。

策略组通过 use 引用提供者，通过 proxies 引用静态节点或其他组。两种来源可以按内核支持方式组合，但维护时应明确节点来自哪里。订阅更新后节点名称改变时，直接写在 proxies 中的旧名称可能失效；使用提供者引用则更适合动态集合。需要进一步筛选时，可在支持的内核中使用 filter 或排除表达式，根据节点名称建立地区组。表达式应先对少量名称测试，避免因为命名规则变化得到空组。

策略组的依赖方向

策略组可以引用其他策略组，但依赖必须保持单向。例如“节点选择”引用“自动选择”是合理结构；如果“自动选择”又回头引用“节点选择”，就会形成循环。设计策略层时，可以从底向上排列：底层是静态节点和提供者，中层是地区筛选与自动测试，顶层是供规则引用的用途组。媒体、工作、下载等用途组再引用顶层出口，而不要让底层测速组引用业务组。

策略组为空时

先检查 use 中的提供者名称，再检查提供者文件是否成功更新；使用名称筛选时，临时移除筛选表达式确认原始节点是否存在。空组通常不是规则问题，规则只会把请求送到已经定义的策略组。

interval 是秒级周期配置时，应根据实际需要设置，不必追求高频。节点订阅更新、健康检查和策略测试是三类不同操作：订阅更新改变候选集合；健康检查判断节点是否可连接；策略测试在候选项之间做选择。排错时分别手动触发，并观察哪一步失败。客户端界面若同时提供自动更新周期，应确认它是在更新整份配置还是更新提供者，避免多个定时器重复请求。

CHAPTER 06 / MATCHING

规则语法、匹配顺序与规则集

rules 是有序列表。连接从第一条开始向下检查，命中后立即使用该条指定的策略，后续规则不再处理同一连接。因此规则的关键不只是内容，还包括位置。具体域名、进程或网段通常放在前面，范围较大的 Geo 规则放在后面，最终使用 MATCH 兜底。把宽泛规则放得过早，会让下面的精确规则永远没有机会命中。

rules:
  - DOMAIN,api.example.com,节点选择
  - DOMAIN-SUFFIX,example.org,节点选择
  - DOMAIN-KEYWORD,example,节点选择
  - 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 按关键词匹配，范围更宽，容易误伤包含相同字符串的其他域名。能使用精确域名或后缀时，不应优先使用关键词。域名规则依赖连接过程中可获得域名信息。若应用直接连接 IP，或者 DNS 处理没有保留域名，匹配可能转到 IP 类规则。

IP、端口、进程与网络类型

IP-CIDR 用于 IPv4 网段，IPv6 使用对应的 IPv6 规则类型。局域网保留地址通常应在 GeoIP 之前直连。no-resolve 表示匹配该 IP 规则时不为了取得 IP 主动触发域名解析，可用于避免额外查询和规则阶段循环，但是否适合要看规则类型和实际流量。使用 CIDR 时应确认前缀长度，过宽网段可能覆盖并非预期的地址。

rules:
  - PROCESS-NAME,example-app.exe,DIRECT
  - DST-PORT,22,节点选择
  - NETWORK,udp,自动选择
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,节点选择

进程规则依赖操作系统权限和客户端内核能力，不同平台取得进程名的方式并不完全一致。Windows 常见可执行文件名，macOS 和 Linux 可能按进程名或路径提供信息；移动平台通常不能按桌面方式识别所有应用。端口规则只反映目标端口，不能证明流量用途。大量服务使用共享端口，仅凭端口分流可能覆盖过宽。NETWORK 可区分 TCP 与 UDP，但它更适合作为特定需求的补充，不应替代域名和 IP 规则。

Rule Provider 与行为类型

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

  private-networks:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-networks.yaml
    url: https://example.com/rules/private-networks.yaml
    interval: 86400

rules:
  - RULE-SET,direct-domains,DIRECT
  - RULE-SET,private-networks,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

rule-providers 把大规模规则拆到独立文件。behavior: domain 表示内容按域名类载荷解释，ipcidr 用于网段，部分内核还支持更通用的规则集合行为。行为类型必须与远程文件内容一致。域名列表不能标成 IP 网段行为，经典规则文本也不能直接当成纯域名载荷。format 则描述文件格式，更新失败时要同时检查网络访问、文件格式、保存路径和解析日志。

规则集更新周期与订阅更新相互独立。节点订阅更新不会自动保证外部规则集已经刷新，规则集刷新也不会改变节点。GeoIP、GeoSite 和外部规则集属于不同数据来源。遇到地区规则过旧时，应确认客户端使用的数据文件位置和更新功能，避免只更新订阅。关于 Geo 数据加载问题，可以在帮助中心继续按错误现象查找。

建立可解释的规则顺序

推荐按“本机与局域网、人工精确规则、业务规则集、地区规则、最终兜底”排列。每个区段前可以写注释，说明规则来源和用途。人工规则数量少时直接写在主配置中便于检查；数量多且需要独立更新时再使用规则提供者。不要把多个来源的规则机械拼接后直接投入使用，应检查是否存在重复项、相反策略和过宽关键词。

规则没有生效

先从连接日志确认实际命中的规则，再向上查找是否有更早的宽泛规则截获。若日志只显示 IP，检查 DNS 模式、嗅探与应用连接方式；若策略名称不存在，则回到策略组引用关系处理。

测试规则时一次只修改一个区段。可先加入一条精确域名规则并置于列表前部，重载后访问对应域名，通过日志确认命中。确认语法和策略组有效后，再逐渐扩大到后缀或规则集。直接切换全局模式只能验证节点链路，不能证明规则正确。完成测试后应恢复规则模式，并检查最终 MATCH 指向是否符合预期。

CHAPTER 07 / MAINTENANCE

覆写、合并、自动更新与配置排错

订阅配置会随远程内容更新，本地修改要放在稳定的自定义层。常见客户端提供覆写、合并、扩展脚本或配置片段功能，但不同客户端对数组和对象的处理方式可能不同。对象字段通常可以按键覆盖，例如把 mode 改成 rule，或为 dns 补充子字段；数组字段则可能整体替换、追加到前后，或按照客户端定义的语法处理。rules、proxies 和 proxy-groups 都是数组，错误地整体覆盖会让订阅原有内容消失。

配置维护应先区分四个来源：远程订阅原文、客户端生成的运行配置、本地覆写片段、客户端自身偏好。界面中看到的最终状态可能是四者合并结果。排查时应找到客户端提供的“查看运行配置”或日志输出，而不是只打开下载下来的订阅文件。若更新订阅后自定义规则消失，说明修改落在了远程副本或缓存层；若界面改动后 YAML 没变化，说明该项可能存储在客户端设置中。

对象覆写与数组追加

# 通用覆写示意，实际入口以客户端支持方式为准
mode: rule
log-level: info

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

上面的对象结构适合表达最终目标，但不能说明某个客户端如何合并数组。例如 fake-ip-filter 如果采用替换语义，写入两项后会覆盖订阅原列表；如果采用追加语义，则会保留原列表并增加两项。使用前应在客户端文档或运行配置中确认。规则数组尤其要关注插入位置：需要优先匹配的本地规则必须进入远程规则之前；仅追加到 MATCH 之后不会生效，因为流量已在兜底规则处结束。

策略组也存在同样问题。为了给“节点选择”增加一个本地组，不应复制整份远程策略组列表长期维护，因为订阅更新后新增组不会自动进入副本。更稳妥的方式是使用客户端提供的组级覆写、脚本处理或提供者引用，在最终配置中只改变目标组。客户端不支持细粒度合并时，可以减少自定义范围，或者把长期规则放到独立规则提供者中。

自动更新的三个层次

自动更新至少包括整份订阅、代理提供者和规则提供者三个层次。整份订阅更新通常由客户端调度，更新后重新生成完整配置；proxy-providers.interval 更新节点集合；rule-providers.interval 更新规则集合。三者不应混为一个开关。订阅地址发生变化时，只刷新规则提供者不会得到新节点；规则集过旧时，只刷新节点订阅也不会改变规则数据。

设置周期时要考虑内容变化频率和客户端运行方式。桌面客户端长期关闭时，定时器无法在后台执行，重新启动后应手动检查更新时间。更新成功还不等于运行配置已经重载，部分客户端会自动应用，部分客户端需要手动切换或重载。可靠的操作顺序是：执行更新、确认来源状态、重载最终配置、查看策略组是否保留选择、再进行访问测试。

建议保留的检查基线

保存一份能够正常启动的最小配置。每次只增加一个功能块，重载后检查日志。出现问题时回退到上一个可用状态，比同时修改 DNS、TUN、策略组和规则更容易定位。

从解析错误到连接错误的排查链

第一层是 YAML 解析。常见提示包括缩进错误、冒号后缺少空格、引号未闭合、列表层级错误和重复键。处理时查看错误行上下数行，因为真正的结构错误可能发生在提示行之前。包含特殊字符的值可先加引号；从网页复制的弯引号和全角标点应改为普通 YAML 字符。解析通过后，再进入字段校验，检查类型是否正确，例如端口应为数字、布尔值应为 true 或 false。

第二层是引用校验。逐项确认规则目标存在于策略组或内置出口中，策略组成员存在于节点、提供者或其他组中，规则提供者名称与 RULE-SET 引用一致。名称中的空格最难观察，可临时复制名称进行搜索。第三层是资源加载，检查订阅、代理提供者、规则提供者和 Geo 数据是否可读取。网络更新失败时保留的旧缓存可能让内核继续启动，因此要同时看更新时间和日志。

第四层是连接建立。节点超时先检查服务器解析、目标端口、本地网络和协议参数；TLS 握手失败检查系统时间、服务器名称与证书；只有 UDP 异常时检查接管方式和节点能力；只有特定域名异常时回到 DNS 与规则命中。第五层是系统流量入口：浏览器设置、系统代理、TUN 路由和应用自身代理必须与当前方案一致。配置文件完全正确，但系统流量没有进入内核时，访问结果仍不会变化。

现象 优先检查 下一步
配置无法加载 缩进、引号、字段类型、重复键 缩减到最小配置后逐段恢复
策略组为空 节点来源、use、筛选表达式 检查提供者日志与缓存文件
规则模式异常 实际命中项、规则顺序、策略名称 用精确域名规则做单项测试
域名失败而 IP 可用 DNS 监听、上游解析、Fake-IP 确认查询是否进入内核
更新后自定义内容消失 修改位置、数组合并语义 迁移到客户端覆写或规则提供者

完成修改后，应保留一条可重复的验证路径：重载配置，确认内核启动；更新提供者，确认节点与规则集可读取；检查策略组选择；访问一个应直连的域名和一个应走代理的域名；最后查看日志中的命中结果。若问题仍无法归类，可前往帮助中心按安装配置、使用技巧和故障排查分类继续检查。需要重新理解整份 YAML 的加载顺序，可阅读配置文件 YAML 结构解析；需要重新完成基础导入，则返回入门指南，不要在尚未验证订阅可用时叠加更多覆写。