Clash YAML 配置参考

一、YAML 结构与配置入口

先确认修改的是哪份文件

结论是：编辑器里保存成功，不等于内核已经使用新内容。图形客户端通常把配置分成订阅下载的原始文件、用户填写的覆写片段，以及合并后交给内核的运行文件。订阅更新会重新生成原始文件，直接在里面改规则，下次更新可能消失；在运行文件中修改，也可能被客户端启动流程覆盖。应该先在配置页面确认当前激活项目，再找配置预览、运行配置或导出配置入口，核对目标字段最终值。

本页片段按用途拆开，不要把每个示例原样首尾拼接。一个 YAML 文档的顶层应该是映射，dns、proxies、proxy-groups、rules 是不同的键。同一层重复写两个 dns，并不能理解为自动合并：解析器可能拒绝，也可能只保留后者。实际编辑时应找到已有段落，在原段内调整。以下最小配置只验证结构和本地监听，所有流量直连，不包含可用代理线路。

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

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

缩进、列表与字符串的基本边界

缩进决定归属关系，建议统一使用两个空格，不能用制表符代替。冒号后有空格，表示键值分隔；短横线后有空格，表示列表项。rules 下每一条规则都是字符串列表项，而 proxies 下每个节点通常是包含多个字段的映射。节点的 name、type、server 必须在同一缩进层级；把 port 多缩进一级，可能直接触发解析错误，而不是改变端口。

包含井号、冒号加空格等特殊组合的文本，最好用引号包住。密码和标识符尤其应该按字符串处理，避免纯数字被识别成数值，或前导零发生变化。单引号通常更适合保存含反斜杠的普通文本，双引号则会解释转义序列；字符串里确实需要双引号时，必须正确转义。不要从聊天软件复制带全角冒号、弯引号或不可见缩进的配置，外观相近并不代表解析结果相同。

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

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

rules:
  - MATCH,手动选择

空值、布尔值与跨段引用

false 是布尔值，"false" 是字符串，不能依赖内核自动纠正类型。[] 表示空列表，{} 表示空映射，而键后什么都不写通常表示空值，三者不能随意互换。节点名称、策略组名称和规则目标都是引用关系，建议统一命名且避免重名。名称中不要放逗号，因为规则通过逗号分隔参数；可读的中文名称可以使用，但必须保持引用处完全一致。

检查配置时要分两层：YAML 能解析，只说明语法结构成立；内核能加载，才说明字段类型、协议支持和名称引用基本有效。即使通过加载，也不保证远端地址、密码或规则意图正确。不要一次引入复杂锚点、合并键和模板语法，它们会放大客户端解析差异。先用普通映射与列表跑通，再考虑减少重复；不清楚内核身份时，先查客户端关于页面或启动日志，而不是凭界面名称判断兼容性。

二、通用字段：监听端口与代理模式

端口只负责接收流量，不代表线路速度

mixed-port 在同一个监听端口接收 HTTP 与 SOCKS 代理请求，适合把浏览器、命令行工具指向同一入口。port 是单独的 HTTP 代理端口，socks-port 是单独的 SOCKS 端口，并不是都必须填写。普通桌面使用可以先保留混合端口，减少多个监听入口带来的混淆。端口数值只是本机服务地址的一部分，把它从一个数字换成另一个数字，不会让远端代理线路变快。

修改端口之后，需要重载配置并确认新监听已经建立，再让系统代理、浏览器手动代理或终端环境变量同步使用新值。旧环境变量不会跟着 YAML 自动变化，已经打开的终端也可能继续保留原设置。桌面客户端可能用界面中的端口选项覆盖文件值，因此应该以运行配置和监听日志为准。遇到占用先定位进程，确认是否是另一个客户端实例；不要为了腾端口直接结束不认识的系统进程。

mixed-port: 7891
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

规则、全局、直连分别改变什么

mode: rule 表示按规则列表决定出口，日常分流通常选它。global 表示进入内核的流量交给全局策略处理，仍需确认全局策略选择了哪个出口；direct 则选择直连。这里的关键词是进入内核的流量：没有设置系统代理、没有使用显式代理、也没有被 TUN 接管的应用，不会仅因切成全局模式就被自动代理。模式和流量入口是两个不同层面的设置。

