Clash 配置字段

YAML 结构与配置边界

结论：配置文件描述的是一组相互引用的对象，不是可以任意排列的设置清单。顶层字段决定监听、解析与转发行为，节点提供连接出口，策略组组织出口选择，规则把请求交给具体策略。阅读陌生配置时，先确认这四层是否齐全，再检查名称是否对应。只看某一行是否合法，无法证明整份文件能按预期工作；例如规则引用了不存在的策略组，缩进完全正确也不能得到有效配置。

顶层映射、列表与嵌套

YAML 使用缩进表达从属关系，建议统一使用两个空格，不使用制表符。dns: 下的 enable 是 DNS 子字段，不能与顶层 mode 对齐后仍期待原含义。以短横线开头的是列表项；同一个节点的 name、type、server 必须处于同一映射层级。冒号后通常需要空格，英文冒号不能被中文标点替代。代码编辑器显示的竖向缩进参考线，比肉眼数空格更可靠。

# 可独立加载的直连结构示例，不包含远程代理节点
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

rules:
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

这份示例用于说明结构，不会凭空获得代理能力：PROXY 组里只有 DIRECT，最终连接仍然直连。实际使用时，应把合法节点或节点提供器接入策略组。空列表 [] 表示字段存在但暂时没有条目，和删掉整个字段不是同一种表达。逐步扩展时，先保留可加载的骨架，每次只增加一类对象，出现问题就能知道错误来自哪一次变更。

字符串、布尔值与名称引用

端口和间隔通常写成数字，开关使用 true 或 false，不要写成中文“开启”。节点名、密码、含冒号或井号的字符串建议加引号，避免被解释成映射或注释。单引号字符串中的单引号需要写成两个；双引号内的反斜杠可能参与转义。复制含 Windows 路径的值时尤其要注意，使用单引号可减少意外转义。注释只帮助阅读，不会改变字段的生效顺序。

同一份映射里不要重复定义两个 dns 或两个 rules。不同解析器对重复键的处理可能不同，有的拒绝加载，有的保留后者；不能把重复键当作合并机制。策略名称也应保持唯一，大小写、空格和符号都按原样引用。把节点改名后，需要同步修改策略组中的名称；把组改名后，则需要同步修改规则目标及其他组对它的引用。

文件、Profile 与运行配置

客户端里的 Profile 是配置来源及其管理记录，可以指向本地文件，也可以来自远程订阅。订阅更新后保存的内容，未必就是内核最终读取的内容，因为客户端可能随后应用端口设置、合并规则或脚本。排查时要区分“订阅原文”“本地编辑副本”和“运行配置”三个对象。只改下载缓存里的文件，可能在下次更新时丢失；只改未选中的 Profile，则不会影响当前连接。

保存配置前先保留可回退副本，并记录当前选中的 Profile。普通文本编辑器应使用 UTF-8 保存，避免富文本格式、全角空格和自动替换引号。文件扩展名可以帮助客户端识别，但改成 .yaml 并不能把网页内容转换成配置。如果导入后看到 HTML、登录提示或订阅额度说明，应先处理来源问题，而不是继续调整缩进。有关多套配置的切换与持久化，可参阅Profile 与多配置管理。

端口、监听地址与流量入口

结论：监听端口只建立入口，不会让所有应用自动经过代理。应用必须主动连接这个入口，或由系统代理、透明转发等机制把流量送入内核。最常见的 mixed-port 可以在同一端口接受 HTTP 与 SOCKS 代理连接，适合桌面应用统一填写。port 与 socks-port 分别建立独立的 HTTP、SOCKS 入口，只有确实需要区分入口时才应分别启用，避免增加难以追踪的监听项。

端口选择与占用判断

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule

示例仅允许本机访问，适合作为单机起点。端口号不是性能参数，也不是节点服务端端口；修改本地监听端口后，浏览器、终端和其他手动代理应用也要同步更新。不要把同一个端口分配给多个监听字段，也不要让两个代理客户端争用同一地址与端口。内核提示地址已被占用时，应先退出旧进程或调整监听，再重新加载，反复切换节点无法解决本地绑定失败。

