Clash 配置文件字段参考

YAML 结构总览与加载顺序

顶层映射决定内核读取什么

Clash 配置文件本质上是一份 YAML 文档。最外层通常由若干键值组成：端口与运行参数使用标量，dns 使用嵌套映射，proxies、proxy-groups 与 rules 使用列表。内核启动时先解析 YAML 语法，再校验字段类型和引用关系，最后建立监听端口、DNS 模块、代理出站、策略组与规则树。语法能被解析不代表配置一定可运行，例如策略组引用了不存在的节点，往往要到配置校验阶段才会报错。

YAML 使用缩进表达层级，不使用花括号包围对象。建议统一使用两个空格缩进，禁止在同一文件里混入制表符。冒号后需要空格；列表项以短横线和空格开头。包含冒号、井号、星号、方括号或前后空格的名称应加引号，避免被解析器当作语法符号。节点名称虽然可以使用中文，但策略名和规则目标会反复引用，名称越短越容易检查。

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

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

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

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

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

上例构成一条最小闭环：入站流量进入 mixed-port，域名解析交给 DNS 模块，规则把请求分配给“节点选择”，策略组再选择具体节点或 DIRECT。如果删除 proxy-groups，规则目标就必须直接写节点名或内置动作；如果删除 rules，在 rule 模式下通常无法得到完整的分流行为。实际订阅会包含更多节点，但结构关系仍然相同。

标量、列表与映射的类型不能互换

mode: rule 是标量，不能写成列表；rules 是有顺序的列表，不能改成以规则类型为键的映射；dns 是映射，其中每个子字段都有自己的类型。布尔值建议写成小写 true 或 false，不要用“是”“否”或带引号的字符串代替。端口应写整数，写成 "7890" 有时仍能被兼容处理，但会增加不同客户端之间的差异。

锚点与别名是 YAML 自带能力，例如用 &common 定义公共参数，再用 <<: *common 合并。它可以减少重复，却不适合需要在多个客户端之间同步的订阅配置，因为部分覆写器会在序列化时展开或丢失锚点。面向长期维护的文件，优先显式写出关键字段；只有确认导入链路完整保留 YAML 语义时再使用锚点。

加载路径、订阅文件与运行时配置

图形客户端通常把远程订阅下载到本地配置目录，再将选中的配置交给 mihomo 内核。界面里看到的配置名称、订阅地址和更新时间属于客户端管理层，不一定出现在 YAML 中。内核只处理最终生成的配置文件。某些客户端还会在加载前套用脚本、全局覆写或本地补丁，因此界面导出的文件可能与订阅服务器返回的原文不同。

排查解析失败时，应先区分下载阶段和解析阶段。浏览器能打开订阅地址，只能证明服务器有响应，不能证明响应内容是 YAML；返回登录页、限流提示或 JSON 错误对象时，客户端仍会把它保存下来，随后在首行报语法错误。可按订阅解析失败自查步骤核对响应状态、内容类型、缩进和缓存。若手工编辑，应保留一份原文件，将修改拆成小批次，每次只调整一个结构区段并重新校验。

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

入站端口与局域网访问

port 只提供 HTTP 代理，socks-port 只提供 SOCKS5 代理，mixed-port 则在一个端口上兼容两类连接。桌面客户端通常使用 mixed-port，这样系统代理、浏览器和支持 SOCKS 的工具可以共享同一监听端口。三者不必同时开启；同时配置时必须使用不同端口，否则内核无法绑定监听地址。端口数字本身没有网络加速含义，只要未被占用并与系统代理设置一致即可。

allow-lan 控制是否允许局域网设备连接。设为 false 时，通常只接受本机访问；设为 true 后，还要检查 bind-address、操作系统防火墙和路由器隔离设置。开放局域网监听会扩大可访问范围，应同时设置访问认证或限制防火墙来源，不要把代理端口直接暴露到公网。移动设备借用电脑代理时，填写的是电脑的局域网地址和 Clash 入站端口，不是远程节点服务器地址。

mixed-port: 7890
allow-lan: false
bind-address: "*"
authentication:
  - "local-user:your-password"

mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

只有在确实需要局域网共享时才启用 allow-lan。部分客户端会用界面开关覆盖 YAML 中的值，所以修改后应回到运行状态页确认实际监听地址。若系统代理已开启但浏览器无法连接，可先检查客户端日志是否出现“address already in use”，再检查系统代理端口是否仍指向旧配置。Windows 应用容器还可能受到 UWP 回环限制，这属于系统网络权限，不是规则字段本身的问题。