切换模式适合做对照实验，不适合掩盖规则错误。若规则模式失败、全局模式成功，说明应该检查规则命中、策略组选择或 DNS，而不是长期保留全局就结束排查。若两种模式都失败，优先看节点、认证、监听与网络可达性。已有长连接可能继续沿用旧出口，切换后要用新连接验证。更细的区别可以参照疑难解答中的代理模式说明，避免把模式切换误当作线路优化。

局域网监听与控制接口要分别管理

allow-lan: false 适合只让本机应用使用代理。需要向其他设备提供代理时，除了允许局域网，还要检查 bind-address、主机防火墙、无线网络隔离和设备访问地址。其他设备应该填写运行客户端那台机器的局域网地址，不能填写它自己的回环地址。开放监听会增加可访问范围，应只在可信网络中进行，并结合认证或访问控制，而不是在公共网络上直接暴露端口。

external-controller 是管理接口，不是浏览器的代理地址；把系统代理填成控制端口不会获得正常代理连接。管理接口应优先绑定回环地址，需要远程访问时再单独设计认证和网络边界。log-level: debug 可短时帮助排错，但会增加信息量，分享日志前要遮住订阅地址与认证内容。ipv6 则与地址处理有关，不能代替网络本身的 IPv6 连通能力；没有验证环境前，不要同时调整它和 DNS 的多个开关。

详细的进程定位与修改顺序见7890 端口占用排查。关键不是选择哪个新数字，而是确保监听地址、入口协议和应用设置三者一致，并从新建请求确认变化确实生效。

三、DNS：解析入口与 fake-ip

先区分内核解析与系统解析

DNS 配置不是只填一个服务器地址。需要同时回答三个问题：谁把域名交给内核解析，内核用什么上游获得真实地址，返回结果如何参与后续连接。dns.enable 开启内置解析服务，listen 指定监听位置，但不会自动让所有系统请求改走这里。系统 DNS、浏览器安全 DNS、应用自己的解析和 TUN 劫持可能并存；仅看到配置里写了 DNS，不足以证明目标请求实际经过它。

下面展示常见 fake-ip 结构，监听在本机高位端口，便于单独验证。它不是完整的透明代理方案，也不会自动修改系统解析器。default-nameserver 用于解析上游 DNS 服务器的域名，应选择可直接访问的 IP 形式解析器；nameserver 则处理一般域名查询。示例上游必须在当前网络可达，否则应按网络环境替换，不要把某组地址当成所有地区都适用的固定答案。

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

fake-ip 不是解析失败，也不负责加密

enhanced-mode: fake-ip 会为查询分配合成地址，并维护域名映射，让后续连接更容易保留域名信息。看到 198.18 开头的结果不一定是异常；关键在于发往合成地址的连接是否仍被同一套代理接管。如果 DNS 返回 fake-ip，但后续流量绕过内核直接发送，连接通常无法成立。因此它要求解析入口与连接入口配套，不能只在系统里孤立指定解析服务。

fake-ip-filter 用来让特定域名绕过合成地址分配，常用于确实依赖真实地址的局域网服务。不要把大量公共域名随手加入过滤表，否则会失去域名映射的便利，并让排错更复杂。redir-host 返回真实解析结果，是另一种工作方式，但不代表天然更快或更安全。遇到兼容问题可以做单项对照，先记录受影响域名、应用和访问路径，再决定是否需要过滤例外。

nameserver、fallback 与定向解析

fallback 不是简单的第二顺位服务器。配置后，内核会结合 fallback-filter 等条件判断采用哪组结果；不同选项涉及域名、地址范围和地理信息，具体行为应以当前内核文档为准。只复制一段 fallback、却没有理解筛选条件，可能增加查询量，或者把本来可用的结果替换掉。先用单一可达上游确认基础解析，再有证据地添加分流，不要一开始就叠加许多公共解析服务。

mihomo 的 nameserver-policy 可以按域名指定解析器，适合将内网域名交给局域网 DNS。代理服务器自身的域名解析则还可能涉及 proxy-server-nameserver，用于避免建立代理连接之前就依赖该代理的循环。选择加密 DNS 只保护相应解析传输，不会自动让业务连接走代理；是否遵循路由规则、上游如何拨号，应结合当前内核支持的字段逐项确认。

dns:
  enable: true
  listen: "127.0.0.1:1053"
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
  proxy-server-nameserver:
    - 223.5.5.5