在 Windows 上可以用 Get-NetTCPConnection -LocalPort 7890 查看对应 TCP 监听；Linux 可用 ss -lntp，macOS 可用 lsof -nP -iTCP:7890 -sTCP:LISTEN。部分进程信息需要更高权限才能显示。检查结果时同时看地址、端口和进程，不要只看到数字相同就认定代理已运行。监听在回环地址上的服务，不能从另一台设备直接访问。

本机代理与局域网共享

需要给同一局域网内的其他设备使用时，应在理解访问边界后开启 allow-lan，并让绑定地址覆盖相应接口。接入设备填写的是运行客户端那台机器的局域网地址，而不是自身的 127.0.0.1。本机防火墙、无线接入点的设备隔离、不同子网的路由都会影响可达性。先确认本机能通过入口访问，再从局域网设备测试，能够把内核故障与网络隔离区分开。

代理认证与节点认证是两件事：前者限制谁能使用本地入口，后者用于连接远程服务。启用入口认证后，接入应用也要支持并填写对应用户名和密码；某些系统代理设置界面不能完整表达这些参数，需要使用应用自身的代理配置。共享失败时，不要为了排障长期关闭所有防火墙规则，而应只对所需接口、来源地址和端口做定向检查。

系统代理、终端与 TUN 的边界

系统代理通常只是向遵循系统设置的应用提供入口地址，不能保证所有程序都会读取。命令行工具往往依赖环境变量或自身参数；可以使用下方命令明确指定 HTTP 代理，避免把环境变量遗留问题误判为内核问题。测试成功只能证明该请求通过指定入口发起，不代表其他应用已接入，也不证明所有域名的分流都正确。

curl --proxy http://127.0.0.1:7890 https://example.com/

TUN 属于虚拟网络接口入口，涉及系统权限、路由、DNS 接管和现有网络软件，并不是打开普通监听端口后的必然步骤。只有应用不支持代理或需要更广泛接管时，再按客户端文档启用。系统代理正常而终端失败时，可先阅读浏览器与命令行分开检查。选择客户端时，优先从下载页的 Clash Plus 开始，再根据平台与所需功能比较其他客户端。

代理模式、日志与控制接口

结论：mode 决定如何选择转发策略，不负责建立节点，也不负责接管应用。规则模式读取规则列表，全局模式使用全局策略选择，直连模式直接连接目标。切换模式前，应先确认流量已经进入内核，并且可用策略确实存在。把模式改为全局，不能修复监听失败、订阅为空或远程服务器不可达；它只能帮助判断问题是否与规则选择路径有关。

rule、global 与 direct

mode: rule
log-level: info
ipv6: false

rule 适合长期按域名、地址和应用需求进行分流。global 会绕过常规规则选择，使用全局策略当前选项，因此要同时检查客户端全局组里选了什么；如果选中直连，全局模式也不会神奇地变成代理。direct 用于不经过代理出口的连接判断。三种模式都不能替代系统入口设置，尚未进入内核的应用不会因为模式变化而改变路径。

测试时应只改变一个变量。例如原来某网站失败，保持节点和 DNS 不变，仅从规则模式切到全局，并重新发起连接。如果全局可用而规则失败，再检查规则命中与目标组；如果两者都失败，则继续检查节点和解析。既换节点又换模式再修改 DNS，即使恢复，也难以知道是哪一处起作用。持久连接还可能继续沿用旧出口，测试时需要关闭旧连接后再观察。

log-level 如何用于定位

info 适合日常保留关键运行信息；需要追踪具体请求时，可短时切换到 debug。warning 与 error 逐渐减少输出，silent 会让排障缺少依据。日志级别本身不会改善节点速度，详细日志还可能增加输出负担。观察一段可复现的操作后就应恢复日常级别，避免长期积累大量不必要的数据。

阅读日志先按阶段分类：配置解析阶段的错误指向文件内容；监听阶段失败指向本机地址与权限；请求进入后出现解析错误指向 DNS 路径；拨号或握手失败则需要检查目标出口及协议参数。同样出现超时，发生在 DNS 查询、建立 TCP 连接和 TLS 握手时，排查对象并不相同。不要仅凭一条英文错误就批量替换所有字段。