mode 决定规则是否参与决策

mode 常用值为 rule、global 与 direct。在 rule 模式下，请求依次匹配 rules；在 global 模式下，流量通常交给全局策略组；在 direct 模式下，连接直接建立，不使用普通规则分流。配置调试应优先保持 rule，因为它最接近长期使用状态。临时切到全局模式可以判断某个故障是否由规则造成，但不能据此证明 DNS、节点或系统代理全部正常。

图形客户端中的模式开关经常属于运行时状态。订阅刷新后，客户端可能保留上次选择，也可能重新采用 YAML 的 mode。需要稳定行为时，应同时检查配置文件和客户端的全局覆写设置。规则模式下“某网站走错策略”应查看规则命中记录；全局模式下所有请求都进入同一策略，修改域名规则不会产生效果，这是排查时最常见的上下文遗漏。

日志、IPv6 与并发连接

log-level 控制日志详细程度，常用值包括 silent、error、warning、info 与 debug。日常使用保持 info 即可；定位解析、握手或规则命中问题时临时切换到 debug，排查结束后再恢复，避免大量日志掩盖关键信息。日志中的域名、节点名称和目标地址可能反映访问行为，转发排障截图前应先删去敏感内容。

ipv6 决定内核是否处理 IPv6 相关解析和连接。关闭它不等于操作系统完全禁用 IPv6，只表示 Clash 的对应模块采用受限行为。网络具备稳定 IPv6、代理节点和上游 DNS 也支持时可以开启；若出现部分站点优先取得 AAAA 记录却无法连接，可先对照 DNS 查询结果和节点能力，而不是直接反复切换规则。tcp-concurrent 允许对目标地址进行并发连接尝试，在多地址解析场景中可能缩短等待，但也会增加短时连接数量。

unified-delay 用于让延迟测试更接近统一的计算口径。它影响策略组测试结果的解释，不会把不可用节点变为可用。延迟测试只表示到测试地址的连接情况，真实访问还受到目标站点、协议握手、出口质量和规则路径影响，因此不应只按单次数字排序节点。节点选择的判断方法可参阅延迟、倍率、地区与协议说明。

外部控制器与管理界面

external-controller 暴露内核控制接口，图形客户端通过它读取连接、切换策略和重载配置。常见监听形式是本机地址加端口。若绑定到非本机地址，应配置 secret 并通过防火墙限制来源。external-ui 指向静态管理界面目录，它只负责前端资源，不会自动下载界面文件。普通图形客户端已经包含管理层时，无需另行配置。

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

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

profile.store-selected 用于保存策略组选择，重启后可恢复上次选项；profile.store-fake-ip 用于保存 Fake-IP 映射，减少重启后映射变化带来的影响。实际持久化位置由客户端工作目录决定。配置文件只声明意图，如果客户端每次启动都清理缓存目录，持久化字段也无法保留状态。多设备同步时不建议直接同步整个运行目录，应同步订阅、覆写和明确需要的配置文件，避免把锁文件、缓存和平台路径一起复制。

DNS 字段、Fake-IP 与解析路径

DNS 模块处在连接决策之前

域名请求通常先经过 DNS 解析，再由规则与出站建立连接。Clash 的 DNS 模块不仅负责“把域名变成地址”，还会影响域名规则能否保留、Fake-IP 映射如何建立、不同上游如何分流以及代理节点服务器地址由谁解析。很多“代理已连接但网页打不开”的问题，实际发生在 DNS 上游不可达、返回结果被污染、Fake-IP 过滤不完整或系统请求绕过内核。

dns.enable 开启内置 DNS，listen 定义监听地址。桌面客户端可能通过系统 DNS 劫持、TUN 或本地端口把查询送进该模块。只在 YAML 中开启 DNS，不代表操作系统一定使用它；还需要客户端正确设置系统 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
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.example/dns-query
    - tls://dns.example:853
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver-policy:
    "geosite:cn":
      - 223.5.5.5

default-nameserver 主要用于解析加密 DNS 上游自身的域名，因此通常填写可直接访问的 IP 地址。若这里仍填写域名，就可能形成“需要先解析上游域名才能使用上游，而解析上游域名又依赖该上游”的循环。nameserver 是主要查询上游，可使用 UDP、TCP、DoT 或 DoH 等形式。示例中的 dns.example 是假域名，实际配置必须换成可用服务。