上例是另一份 DNS 段示意，192.168.1.1 必须替换为实际内网解析器；不要与前一个示例重复粘贴成两个顶层 DNS 段。TUN 的 dns-hijack 位于 tun 下，不属于 dns，并且通常不能接管应用自行发出的 HTTPS DNS。排查时分别测试内核监听、系统解析和浏览器行为，注意清理缓存或新建连接，避免旧结果干扰判断。

四、代理节点：协议字段与提供器

通用字段相同，不代表协议参数通用

proxies 是本地节点定义列表。最常见的公共字段是 name、type、server 和 port：名称供策略组引用，类型决定协议解析方式，服务器与端口决定连接目标。server 通常只填写域名或 IP，不要带 https://、路径或订阅查询参数。代理节点端口是远端服务端口，与本机 mixed-port 没有必须相同的关系，两者不要互相抄写。

协议专用参数必须来自服务方。Shadowsocks 需要匹配加密方式与密码，Trojan 通常需要密码与 TLS 相关参数，VMess、VLESS 则涉及对应标识与传输设置。不能只把 type 从一种协议改成另一种，期待原节点继续可用。传输层也要对应：WebSocket 路径、请求头、gRPC 服务名称等，只有在服务器确实配置了相应传输时才有意义，额外多写字段不会增强兼容性。

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

TLS 名称与 UDP 能力不能靠开关补齐

sni 是 TLS 握手相关名称，可能与拨号地址相同，也可能由服务方另行指定。证书错误应先检查设备时间、服务器名称、证书有效性和链路是否被替换，不应把 skip-cert-verify 改为真作为常规解决方法。保留证书验证可以让名称不匹配等问题被明确暴露；如果连最初的 TCP 连接都没有建立，修改 SNI 或证书选项通常也解决不了地址不可达的问题。

udp: true 只表示配置允许使用相应能力，不代表服务端、协议、线路和应用入口都已经支持 UDP。浏览器能打开网页，但游戏或语音失败时，需要检查实际使用的传输与接管路径。反过来，测速超时也不能立刻说明所有业务都失败，测试目标、请求方法与节点路由可能存在差异。应该把握手失败、认证失败、远端连接失败分开看，避免把所有错误都归为节点失效。

proxy-providers 负责载入节点集合

proxy-providers 用于把节点集合交给内核加载，策略组再通过 use 引用。HTTP 提供器的 url 是资源地址，path 是缓存位置，interval 常以秒为单位控制更新间隔。提供器资源与完整客户端订阅不是同一种格式：常见节点提供器需要包含 proxies 列表；如果响应内容是网页登录页面或其他格式，仅更换扩展名并不能让它变成有效 YAML。

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

proxy-groups:
  - name: "订阅选择"
    type: select
    use:
      - remote-nodes

示例地址仅演示结构，需要替换成实际提供器资源；如果已经由客户端配置页管理订阅，通常不必再手写第二套更新机制。先辨认服务方提供的是完整配置、节点列表还是 URI 集合，再选择对应导入方式。缓存相对路径由内核工作目录解释，不一定相对于编辑器打开的文件夹；更新失败时查客户端数据目录和权限，比反复移动 YAML 更有用。

认证信息属于敏感内容，截图和求助日志只保留域名、错误类型及必要字段，不要公开完整订阅链接。节点名称更新后，手工写死的策略组引用可能失效；采用提供器引用可以减少逐个维护，但仍要处理过滤条件和可用节点为空的情况。订阅能下载只说明资源获取成功，不能替代节点连接验证，更不能证明该资源中的所有协议都受当前内核支持。

五、策略组：手动、测速与故障切换

先建立明确的引用关系

策略组是规则与实际出口之间的一层选择。规则可以指向组，组再包含节点、其他组或内置目标。这样更换节点时不必修改每条域名规则。最基础的 select 提供手动选择，适合先确认哪些线路可用。组内 proxies 填的是节点或组的名称，而不是服务器地址；use 填的是提供器名称。两者承担的引用类型不同，拼错一个字也可能让配置加载失败。

建议把用途和机制分开命名，例如“日常出口”表示业务入口，“自动测速”表示选择机制。日常规则统一指向前者，前者再允许选择测速组、备用组或单个节点。不要让一个组包含自己，也不要让多个组互相绕回形成循环。组名避免使用与内置目标相同的名称，也不要与节点重名；能加载的复杂嵌套不一定容易维护，排错时层级越少越容易看到实际出口。