有效的复现记录应包括当前 Profile、模式、命中规则、选中策略以及同一时间附近的错误。分享日志前要删除订阅地址、认证信息、个人访问域名与局域网拓扑等敏感内容。运行日志与常见报错对照提供了进一步的阅读顺序。日志里没有目标请求时，应优先返回入口检查，而不是继续研究一条根本没有执行的规则。

控制接口不是代理入口

external-controller 用于客户端或面板管理内核，可查询状态、切换策略和修改部分运行设置；它不能填进浏览器当作 HTTP 代理。桌面客户端通常自行管理这个接口与访问凭据，不宜随意在订阅里覆盖。手工运行内核时，应优先绑定回环地址；确需远程管理时，再配合认证和网络访问限制，不能把管理端口当作普通的局域网共享端口。

顶层 ipv6 影响内核的 IPv6 使用行为，DNS 下的同名字段则属于解析配置，两者不能只改其一就推断整个网络栈的结果。是否启用应由本地网络、代理服务与应用需求共同决定，而不是把关闭 IPv6 当作固定优化。遇到只在某类地址上失败的现象，应分别观察地址解析结果和实际连接路径，再调整相应层级的字段。

DNS、Fake-IP 与解析路径

结论：DNS 配置同时涉及应用查询、内核解析和节点域名解析，不能只看一个服务器地址。应用可能使用系统 DNS，也可能自行发送加密查询；内核为了连接目标或节点，也可能发起解析。因此，修改 nameserver 不代表所有查询都经过该列表。先明确请求在哪里产生、由谁接收、查询结果交给谁使用，再判断应该改变监听、接管还是上游选择。

启用与监听的基本关系

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"

该片段建立本机 DNS 监听，但不会自动修改系统 DNS。传统系统 DNS 设置一般不能直接填写非标准端口，因此不能简单把系统地址改为回环地址，就期待系统查询自动送到 1053。需要客户端的 DNS 接管、TUN 配套功能或其他明确的转发机制。如果设备上已有 DNS 服务，应先确认监听地址和端口是否冲突，避免把加载失败误判成解析上游不可用。

default-nameserver 可用于解析 DNS 服务自身的域名，帮助解决先有域名还是先有解析的问题；这里通常使用可直接联系的 IP 地址。nameserver 是主要上游列表，能否访问取决于网络连通与相应出站设置。使用加密 DNS 可以改变查询传输方式，但不能证明查询一定经过代理，也不能保证远程服务在当前网络可达。上游越多不等于结果越准确，应先使用容易验证的组合。

fake-ip 与 redir-host 的差别

fake-ip 为查询分配合成地址，并维护域名与地址的映射，连接到合成地址时再恢复域名进行处理。它有助于保留域名信息，但要求 DNS 查询与后续流量进入同一套处理链。如果应用拿到合成地址后绕过内核直连，连接通常无法成立。redir-host 返回实际解析结果，兼容路径不同；不能把两者理解成单纯的速度开关。

fake-ip-filter 用于让指定域名不走合成地址流程，适合处理局域网服务发现或与真实地址绑定的应用。示例里的局域网后缀只是起点，不是覆盖所有环境的完整名单。过滤某域名不会自动给它添加直连规则，也不会自动指定正确的局域网 DNS。遇到打印机、内部域名或本地服务异常，应同时核对域名解析来源、返回地址和连接路由，而不是扩大过滤范围后就停止检查。

按域名选上游与防止解析回环

nameserver-policy 可以为特定域名选择上游，例如将内部域名交给局域网解析器。策略键的匹配语法应按内核支持范围填写，它不是可以直接复制所有规则表达式的第二个 rules。proxy-server-nameserver 则用于代理节点域名解析，适合把建立出口所需的基础解析单独管理。节点服务器本身解析失败时，目标网站解析正确也无法建立代理连接。