proxy-server-nameserver 专门处理代理节点服务器域名。节点的 server 如果写域名，内核必须先得到它的真实地址才能建立代理连接；若这一步又被送入尚未建立的代理链，会形成依赖环。为该字段指定可直连的解析上游，可以把节点域名解析与普通网站查询分开。节点直接填写 IP 时不经过这一步，但会失去域名切换后端地址的能力。

Fake-IP 模式如何保留域名信息

enhanced-mode: fake-ip 时，内核先向应用返回保留地址段中的映射地址，应用随后连接该地址，内核再通过映射表恢复原始域名并执行规则。这样即使应用只发起 IP 连接，内核仍能按域名规则判断。fake-ip-range 默认应使用专门保留的测试地址范围，不应与真实局域网、企业 VPN 或容器网络重叠。

Fake-IP 不是远程服务器地址，也不会被发送到公网。它是本机内核维护的临时映射。看到系统连接指向 198.18.x.x 并不表示 DNS 解析错误；真正需要检查的是该连接是否被 Clash 接管。如果应用绕过系统代理，同时 TUN 又未接管流量，它会直接尝试连接保留地址，表现为超时。此时应检查接管路径，而不是把所有域名加入过滤列表。

fake-ip-filter 用于让特定域名返回真实地址。局域网服务、网络探测、时间同步、部分游戏或需要本地发现的服务可能不适合使用映射地址。过滤范围应尽量精确，过宽的通配符会让大量域名失去 Fake-IP 带来的域名识别能力。修改后还要清理旧 DNS 缓存或重启相关应用，否则应用可能继续使用先前结果。

dns:
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"
    - "time.*.com"
    - "time.*.gov"

redir-host 与 Fake-IP 的取舍

redir-host 返回真实解析地址，理解路径较直接，对依赖真实 IP 的应用兼容性较好；但在透明代理场景中，内核可能只能看到目标 IP，需要借助嗅探或解析映射恢复域名，域名规则的稳定性取决于接管链路。fake-ip 更适合希望完整保留域名信息的 TUN 场景，但需要处理少量不接受保留地址的程序。选择模式时应根据系统接管方式和应用兼容性决定，不应把它当作节点速度开关。

respect-rules 让 DNS 查询参考现有规则，但它要求解析上游与代理策略之间没有循环依赖。若主要 DoH 上游必须经过代理，而代理节点服务器域名又依赖主要 DoH，就可能无法完成初始连接。解决方向是给节点域名准备独立的直连解析器，或让至少一个基础上游无需代理即可访问。日志中持续出现 DNS timeout 时，应从依赖链最底层开始核对。

nameserver-policy 的分流边界

nameserver-policy 根据域名或 geosite 集合选择解析上游。它决定“去哪里问 DNS”，并不直接决定后续连接使用 DIRECT 还是代理。连接策略仍由 rules 控制。若同一域名在不同上游得到不同地址，解析策略会间接影响连接目标，因此 DNS 分流与规则分流应采用一致的地域意图，避免国内域名由远端上游解析到跨区地址，或代理域名被本地上游返回异常结果。

排查 DNS 时建议分三步：先确认系统查询进入 Clash；再确认 Clash 能访问指定上游；最后确认返回地址和规则命中符合预期。只测试浏览器页面不足以区分缓存、HTTP/3 和系统代理影响。可以暂时关闭浏览器安全 DNS，清除应用缓存，并在内核日志中观察域名查询与连接记录。更完整的联网排查顺序见系统代理、DNS 与规则模式排查清单。

代理节点字段与协议参数

每个节点都需要可引用的唯一名称

proxies 中的每一项表示一个静态出站节点。通用字段包括 name、type、server、port，其余字段由协议决定。name 是策略组和规则引用的标识，同一配置内应保持唯一。名称重复时，客户端可能覆盖前项，也可能在界面显示两个同名选项，后续无法判断规则实际引用哪一个。订阅生成器应在节点名称中保留地区或用途，但不宜塞入过长公告。

server 可以是 IP 或域名，不能附带协议前缀和路径。port 是远端服务端口，不是本机 mixed-port。连接失败时要区分本机入站与远端出站：系统代理连接到本机端口，内核再按节点字段连接服务器。把两组端口混写是手工配置中的常见错误。

proxies:
  - name: "SS-示例"
    type: ss
    server: 192.0.2.20
    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: gateway.example.com
    skip-cert-verify: false
    udp: true

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