proxies:
  - name: "线路 A"
    type: ss
    server: a.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
  - name: "线路 B"
    type: ss
    server: b.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "日常出口"
    type: select
    proxies:
      - "自动测速"
      - "备用切换"
      - "线路 A"
      - "线路 B"
      - DIRECT

  - name: "自动测速"
    type: url-test
    proxies:
      - "线路 A"
      - "线路 B"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "备用切换"
    type: fallback
    proxies:
      - "线路 A"
      - "线路 B"
    url: https://www.gstatic.com/generate_204
    interval: 300

rules:
  - MATCH,日常出口

自动测速只反映测试请求

url-test 会按照测试结果选择出口，url 是检测目标，interval 控制检测间隔，tolerance 用于减少小幅差异造成的频繁切换，通常按毫秒理解。不要把检测周期设得过短，尤其是移动设备和节点数量较多时，密集请求会增加网络与电量消耗。选择稳定且预期响应明确的检测地址，避免需要登录、发生复杂跳转或对特定线路限制访问的页面。

节点延迟是一次测试请求的观测结果，不等于视频吞吐量、下载速度或所有网站的响应时间。测试目标可达，业务目标仍可能受地区、账号或服务策略影响。看到某节点数值较低时，应该再用实际业务验证，而不是把整套规则交给测速结果决定。组内包含 DIRECT 时还要想清楚意图：如果让自动测速在直连和代理间竞争，可能得到与预期完全不同的出口选择。

fallback 与负载均衡各有边界

fallback 通常按列表优先顺序选择可用项，重点是故障切换，而不是每次寻找最低延迟。顺序前面的节点恢复后，后续新连接如何选择还应结合内核实现与当前状态确认。它不会迁移已经断开的 TCP 会话，正在进行的下载仍可能需要重新连接。将它作为“主线路加备用线路”更容易理解，不要把自动恢复误解成业务完全不会中断。

load-balance 会在多个出口间分配连接，策略取决于具体配置，不是把多条线路带宽直接叠成单连接速度。某些业务对出口地址变化敏感，可能出现重新认证或会话异常；这类业务宜固定到稳定策略组。第一次搭建配置时，先用手动组完成验证，再加入自动机制。只有手动选择节点也失败，才说明应该继续查节点或入口，而不是调整测速容差。

客户端可能保存组的上次选择，重新加载后并不一定回到列表第一项。profile.store-selected 等配置、图形界面的持久化机制以及组名变化，都可能影响恢复行为。排查时应查看当前选中项，而不是只阅读 YAML 顺序。节点由提供器更新时，还要留意过滤后是否剩余可用项；自动组为空、名称引用缺失与所有探测失败是三类不同问题，需要分别处理。

六、分流规则：匹配顺序与规则集

规则从上到下，先命中先结束

规则模式下，普通规则按列表顺序匹配，先命中的目标决定后续出口。最容易出错的不是写法，而是位置：把覆盖范围很大的规则放前面，会让后面的精确例外没有机会执行。MATCH 是兜底，应放在常规列表末尾。添加网站例外时，应同时确认规则目标存在、组内选择正确，并用新连接观察命中；仅看到列表里有这个域名，不能证明该条规则实际被走到。

DOMAIN 精确匹配域名，DOMAIN-SUFFIX 匹配域名及其子域，DOMAIN-KEYWORD 匹配域名中的关键词。需要让某个站点直连时，优先用精确域名或后缀，别只写短关键词，否则可能影响无关域名。规则里一般不填 URL 协议、路径或网页参数；同一网站也可能调用多个资源域名，主页面命中直连不代表图片、登录和接口自动采用相同出口。

rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,home.arpa,DIRECT
  - DOMAIN-SUFFIX,example.org,日常出口
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,日常出口

IP 规则与 no-resolve 的实际含义

IP-CIDR 根据目的地址所属网段匹配，适合内网或明确的地址范围。no-resolve 表示这条规则不主动触发域名解析，不是禁止整个连接使用 DNS。请求已有目的 IP 时仍可进行匹配；如果只有域名且尚未解析，它可能跳过该条而继续往下。把所有 IP 规则都加上这个参数之前，要理解自己是想减少查询，还是确实需要通过解析结果判断出口。