启用 respect-rules 等按分流规则决定 DNS 出站的选项前，要先设计节点域名的独立解析路径。若 DNS 请求必须先走代理，而代理又依赖同一个 DNS 请求才能建立，就可能形成回环。不要一次引入按规则出站、多个上游、复杂过滤和多层回退。先确认基础上游可访问，再逐项增加约束，并在日志中观察解析与拨号阶段是否前后相接。

fallback 与配套筛选配置不是永远启用的备用按钮，其结果选择受筛选条件影响；照抄其他网络的地址范围和地域设置，可能改变预期解析。排障时应记录查询域名、响应地址、使用上游以及连接命中的策略。只有部分应用失败时，还要检查应用内置 DNS 是否绕过系统。有关具体症状的短答可查看FAQ，而不是把所有 DNS 选项同时打开。

代理节点字段与节点提供器

结论：节点字段必须与服务端提供的协议参数逐项一致，名称相似不代表可以互换。proxies 是节点对象列表，常见公共字段包括名称、类型、服务端地址和端口；认证、加密、传输与 TLS 字段则随协议变化。订阅能够成功导入，只能证明客户端接受了配置结构，不能证明服务器地址可达，也不能证明认证和握手参数正确。

公共字段与协议专属字段

# 结构示例：example.com 与认证值仅用于说明字段
proxies:
  - name: 示例出口
    type: socks5
    server: proxy.example.com
    port: 1080
    username: "your-username"
    password: "your-password"
    udp: true

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - 示例出口
      - DIRECT

该示例展示 SOCKS5 节点如何被策略组引用，不提供实际代理服务。name 是本地标识，修改它不会改变服务器，但会影响其他位置的引用。server 是远程地址，port 是服务端监听端口，不能用本地 mixed-port 替换。用户名和密码应来自实际服务参数；如果服务端不使用该认证方式，就不应为了凑齐字段而随意添加。

type 决定后续字段如何解释。Shadowsocks 的加密与密码、VMess 或 VLESS 的用户标识、Trojan 的认证与 TLS、其他协议的传输参数都有各自约束，不能在同一节点里混合不同协议的字段来尝试兼容。遇到未知字段提示时，先核对当前内核是否支持对应协议及字段，再检查订阅格式，而不是简单删除所有报错字段；删掉必要传输参数可能让配置能加载却无法连接。

TLS、传输层与 UDP

需要 TLS 的节点可能包含服务器名称、应用层协议协商以及证书相关选项。服务器名称通常服务于握手与证书验证，不一定等于连接地址；地址、TLS 名称和 WebSocket 请求头中的主机字段也可能分别承担不同角色。应按服务端给出的组合填写。不要把某个可访问的网站域名随意填进这些位置，域名看起来正常并不意味着对应服务端会接受握手。

证书验证失败时，应检查系统时间、服务器名称、证书有效性和服务端配置。跳过验证会削弱对远端身份的确认，不应作为通用修复方法长期保留。WebSocket、gRPC 等传输还需要匹配路径、服务名或请求头，任何一层不一致都可能表现为连接被关闭。排查时应保存服务端原始参数作为对照，不要只比较客户端界面里可见的节点名字。

udp: true 表示允许使用相应节点的 UDP 能力，并不能让不支持 UDP 的服务端获得该能力。还要确认应用入口、策略组、节点协议和远程服务整条链都支持所需流量。网页可打开而游戏、语音失败时，应先区分 TCP 与 UDP；单次 HTTP 探测成功不足以验证所有应用。反之，UDP 不可用也不意味着普通 HTTPS 请求必然失败。

proxy-providers 与整份订阅的区别

# 提供器片段：本地文件需预先存在，并包含 proxies 列表
proxy-providers:
  local-nodes:
    type: file
    path: ./providers/local-nodes.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - local-nodes
    proxies:
      - DIRECT

proxy-providers 将节点来源独立出来，策略组通过 use 引用提供器，而不是把提供器名字放入普通节点列表。文件型来源要求文件真实存在且内容符合提供器格式；网络型来源还需要正确地址、保存位置与更新配置。完整 Profile 通常还包含 DNS、规则与组，不能默认把整份订阅原文当作只含节点的提供器文件使用，具体要看来源支持的输出格式。