示例中的地址和凭据仅用于展示字段关系。Shadowsocks 的 cipher 必须与服务端一致；Trojan 常通过 TLS 建立连接，sni 用于发送服务器名称；VMess 的 uuid、传输方式、TLS 与 WebSocket 参数必须成组对应。单独修改其中一个字段通常不能解决握手失败，反而会让客户端与服务端配置失配。

TLS、SNI 与证书验证

开启 TLS 的协议通常需要区分连接地址、SNI 和 HTTP Host。server 决定连接到哪里，sni 或 servername 决定 TLS 握手声明哪个主机名，WebSocket 的 Host 则属于 HTTP 请求头。三者可能相同，也可能由服务端部署要求设为不同值。出现证书名称不匹配时，应核对服务端证书覆盖的域名和 SNI，而不是直接启用 skip-cert-verify。

skip-cert-verify: true 会跳过证书有效性验证，只适合明确掌握服务端证书情况的临时测试。长期配置应保持 false，并修正系统时间、证书链、SNI 或服务端部署。系统时间错误会让尚未生效或已经过期的判断全部异常，这类错误在日志中通常表现为 TLS 验证失败，与规则或代理组无关。

传输层选项必须按层级嵌套

WebSocket 参数放在 ws-opts，gRPC 参数放在 grpc-opts，HTTP 参数放在对应传输选项中。它们不能与 server 平级后随意改名。YAML 缩进错误可能让 headers 离开 ws-opts，配置仍像文本一样可读，但内核会忽略未知位置的字段或直接拒绝加载。排查时应对照协议文档逐层确认，而不是只比较字段值。

  - name: "VLESS-gRPC-示例"
    type: vless
    server: 192.0.2.40
    port: 443
    uuid: "00000000-0000-4000-8000-000000000001"
    network: grpc
    tls: true
    servername: grpc.example.com
    udp: true
    grpc-opts:
      grpc-service-name: example-service

udp 表示节点是否允许承载 UDP。开启该字段还要求协议、服务端和网络路径都支持 UDP。某个游戏或语音应用无法工作时，不能只看节点配置里是否写了 udp: true，还要确认 TUN 接管、策略组选择、服务端转发和应用自身协议。UDP 故障与 TCP 网页访问正常可以同时存在。

协议字段差异与选择原则

节点字段应来自实际服务端或订阅，不应靠猜测补全。客户端之间的兼容差异常发生在新增协议特性、传输参数命名或内核能力上。遇到“不支持的代理类型”或“未知字段”时，先确认当前客户端使用的内核类型，再检查订阅是否为该客户端生成了合适格式。需要更换客户端时，下载页提供 Clash Plus、Clash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、ClashX Meta、Surfboard 等对应平台入口。

静态节点适合少量手工配置；节点数量较多或需要远程更新时，应使用 proxy-providers。两者可以同时存在，策略组也可以同时引用静态节点和提供器。无论采用哪种来源，最终进入策略组的名称必须能被内核解析，远程文件下载成功也必须具备合法节点结构。

策略组类型、嵌套与健康检查

策略组是规则与节点之间的控制层

proxy-groups 把多个节点、其他策略组以及内置动作组织成可引用目标。规则通常不直接指向某个具体节点，而是指向“节点选择”“自动选择”“流媒体”等策略组。这样节点变化时只需调整组内成员，不必改动大量规则。策略组名称同样区分大小写，并且不能与预期引用名称存在多余空格。

select 是手动选择组，用户在客户端界面中指定一个成员；url-test 定期测试成员并选择测得表现较好的节点；fallback 按顺序寻找可用成员；load-balance 按指定策略在多个成员间分配连接。不同类型解决的问题不同。需要稳定固定出口时使用手动组，不应依赖自动组频繁切换；希望故障时按优先级退回备用节点时，fallback 比单纯选择最低延迟更符合意图。

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

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

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

url 是健康检查目标，应选择稳定、返回内容小且可通过所有候选节点访问的地址。测试成功只能说明节点能访问该目标，不能保证所有网站都可用。interval 是测试间隔，过短会产生不必要的连接，过长则可能在节点失效后迟迟不更新。lazy 启用后，组未被实际使用时可减少主动测试。tolerance 用于避免多个结果接近时频繁切换，不应理解为固定速度差。

组嵌套需要保持单向引用

策略组可以引用另一个策略组，例如“节点选择”包含“自动选择”，“流媒体”再包含“节点选择”。这种嵌套适合建立默认策略和用途策略，但不能形成循环。若 A 包含 B，B 又包含 A，内核无法得到最终出站。设计组关系时可以画成从业务组到基础组再到节点的单向树，任何路径最终都应到达具体节点、DIRECT 或 REJECT。