GEOIP 依赖对应地址数据库，GEOSITE 涉及域名分类数据，并且与内核支持及资源配置有关。它们不是实时判断服务器物理位置的工具，数据库更新和共享地址都可能造成偏差。遇到单个业务误分流时，用精确规则覆盖往往比大幅改变分类逻辑更稳妥。不要为省事把所有私有地址都交给一个过宽的公网例外，特别是在存在企业网络或多段局域网时。

rule-providers 的格式必须对应 behavior

规则提供器把长列表独立成资源，主配置通过 RULE-SET 引用。behavior: domain 适合域名列表，ipcidr 适合网段，classical 则使用规则类型加参数的形式。资源内容还要对应 format，不能把纯文本列表当作带 payload 的 YAML，也不能把二进制资源按文本读取。下载成功但解析失败时，先核对格式与响应正文，再判断是否网络问题。

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,日常出口

对应的 local-domains.yaml 可以写成下面这样。需要先创建文件并确保内核有读取权限；相对路径仍由运行目录决定。主配置中的目标“日常出口”必须已在策略组定义，规则提供器文件则只保存匹配内容，不在每行重复填写策略名。一个清晰的资源职责边界，比在所有文件里混写出口更容易维护。

payload:
  - "+.home.arpa"
  - "printer.example.com"

mihomo 的进程名规则等能力还受操作系统、权限和入站方式影响。某平台能够识别进程，不代表其他平台也能沿用相同效果。基于域名的规则在应用先自行解析、再以 IP 连接时，也可能缺失所需域名信息。排错应观察连接详情中的域名、目标 IP、命中规则和实际链路，先判断输入信息是否完整，再决定调整 DNS、接管方式还是规则顺序。

七、覆写与合并：保留订阅更新能力

区分内核配置与客户端加工流程

覆写不是一个所有客户端都相同的 YAML 标准。内核读取最终配置，图形客户端则可能在读取前应用全局设置、订阅专属设置、合并片段或脚本。Clash Plus、Clash Verge Rev、FlClash 等客户端的入口与优先级不能简单互抄。先查看当前客户端的覆写说明，再确认作用范围是全部订阅还是单个配置；只要最终生成文件中字段与预期不同，就应该排查加工流程，而不是继续反复编辑订阅原文。

常见合并方式包括覆盖标量、递归合并映射和替换列表，但这些不是必须遵守的统一规则。例如一个覆写片段只写 dns.nameserver，有的工具会保留原 DNS 的其他键，有的流程可能替换整个段落。rules、proxies 等列表更需要谨慎：把只含一条规则的列表当作补丁提交，可能直接替换整张规则表。不能根据“合并”两个字推断它一定是追加。

# 仅适用于接受普通 YAML 合并片段的客户端。
# 仍需在客户端确认映射和列表的合并规则。
mixed-port: 7891
allow-lan: false
log-level: info

dns:
  enable: true
  ipv6: false

规则前置、后置与列表替换

需要增加本地规则时，优先选择客户端明确提供的规则前置或规则追加功能，而不是猜测某个私有字段。前置适合必须优先匹配的域名例外；后置则要注意原列表可能已经包含 MATCH，追加到它后面的普通规则不会生效。若工具提供的是整表替换，就需要保留原有规则及兜底，并承担订阅规则更新不同步的维护成本。选择哪种方式，应由希望保留多少订阅控制权决定。

节点和策略组同样存在依赖。删除原节点却保留旧组引用，会导致找不到目标；用新组名替换旧组名却没有修改规则，也会破坏引用。正确顺序是先明确最终命名，再同步节点、组和规则三个层面的关系。如果只想固定某个网站出口，通常只需添加一条精确规则并引用已有组，不必接管整个节点列表。改动面越小，后续订阅更新越不容易产生冲突。

YAML 的锚点和合并键只能在解析器支持的语义范围内复用结构，不会天然提供跨文件覆盖，也不能当作通用的列表追加语法。不同编辑器预览正常，客户端仍可能采用不同解析流程。脚本覆写更灵活，但还涉及客户端约定的函数入口、执行顺序与错误处理；本页不提供假定所有客户端都支持的脚本模板。没有明确接口说明时，普通字段覆写比复制来源不明的脚本更容易验证。

建立可回退的配置分层