提供器获取成功与其中节点可连接也要分开判断。前者取决于下载路径与内容格式，后者取决于协议和出口。服务返回登录页面、错误文本或空列表时，先处理订阅授权、有效期及响应内容。订阅链接可能含访问凭据，不应粘贴进公开日志或在线转换工具。节点全部失败时，可按从订阅到出口的逐层排查顺序确认故障层级。

客户端是否能够编辑某类节点，与内核是否支持相应字段是两个问题。选择 Clash Plus、Clash Verge Rev、FlClash 等客户端时，应同时确认它们当前使用的内核与导入能力；界面没展示的字段不一定无效，界面允许输入也不代表服务端接受。维护节点时优先保留可信来源的原始参数，把策略与规则定制放在外围，减少对认证内容的手工改写。

策略组、自动选择与引用关系

结论：策略组是出口选择器，规则指向组后，仍要由组内当前策略决定最终节点。proxy-groups 将多个节点、其他组或提供器组织起来。设计时先确定用户需要哪些决策，例如手动固定出口、自动选择或故障切换，再选择组类型。把每种类型都堆进配置并不会自动提升可靠性，反而会让实际出口难以解释。

select 与嵌套策略

# 直连组用于展示可加载结构，实际节点应按需加入
proxy-groups:
  - name: 手动选择
    type: select
    proxies:
      - DIRECT

  - name: PROXY
    type: select
    proxies:
      - 手动选择
      - DIRECT

rules:
  - MATCH,PROXY

select 由用户或控制接口确定当前选项，适合需要固定出口的应用。示例中规则先到 PROXY，再可能进入“手动选择”，最后到达 DIRECT；真正访问时应沿着这条引用链追踪。组名只是标识，不保证行为。名叫“自动”的组如果类型仍是 select，也不会自动测试并选出节点。

嵌套组应避免循环，例如甲组引用乙组，乙组又引用甲组。命名也应区分用途与来源：用途组可以是工作、媒体或默认出口，来源组可以对应某个提供器。这样更新订阅节点时，不必同步改动所有规则。组层级不宜过深，通常能在少量跳转内解释最终出口即可；否则界面显示一个选中名称，却需要逐层展开才能知道实际路径。

url-test、fallback 与 load-balance

url-test 使用探测结果选择候选出口，适合接受自动切换的访问场景。fallback 更关注候选顺序与可用性，适合希望优先使用某个出口、失败后再切换的场景。load-balance 根据策略把连接分配给不同候选，不是把一个下载连接的带宽相加。需要稳定来源地址的登录、支付或会话业务，应谨慎使用可能改变出口的组。

# 片段：local-nodes 提供器须已在 proxy-providers 中定义
proxy-groups:
  - name: 自动选择
    type: url-test
    use:
      - local-nodes
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

示例中的 interval 是探测间隔，tolerance 用于减少细小差异造成的频繁切换，它们不是节点测速成绩。探测地址应在当前网络和出口上可以稳定访问，并且响应适合连接测试。某个地址探测失败，可能是测试目标受限，而不是节点对所有目标都不可用；应与实际应用请求交叉验证，不要只按一列测试结果决定所有业务的策略。

候选列表、过滤与测试边界

proxies 写明确的节点或策略名称，use 引用节点提供器；两类来源可以配合，但应防止重复或空候选。使用 filter 等名称筛选条件时，要确认正则表达式匹配的是实际节点名，而不是提供器名。订阅方改名后，原先有效的筛选可能突然得到空列表。排查自动组没有节点时，先看提供器内容，再看筛选结果，最后才检查探测设置。

健康检查回答的是指定探测目标是否能按条件完成请求，不是节点在全部协议和目的地上的通用评分。频繁并发探测会产生额外连接，对移动网络、低功耗设备或有限额服务尤其需要克制。提供器层和策略组层都配置检查时，还应留意是否产生重复探测。优先保留足以判断可用性的频率，不要为了界面数据持续刷新而缩短间隔。