嵌套层数过多也会增加排查成本。请求命中“流媒体”后，可能由它进入“地区选择”，再进入“自动选择”，最终才到节点。界面只看到最外层选择时，容易误判实际出口。建议基础配置保持三层以内：规则目标组、选择或测试组、具体节点。需要为不同服务固定地区时，可在业务组中直接引用地区组，不必复制节点列表。

filter 与 use 管理提供器节点

策略组通过 use 引用 proxy-providers，通过 filter 按节点名称筛选成员。过滤表达式通常按正则处理，字符需要正确转义。节点名称由订阅提供方决定，可能随更新变化，因此过滤词应覆盖稳定的地区标记，同时避免过宽匹配。例如只写“美”可能同时匹配公告文字，写清常见地区代码与中文名称更稳妥。

proxy-groups:
  - name: "美国节点"
    type: url-test
    use:
      - remote-nodes
    filter: "(?i)美国|US|United States"
    exclude-filter: "测试|过期|到期"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: "业务分流"
    type: select
    proxies:
      - "美国节点"
      - "节点选择"
      - DIRECT

当过滤结果为空时，策略组可能无法使用。订阅刷新后突然出现组内没有节点，应先查看提供器是否更新成功，再检查节点命名是否改变，最后检查正则是否被 YAML 引号和反斜线影响。双引号字符串会处理转义字符，复杂正则可考虑使用单引号，减少反斜线层级。

DIRECT、REJECT 与 PASS 的含义

DIRECT 表示直接连接目标，不经过代理节点；REJECT 表示拒绝连接；PASS 常用于特定规则组合或子规则集，让匹配继续交由后续流程处理。它们是内置动作，不需要在 proxies 中声明。将 DIRECT 放入手动策略组，表示允许用户临时切换为直连；将 REJECT 用于广告或恶意域名规则时，应考虑误拦截后对页面资源的影响。

策略组里是否加入 DIRECT 取决于业务边界。默认代理组加入它便于诊断，但也可能被误选后让敏感流量直连；固定用途组若明确要求代理，可以不提供直连成员。配置设计应让组名反映行为，例如“节点选择”表示允许人工调整，“自动选择”表示由测试决定，“国内直连”表示规则目标而不是节点地区。

自动策略组不是“节点越多越好”。候选成员过多会增加测试流量，质量差异过大时也会让结果抖动。先按地区、用途和协议筛选，再在有限候选中测试，通常更容易得到稳定行为。需要多个设备保持同样策略结构时，可参考多设备配置同步方案，将订阅、覆写与设备专属设置分层保存。

规则语法、优先级与兜底顺序

规则按照声明顺序首次命中

rules 是有序列表。内核从上到下检查，一条规则命中后通常不再继续比较后面的普通规则。因此具体规则应放在前面，宽泛规则放在后面，最终以 MATCH 兜底。规则并不存在“域名规则天然比 IP 规则优先”的全局机制，实际优先级由文件顺序决定。把 MATCH 放在中间，会让它后面的规则全部失去机会。

常见格式是“规则类型,匹配内容,策略目标”，部分规则还有附加参数。逗号是字段分隔符，匹配内容中若需要表达复杂值，应使用对应规则类型或规则提供器，不要随意增加逗号。策略目标必须是已存在的策略组、节点或内置动作。规则本身不会创建策略组。

rules:
  - DOMAIN,api.example.com,节点选择
  - DOMAIN-SUFFIX,example.com,节点选择
  - DOMAIN-KEYWORD,example,节点选择
  - GEOSITE,cn,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 只要域名中包含关键词就可能命中，范围最宽，容易误匹配。能用完整域名时不要使用关键词，能用后缀时也应确认是否需要覆盖根域。比如 DOMAIN-SUFFIX,example.com 会覆盖 example.com 和 www.example.com，更适合整个站点采用同一策略的场景。

IP 规则与 no-resolve

IP-CIDR 用于 IPv4 地址段，IP-CIDR6 用于 IPv6 地址段。请求已有目标 IP 时可以直接匹配；请求仍以域名表示时，内核可能需要先解析才能判断是否落入地址段。附加 no-resolve 表示不要为了该规则主动触发解析，常用于私有地址和已经明确为 IP 的连接，以减少不必要查询。