可以把维护内容分成三层：订阅层负责节点与服务方规则，本地层负责端口、可信内网例外和个人策略，临时层只用于排错。临时调整成功后，应整理回适当的持久层，并移除重复键。每个覆写片段写清用途，保留修改前的可运行备份。不要同时在界面选项、全局覆写和订阅覆写里设置相同端口，否则未来只改一处会产生“保存了但没变化”的错觉。

验证覆写不能只看文件是否保存。先重新载入当前订阅，查看合并后配置，搜索目标键；再确认策略组与规则引用存在，最后用新请求检查命中。随后手动更新一次订阅，确认改动仍然保留，这一步专门验证持久化位置是否正确。如果更新后消失，就应该迁移到客户端支持的本地层，而不是每次更新后重新手改。切换另一个订阅也要检查作用范围，防止全局规则引用只在某份订阅存在的组。

多人或多设备维护时，建议记录“字段、来源、最终值、验证方法”四项信息。不要只记菜单点击过程，因为客户端界面可能变化；记录最终结构更容易在升级、迁移与重装后恢复。遇到更新后突然无法启动，也应先回看最近新增的覆写及引用关系，再进入故障排查页面逐项定位。

八、验证与排错：从加载到实际请求

先通过解析与内核测试

验证顺序应固定为语法、内核加载、端口监听、节点连接、规则命中，最后才是具体应用。这样每一步都有明确的输入与结果。出现启动失败时，先回退到最近能运行的配置，避免在坏文件上继续叠加修改。使用命令行测试前，要确认调用的是当前客户端对应内核；系统里另一个旧二进制可能不支持新字段，测试结果不能直接代表客户端实际行为。

# 在配置文件所在目录执行，命令名按本机实际安装方式调整。
mihomo -t -d . -f ./config.yaml

-f 指定文件，-d 指定工作目录，测试可能需要读取提供器缓存或相关资源。命令返回成功，表示当前环境下配置通过基础加载检查，不代表远端节点和所有规则资源都健康。若客户端没有提供独立命令行入口，可以使用配置检查与日志页面完成相同层次的验证。不要为了跑一条测试命令，把内核文件复制到不受控目录或另开一个常驻实例。

解析错误通常给出行号，但真正原因可能在前面一行，例如字符串未闭合、列表项缺失或缩进层级改变。先查看报错行附近的完整映射，必要时回到最小结构逐段加入。名称不存在则检查节点、组与规则的引用，不是删掉报错行就算修复；字段不支持则核对内核身份和该字段适用位置。权限或资源读取错误要检查工作目录，而不是改 YAML 缩进。

用显式代理隔离系统接管问题

内核正常启动后，先用显式代理发一个新请求，把系统代理与 TUN 暂时排除在判断之外。下面命令适用于支持这些选项的 curl；Windows 环境中可以明确使用 curl.exe，避免命令别名差异。端口需替换为实际监听值，测试地址也应选择当前环境预期能够访问的目标。一次请求失败只能证明这条路径有问题，不能直接说明所有代理功能失效。

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/
curl --proxy socks5h://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/

socks5h 让域名交给代理端处理，和客户端本地先解析再连接的测试路径不同。如果一种成功、另一种失败，应该继续比较解析和入口协议，而不是立即更换全部节点。显式代理成功但浏览器失败，优先查系统代理、浏览器扩展、独立安全 DNS 与旧连接。TUN 场景则还要检查系统路由、授权和其他网络接管软件，避免两套工具同时抢占入口。

按症状收集最小证据

求助时提供操作系统、客户端名称、内核身份、故障发生步骤和脱敏后的相关日志。再说明显式代理是否成功、规则模式与全局模式是否有差异、是否仅一个目标失败。这些信息比一张“超时”截图更有用。不要只上传大量 debug 输出：先截取故障前后的关联记录，遮住认证信息，再说明每次试验改变了哪个变量。错误能稳定重现，才容易判断修复是否有效。

最后做一次回归：重新启动客户端，确认监听恢复；更新订阅，确认本地覆写仍在；切换网络后重试目标业务，检查解析缓存与策略组选择。排错结束将日志级别恢复到日常值，移除临时放宽的设置和重复规则。配置维护的目标不是字段越多越好，而是每个字段都能说明用途，每次修改都能验证结果。后续需要重新梳理连接流程可回到使用文档，需要更换客户端则查看下载中心的系统与架构选项。