规则指向的用途组应尽量稳定，节点更换放在组内部完成。发现同一个网站偶尔走不同出口时，先查自动组是否切换、应用是否建立多条连接、域名是否对应多个规则路径，再考虑服务端问题。对需要长期固定出口的任务，可单独建立手动组，避免与日常自动选择混用。不同客户端的组选择界面可在选型指南中结合平台需求比较。

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

结论：规则按列表从上到下处理，首条匹配决定本次分流，不按文字长度自动判断优先级。维护 rules 时，应把具体例外放在一般规则之前，将兜底规则放在最后。新增规则前先说明它要匹配什么信息：域名、目标地址、来源地址还是进程。规则能使用的信息取决于入口和系统环境，不能假设每条连接都具有完整域名与进程名称。

域名规则与目标策略

# 片段：PROXY 策略组须已定义
rules:
  - DOMAIN,login.example.com,PROXY
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,internal,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,PROXY

DOMAIN 匹配完整域名，DOMAIN-SUFFIX 匹配域名后缀及相应子域，DOMAIN-KEYWORD 按域名包含的关键词判断。关键词规则范围通常更宽，容易把并不相关的域名一起纳入，因此精确需求优先使用完整域名或后缀。填写时不加 https://、路径或端口；这些是 URL 的其他部分，不是域名规则要匹配的值。

规则最后一段是目标策略，可以是内置动作，也可以是已定义的节点或组。为了维护稳定性，通常让规则指向用途组，而不是会随订阅更新改名的节点。DIRECT 表示直接连接，REJECT 用于拒绝请求；策略名字要与定义完全一致。把组名写错不是“没有命中”，而是配置引用关系有问题，应在加载检查阶段处理。

地址匹配与 no-resolve

IP-CIDR 匹配 IPv4 网络，IPv6 网络使用对应的 IP-CIDR6。当请求以域名形式进入，而规则需要真实地址才能判断时，内核可能触发解析。末尾的 no-resolve 用于避免为了这条地址规则主动解析域名，但它不会阻止已经具有目标地址的连接参与匹配，也不是全局关闭 DNS。给所有地址规则机械添加它，可能改变原有分流结果。

GEOIP 根据地址数据库分类，结果依赖数据库内容与更新；域名分类常见的 GEOSITE 则需要相应资源和内核支持。示例里的地域直连只是演示写法，不能视为所有网络的默认政策。数据库分类不等于服务实际所在地，也不保证目标可达。企业网络、跨区域服务和自建地址应根据实际需求配置例外，而不是依赖单一分类解决全部问题。

rule-providers 与 RULE-SET

# 文件需预先存在，内容格式须与 behavior 对应
rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,PROXY

规则提供器把可更新的匹配内容放在独立文件，主配置通过 RULE-SET 引用它。behavior 用来说明内容是域名、地址段还是传统规则表达式，不能仅根据文件扩展名判断。YAML 格式的域名提供器通常在 payload 下列出域名匹配项；传统行为的规则集则使用相应规则表达式，不是在每行重复填写主配置里的目标策略。

规则集文件内容下载成功后，仍需检查格式与行为是否一致。把纯文本域名列表当成 YAML，或把完整规则列表交给域名行为解析，都会产生错误或意外结果。网络型规则来源还涉及更新请求是否可达、缓存文件是否可写。更新失败时应保留可用缓存并定位获取问题，而不是立即把整份主配置重置，导致本来正常的其他部分也丢失。

从连接记录反推规则

验证新规则应发起一个新连接，记录请求域名、匹配规则和最终策略。浏览器页面往往同时访问主域、登录、静态资源与接口域名，页面只加载一部分时，需要分别观察这些连接，不能只给地址栏域名添加一条规则。若连接只剩 IP，应检查应用是否自行解析、DNS 是否进入内核，以及当前入口是否保留了域名信息。

进程规则还受平台、权限和入口影响，相同配置换一台设备可能无法获取同样的进程元数据。不要把它作为跨平台唯一依据。逐条排查时，先找最早能够匹配的规则，再确认组内选择，最后验证出口。若规则模式失败而全局正常，这条路径比直接批量添加宽泛关键词更可控；临时例外验证成功后，也应收窄范围并写明用途。