GEOIP 根据地址数据库判断地区，结果取决于本地数据库内容和更新状态。它适合大范围兜底，不适合要求精确的单个服务。云服务和内容分发网络的地址会变化，同一域名也可能按网络返回不同地区地址，所以服务级规则优先使用域名或维护明确的规则集。IPv6 开启后，还要确认规则是否同时覆盖对应地址族。

进程、端口与网络类型规则

桌面平台可能支持 PROCESS-NAME、PROCESS-PATH 等进程规则，但可用性取决于系统权限、内核运行方式和平台能力。进程名规则适合将某个应用固定到策略组，路径规则更精确，却容易因安装目录变化而失效。移动平台通常无法按桌面方式读取进程路径，因此跨平台配置不应完全依赖进程规则。

DST-PORT、SRC-PORT 等端口规则可以处理特定协议或本地服务，但端口并不等于应用身份。大量现代服务共享 443 端口，使用 DST-PORT,443 做宽泛代理会覆盖几乎全部 HTTPS 流量。端口规则更适合已知服务端口、局域网管理端口或调试场景，并应放在不会遮蔽更具体规则的位置。

rules:
  - PROCESS-NAME,example-client.exe,业务分流
  - DST-PORT,22,DIRECT
  - NETWORK,udp,节点选择
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - MATCH,节点选择

NETWORK,udp 会匹配广泛的 UDP 流量，是否合适取决于节点是否支持 UDP、DNS 是否由独立模块处理以及应用用途。把全部 UDP 强制交给不支持 UDP 的策略，会造成语音、游戏或 QUIC 连接失败。若只是希望特定应用走代理，应优先使用域名、进程或端口组合，而不是一条覆盖所有 UDP 的规则。

规则设计应先写意图再写语法

维护规则前，可以先把需求整理为几层：私有网络直连；明确需要拒绝的域名；必须使用特定地区的业务；常用本地区域直连；其余流量进入默认策略。再将每层翻译为规则，按“例外在前、一般在后”排列。这样比从多个网络配置片段直接拼接更容易发现冲突。

例如某域名整体应直连，但其中一个 API 子域必须代理，应先写完整 API 域名规则，再写整个域名后缀直连。若顺序相反，后缀规则会先命中，例外规则永远不会执行。排查时应在连接日志中查看实际命中的规则类型和目标策略，而不是只搜索文件里是否存在某条规则。

rules:
  - DOMAIN,api.example.com,节点选择
  - DOMAIN-SUFFIX,example.com,DIRECT
  - GEOSITE,private,DIRECT
  - GEOIP,LAN,DIRECT,no-resolve
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

规则数量增加后，重复和冲突很难仅靠肉眼发现。可以把稳定公共规则移入 rule-providers，本地 rules 只保留少量高优先级例外和最终兜底。远程规则集也应检查行为类型和策略目标，不能因为文件来源可信就忽略其覆盖范围。规则更新后若出现网站走错路径，应比较更新前后命中结果，而不是立即更换节点。

代理提供器与规则提供器

proxy-providers 管理远程节点集合

proxy-providers 将节点列表从主配置中拆出。每个提供器通常包含类型、下载地址、本地缓存路径、更新间隔和健康检查。策略组通过 use 引用提供器，而不是把每个节点名逐个写入 proxies。这种结构适合订阅更新，也便于对多个来源分别设置筛选与检查。

type: http 表示从远程地址获取，path 是下载后的本地缓存位置，interval 控制更新间隔。远程文件应是内核支持的代理提供器格式，不能直接把完整 Clash 配置当成纯节点集合。若订阅返回完整配置，需要由客户端订阅管理层导入，或通过可信转换流程生成 provider 文件。

proxy-providers:
  remote-nodes:
    type: http
    url: "https://subscription.example/nodes.yaml?token=xxxx"
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      lazy: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "提供器选择"
    type: select
    use:
      - remote-nodes
    proxies:
      - DIRECT

示例订阅地址使用明显假值。真实订阅通常包含访问凭据，不应写入公开仓库、截图或共享文档。提供器下载失败时，内核可能继续使用本地缓存，因此界面仍能显示旧节点。排查时要同时查看“本次更新是否成功”和“缓存是否仍可读取”，不能仅凭节点列表存在就判断订阅正常。

path 应位于客户端允许写入的配置目录。使用绝对路径会降低跨平台可移植性，Windows、macOS、Linux 与 Android 的目录结构也不同。优先使用客户端工作目录下的相对路径，并保证不同提供器使用不同文件名。多个提供器写入同一路径会互相覆盖，表现为刷新一个来源后另一个来源的节点突然变化。

健康检查属于提供器级可用性观察

提供器的 health-check 会检查节点是否能访问测试地址。它与策略组的 url-test 有关联但目的不同：前者为提供器节点维护可用状态，后者在组内成员之间作选择。两处都设置过短间隔会重复产生大量测试请求。常规配置可以让提供器按较长周期检查，再由需要自动选择的策略组按合理周期测试。

测试地址应稳定且响应轻量。某节点无法访问测试地址，可能是节点故障，也可能是该目标被出口网络限制。若所有节点同时失败，先测试 DNS 和测试地址本身；若仅个别协议失败，再查看握手日志。健康检查不是带宽测试，也不会验证视频、登录或特定地区内容是否可用。

rule-providers 拆分大型规则集

rule-providers 用于加载远程或本地规则集合。常见 behavior 包括 domain、ipcidr 与 classical。domain 集合面向域名条目，ipcidr 面向地址段，classical 可以容纳带类型的经典规则。行为类型必须与文件内容一致，否则会出现解析失败或规则不生效。

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

  service-rules:
    type: http
    behavior: classical
    format: yaml
    url: "https://rules.example/service-rules.yaml"
    path: ./rules/service-rules.yaml
    interval: 86400

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-rules,业务分流
  - MATCH,节点选择

规则提供器只提供匹配集合，使用它时仍需在主配置的 rules 中通过 RULE-SET 指定策略目标。相同规则集可以在不同配置中映射到不同策略组。远程文件更新后，匹配范围可能改变，因此应记录来源用途，并避免将未知的大型集合直接放到最高优先级。

format 需要与远程内容一致。YAML 规则文件常以 payload 列表组织；二进制格式则依赖内核支持和对应扩展。仅修改文件扩展名不会转换内容。下载到的文件如果实际是 HTML 错误页，解析器通常会在开头报错。遇到提供器更新失败，应先查看 HTTP 状态和响应内容，再检查行为类型、格式和本地路径权限。

提供器与主配置的更新边界

主配置控制端口、DNS、策略组结构和最终规则顺序；提供器负责可变的节点集合或规则集合。将稳定结构放在主配置，将频繁变化的数据放在提供器，能降低订阅刷新覆盖本地设置的概率。若所有内容都由远程订阅生成，本地个性化设置应通过覆写层加入，而不是每次刷新后直接修改缓存文件。

多个节点来源可以分别建立提供器，再由策略组组合。需要注意节点同名问题：不同来源可能包含相同显示名称，组内筛选和日志识别会变得困难。可在订阅转换或覆写阶段为来源增加前缀，而不是在规则中依赖同名节点。规则提供器也应避免职责重叠，例如两个大范围域名集分别指向不同策略时，真正行为仍由它们在 rules 中的先后顺序决定。

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

覆写层应修改稳定结构，不直接改订阅缓存

订阅刷新通常会重新下载并替换缓存文件，直接编辑订阅内容容易在下一次更新时丢失。较稳妥的方式是保留远程订阅作为数据源，再使用客户端提供的全局覆写、扩展脚本或本地合并文件修改端口、DNS、策略组和规则。不同客户端对覆写格式支持不同，Clash Plus、Clash Verge Rev、FlClash 等界面中的名称与执行顺序也可能不同，应先确认覆写发生在订阅解析之前还是之后。

覆写可以分为“替换标量”“合并映射”“追加列表”“前置列表”和“删除字段”。标量如 mode 通常直接替换；dns 作为映射可以只改其中几个子字段；rules 是有序列表，简单追加到末尾可能落在 MATCH 之后而失效，因此本地高优先级规则应插入列表前部。策略组列表若按名称合并，需要确认客户端是否支持按对象键识别，否则可能产生两个同名策略组。

# base.yaml
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
rules:
  - GEOSITE,cn,DIRECT
  - MATCH,节点选择

# override.yaml 的目标语义
dns:
  ipv6: false
  fake-ip-filter:
    - "*.lan"
    - "*.local"

# 需要前置到 MATCH 之前的本地规则
rules-prepend:
  - DOMAIN,api.example.com,业务分流
  - DOMAIN-SUFFIX,internal.example,DIRECT

rules-prepend 是覆写工具可能采用的语义示例，并非所有内核直接识别的顶层字段。最终送给 mihomo 的文件仍应展开为标准 rules 列表。使用某客户端的扩展字段时，应把它留在客户端覆写文件中，不要复制到准备直接交给内核的配置里。判断一个字段属于客户端还是内核，可以查看导出的最终配置和启动日志。