订阅覆写、配置合并与加载验证

结论：可持续的自定义应独立于会被远程更新替换的订阅原文，并以最终运行配置为验收对象。客户端通常提供覆写、合并、扩展配置或脚本入口，但这些是客户端生成配置的机制，不是所有客户端共享的一套 YAML 标准。迁移到另一款客户端时，应重新确认应用顺序和合并语义，不能只复制一份名为覆写的文件就假定结果一致。

标量、映射与列表的合并差别

标量字段例如 mode、mixed-port，通常表现为后写入的值覆盖先前值；映射例如 dns，可能逐键合并，也可能整体替换；列表例如 rules、proxies，则可能替换、前置或追加。具体行为必须以客户端说明与生成结果为准。仅知道某个功能叫“合并”，不足以判断原有节点或规则是否会被保留。

# 概念示例：仅用于支持规则前置的客户端覆写入口
# 不应直接拼接成第二个顶层 rules
rules:
  - DOMAIN,work.example.com,DIRECT

若客户端把这段内容整体替换原有规则，所有订阅规则都可能被移除；如果追加到原有 MATCH 之后，这条规则又可能永远没有机会匹配。正确操作是选择客户端支持的前置规则功能，或在脚本中明确构造顺序，再查看最终列表。DNS 合并也一样：修改上游列表时应确认其他子字段是否保留，避免只想改一个地址却清除了监听与模式设置。

确认写入顺序与名称稳定性

建立一张简单的来源记录：订阅提供哪些节点和规则，客户端全局设置控制哪些端口，覆写补充哪些 DNS 与例外，脚本是否再修改策略组。多个入口都修改同一字段时，应尽量收敛到一个地方。运行模式反复恢复、端口保存后变化、规则每次更新后消失，往往是后续生成步骤覆盖了前一步，而不是编辑器没有保存。

自定义规则依赖的策略组应有稳定名称，并确认订阅更新后仍会生成。若自定义组引用某个具体节点，而服务方定期改名，更新后就可能失去候选。更稳妥的方式是通过固定用途组衔接提供器或客户端的节点集合。脚本修改前也应验证目标字段类型，不能假设所有订阅都包含相同的列表结构；遇到缺失对象时应给出可理解的失败，而不是生成半份配置。

语法检查、加载检查与实际连接

# 适用于已安装 mihomo 命令行程序的环境
mihomo -t -f ./config.yaml

命令行测试用于发现配置解析与初始化问题，执行目录、资源路径和运行权限应尽量与实际启动环境一致。引用的提供器文件、地域数据库或其他资源不存在时，即使 YAML 语法正确也可能失败。桌面客户端可以优先使用自身的配置检查入口，避免拿另一个内核程序的结果代替当前客户端环境。检查通过只意味着具备加载条件，并不保证远程节点可达。

完整验证分成三个阶段：先确认配置被选中并成功加载，再确认入口已经监听且应用请求进入，最后检查 DNS、规则、组选择和远程握手。每个阶段都保留一个可复现的请求作为对照。修改后若只有已有连接保持旧路径，应先重新建立连接；若所有新请求都没有记录，应返回入口层；若记录显示正确策略但握手失败，再检查节点参数与服务端状态。

常见失败的回退顺序

配置立即报错时，先恢复最后一次修改，检查缩进、重复键、缺失引用和字段类型。配置能加载却无法访问时，先用直连与指定代理请求做对照，再观察实际命中的策略，不要把两个问题混在一起。只有自动更新后出错时，对比更新前后的节点名、提供器格式和规则目标。只在某个客户端复现时，则进一步核对它的覆写顺序、内核能力和系统权限。

恢复后应把成功条件写入注释或维护记录，例如哪一类流量需要例外、为何使用特定解析路径、某条规则必须位于哪条规则之前。不要记录真实认证值，也不要把临时绕过方案当作长期默认。首次使用仍建议按入门指南完成一条完整连接链；遇到界面操作问题查阅FAQ，更换客户端则从客户端平台下载项选择，保留原配置直到新环境验证完成。