合并列表时必须明确顺序与去重方式

规则列表合并最重要的是顺序。建议把本地强制规则放在远程规则之前，把补充规则放在区域规则之前，把最终兜底保留在唯一末尾。合并后应检查是否存在多个 MATCH、是否把私有网络规则放到代理兜底之后、是否有同一域名被更早的宽泛规则覆盖。规则文本重复不一定造成启动错误，但会增加匹配和维护成本。

策略组与节点列表的去重不能只比较整行文本。节点对象可能名称相同但服务器不同，也可能服务器相同却名称不同。普通手工维护应以唯一名称为第一约束，再核对协议、服务器和端口。策略组同名通常比节点同名更危险，因为规则只按组名引用，重复定义的处理方式可能随解析器或客户端而变化。

DNS 映射合并时，特别注意列表字段是替换还是追加。若覆写器把 nameserver 完全替换，基础配置中的备用上游会消失；若把 fake-ip-filter 追加，则通常符合补充过滤的意图。不能只看覆写片段本身，必须检查合并后的最终 YAML。图形客户端若提供“查看运行配置”或“导出当前配置”，应以该结果作为校验对象。

配置校验应按四个层级进行

第一层是 YAML 语法：缩进、冒号、引号、列表和数据类型必须正确。第二层是字段校验：内核是否识别字段，协议必需参数是否齐全。第三层是引用关系：规则目标、策略组成员、提供器名称和本地路径是否存在。第四层是运行行为：端口能否监听、DNS 能否访问上游、节点能否握手、规则是否命中预期策略。四层应按顺序检查，前一层未通过时，后续网络测试没有意义。

# 使用客户端内置校验功能时，以实际内核路径和配置路径为准
mihomo -t -f config.yaml

# 若配置通过，输出通常会表明配置测试完成
# 若失败，重点记录报错行号、字段名和引用名称

命令行中的可执行文件名和参数取决于实际安装方式，图形客户端通常已经提供配置检查入口。测试时应使用与客户端一致的 mihomo 内核，避免一个内核接受字段、另一个内核不支持。报错行号指向解析器发现问题的位置，不一定是根因位置，例如上一行缺少引号，错误可能在下一行才暴露。

修改配置后，不要一次性重写多个章节。建议采用二分式定位：先恢复到可运行版本，再逐块加入 DNS、节点、策略组和规则；某块触发错误后，再继续缩小到具体字段。远程提供器可暂时替换为一两个静态示例节点，以判断问题位于下载链路还是策略结构。排查结束后再恢复完整来源。

常见错误的定位路径

若配置能启动但无法上网，应先验证不经过 Clash 时基础网络是否正常，再验证本机入站端口，随后检查 DNS、策略组、节点握手和规则命中。不要一开始就删除全部规则或关闭所有安全设置，这会破坏故障现场。日志中保留首次失败的时间点，并对照当时选择的模式和策略组，通常比反复重启更有效。

如果只有浏览器异常，检查浏览器是否启用了独立安全 DNS、代理扩展或 QUIC；如果所有应用都异常，检查系统代理或 TUN；如果局域网设备异常而本机正常，检查监听范围和防火墙；如果某个策略组异常而其他组正常，检查组内成员和健康检查。不同范围对应不同配置层级，先界定范围可以避免无关修改。

形成可维护配置的最终检查表

完成配置后，确认顶层字段只有一份有效定义；端口互不冲突；DNS 上游存在基础解析路径；每个节点名称唯一；策略组引用形成单向关系；所有规则目标存在；MATCH 只在末尾出现一次；提供器缓存路径互不覆盖；本地覆写不包含订阅凭据的公开副本；最终运行配置可以通过当前内核校验。随后分别测试直连域名、代理域名、IP 目标和 UDP 应用，确认不是只在单一网页上偶然成功。

配置文件应与订阅来源、覆写文件和运行状态分开备份。需要跨设备复用时，先移除平台专属路径和控制端口，再为每台设备保留独立的系统接管设置。远程订阅负责节点变化，本地覆写负责稳定偏好，客户端运行目录负责缓存与选择状态。分清三者后，订阅更新、客户端升级和设备迁移就不会互相覆盖。

遇到无法归类的问题，可转到帮助中心按基础认知、安装配置、使用技巧和故障排查继续查找。若需要从安装到首次连接重新建立可工作的基线，返回入门指南逐步执行；若需要重新选择客户端或内核安装包，前往安装包页面按平台查看。排障时始终先保存当前配置，再进行可回退的小范围修改。