Clash 配置大全

一、YAML 总览：从文件结构到生效配置

Clash 配置不是一张节点地址表，而是一组相互引用的对象。通用字段声明入口和工作模式，DNS 字段决定内核如何解析域名，代理节点定义可用出口，策略组组织出口，规则把连接交给指定目标。阅读陌生配置时，先看顶层有哪些键，再追踪名称引用；直接从几百条规则往下读，容易忽略真正控制连接路径的入口设置与最终策略。

缩进、映射与列表

YAML 使用缩进表达层级。冒号后接一个空格表示键和值，短横线开头通常表示列表元素。缩进建议统一为两个空格，不要混用制表符；同一层级必须对齐。顶层的 dns 与 rules 平齐，而 enable 放在 DNS 下面。中文名称可以使用，但名称中的空格、标点和大小写都属于引用内容，不能在别处随意改变。

端口使用整数，开关使用不带引号的 true 或 false。域名模式、密码、含冒号或井号的字符串建议加引号，避免被解释成映射、注释或其他类型。井号只在字符串外承担注释作用。重复顶层键也应避免：不同解析器可能报错，也可能仅保留其中一份，不能靠重复写两段规则列表实现追加。

# 完整的直连教学配置，不包含远程代理节点
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: false

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

这份配置可以用于支持这些字段的内核的基本启动测试；端口未被占用时，它建立一个本地混合代理入口，但所有匹配连接仍然直连。应用还必须显式使用该入口，配置才参与请求处理。它不提供远程出口，也没有开启内核 DNS。将它作为独立测试文件保存，不要用它直接覆盖正在使用的订阅，否则原有节点和规则会被移除。

先识别输入文件属于哪一层

订阅 URL 是获取内容的地址，不代表返回内容必然是完整 YAML。有的返回整份配置，有的只有节点列表，有的返回编码文本或单节点分享链接。完整配置应放进配置导入入口，节点集合则可能需要客户端转换，或由 proxy-providers 引用。入口选错时，即使地址能够下载，也可能出现缺少字段、解析失败或规则目标不存在。

配置文件还可能经过客户端二次加工。订阅原文保存了服务方提供的内容，本地设置保存了端口、接管方式等偏好，覆写文件用于插入或替换部分字段，最终生成文件才交给内核。编辑某一层后，应找到客户端的运行配置预览或导出入口，核对变更是否进入最终文件。界面中显示了一个数值，并不等于订阅文件中的同名字段拥有最终优先级。

沿引用关系检查，而不是只看语法

规则里的策略名称必须对应节点、策略组或内置目标；策略组里的节点名称又必须存在。名字写对还不够，组之间不能构成循环引用。推荐按节点、策略组、规则的顺序阅读：先知道出口有哪些，再知道怎样选择出口，最后看哪些连接被送往那里。遇到规则提供器或代理提供器时，继续检查其路径、格式和加载结果，而非把顶层声明当作已经成功加载。

开始修改前，记录当前客户端名称、内核类型和配置来源，并导出一份可恢复副本。优先保留能工作的配置，只改变一个主题，再验证差异。若还没有客户端，可从客户端下载页先考虑 Clash Plus，再按平台与所需功能比较其他入口。导入格式的进一步区分见订阅链接与 YAML 导入说明。

二、通用字段：端口、模式与访问边界

通用字段决定本机程序怎样进入代理，以及内核收到连接后使用哪种处理模式。这里最容易混淆的是本地监听端口与远程节点端口：前者由设备上的内核提供，后者属于服务端连接参数。把节点服务端口填进系统代理设置不会自动建立连接；系统代理通常需要填写本机监听地址和对应的 HTTP 代理端口，而节点端口保留在节点定义内部。

选择监听入口，核对实际占用

对一般桌面教学配置，先使用一个混合端口更容易定位问题。只有应用确实需要独立入口时，再配置 HTTP 或 SOCKS 端口。不要让不同监听字段重复占用同一端口，也不要在已经运行图形客户端的情况下，启动另一份同端口内核。发生监听失败时，应先识别占用者；随意换端口后若忘记更新系统代理，只会把错误从启动阶段转移到连接阶段。

# 通用字段片段，监听端口仅供教学
mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

这里将监听限制为本机用途。bind-address 对各入口的具体影响需结合内核和客户端生成结果确认，不能仅凭文件判断外部可访问性。应用应连接 127.0.0.1:7890，而不是把它当成远程节点。桌面系统的代理设置、浏览器独立代理设置与终端环境变量可以互不相同，因此同一台设备上不同程序可能走不同路径。

模式选择与流量接管是两件事

rule 按规则顺序为已进入内核的连接选择目标；global 使用全局策略处理这些连接；direct 使用直连。全局模式不是操作系统层面的全量接管，不能保证所有程序都进入代理。反过来，开启 TUN 也不意味着所有请求都走远程节点：流量进入内核后，仍可由规则决定直连、拒绝或代理。

系统代理主要影响遵循系统代理设置的应用；TUN 通过虚拟网络接口及配套路由接管流量，可能需要管理员权限、服务组件或移动平台 VPN 授权。不要为了验证一个网页就同时改系统代理、TUN、DNS 和模式。先确认单个应用能通过明确的本地端口访问，再决定是否需要扩大接管范围，具体安装与授权步骤可回到模式与接管教程。

局域网开放、日志与 IPv6

只有其他可信设备需要使用本机代理时，才考虑开启局域网访问。此时还要检查监听网卡、防火墙入站规则和代理认证，并避免路由器把该入口转发到公网。代理入口与控制接口不是同一个服务；后者可能具有切换策略、读取连接和修改配置的能力。若没有远程管理需求，应保持控制接口仅本机可用，不要为解决连接问题而扩大管理权限。

log-level: info 适合日常观察。排错时临时提高日志详细程度，可以看到更多错误上下文，但日志可能包含域名、节点地址和连接元数据，分享前需要脱敏。排错结束再恢复日志级别，防止持续写入大量记录。日志是否落盘、保留多久、保存在哪里，通常还受客户端管理，不能只看内核的级别字段。

顶层 ipv6 与 DNS 区域的同名字段作用层面不同，操作系统本身也可能继续使用 IPv6。示例关闭它只是简化测试路径，不是通用网络优化建议。需要双栈访问时，应同时核对解析结果、路由、接管范围以及节点是否能到达目标；只改一个开关无法证明不存在绕过代理的连接。任何通用字段修改，都应以最终监听状态和实际请求路径作为验收依据。

三、DNS 处理：解析入口、上游与 Fake-IP

DNS 配置首先要回答谁发起查询、谁接收查询、怎样到达上游。内核开启 DNS 服务，不代表系统与全部应用会自动使用它；浏览器内置的加密 DNS、应用自己的解析器和其他 VPN 都可能形成独立路径。排查时应画出应用、系统解析器、内核 DNS、上游服务器之间的顺序，先确认请求真的进入目标入口，再讨论返回地址是否正确。

基础字段与解析依赖

# DNS 片段；不会自动改写操作系统的 DNS 设置
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"

listen 声明内核 DNS 的监听地址。示例使用本机非标准端口，适合显式查询测试，但多数系统网络设置不能直接填写这样的端口。要使普通应用使用它，还需要客户端提供的 DNS 接管、转发或 TUN 劫持机制；不要仅把系统 DNS 写成一个未在标准端口监听的地址。示例中的上游只是可替换对象，其可达性取决于当前网络。

nameserver 配置常规解析上游，default-nameserver 常用于解析上游 DNS 地址本身的域名。若加密 DNS 服务器使用域名作为地址，内核需要先知道该域名对应的 IP，才能建立加密连接。这个引导过程不能反过来完全依赖尚未建立的同一个解析通道，否则可能形成依赖环路。修改上游前，先确认它在当前网络中确实可达。

Fake-IP 保存的是域名映射关系

Fake-IP 模式可为域名返回一个虚拟地址，内核保留该地址与域名的映射。随后应用连接虚拟地址时，内核据此恢复域名信息并执行后续处理。虚拟地址不是目标网站的真实服务器地址，因此在系统查询结果中看到它，不应立即认定解析被污染。能否完成连接，还取决于相应连接是否被同一内核接管，以及映射是否仍然有效。

传统真实地址返回方式通常更容易兼容要求真实 IP 的程序，但连接阶段可能需要其他机制才能保留或恢复域名信息。选择模式时，应以应用兼容性和接管方案为依据，而不是把某种模式当作必然更快的选项。切换增强模式后，系统或应用仍可能缓存旧结果；先清理相关缓存、重建连接，再比较现象，避免把缓存差异误当成模式差异。

fake-ip-filter 用于排除不宜返回虚拟地址的域名，常见起点是局域网服务与依赖真实地址的应用。示例只说明列表结构，并不保证涵盖所有内网名称。特别是 .local 服务还可能依赖组播 DNS，不能靠添加排除项解决全部发现问题。排除虚拟地址也不等于指定直连：解析方式与连接策略需要分别检查。

按域名选上游与 DNS 泄漏判断

# 合并到现有 dns 映射内，不要再增加第二个 dns 顶层键
# 内网 DNS 地址仅为教学值，需要替换为实际可达地址
nameserver-policy:
  "+.corp.example":
    - 192.168.1.1

这段策略用于说明某些域名可以交给特定解析器，适合存在内部名称的网络。内网解析器必须知道该域名，并且能从设备当前网络到达。切换到外部网络后，原先可用的内网地址可能不再存在，不能把超时直接归因于远程代理节点。策略键的匹配语法也不是规则列表语法，不要将 DOMAIN-SUFFIX 规则原封不动放在这里。

在支持相关字段的 mihomo 中，proxy-server-nameserver 可用于代理节点服务器域名的解析；respect-rules 会让 DNS 上游连接遵循路由规则，需要特别注意节点解析与代理连接之间的依赖。fallback 也不应被简单理解为第一台服务器超时后的顺序备用，它可能结合过滤条件选择结果。未确认实现前，先采用较少的解析路径。

验证时分别测试普通域名、内网域名和需要代理的域名，记录解析结果与后续连接命中的规则。若只有局域网应用异常，先缩小排除范围；若所有请求都等待解析，再查上游可达性与依赖环路。虚拟地址的查询和连接过程可继续阅读Fake-IP 映射与排除项说明。

四、代理节点：协议字段与连接前提

proxies 是静态节点列表，每个节点描述一种到远端服务的连接方式。节点不是策略组，也不决定哪些网站使用它；只有被规则直接引用，或被策略组选择后，它才参与对应连接。排查节点定义时，应把服务地址、认证信息、传输方式和 TLS 参数分开核对，不要因为名称能够显示在客户端里，就认为协议参数已经通过连接验证。

通用字段与协议专属字段

# 节点教学片段；示例域名与密码不能用于实际连接
proxies:
  - name: "教学节点"
    type: ss
    server: edge.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

name 是本地引用标识，建议稳定且唯一；它不必等于服务器域名。type 决定内核使用哪种协议以及后续字段如何解释。server 和 port 必须与服务端实际监听位置一致，不能从网页地址或订阅接口路径推测。示例中的保留域名和教学密码需要由合法获得的真实参数替换，修改名称不会改善服务器连通性。

协议专属字段必须成套对应。Shadowsocks 的加密方式和密码要与服务端匹配；其他协议可能需要 UUID、认证口令、额外握手参数或不同的传输层设置。不能将某个节点的 type 改成另一个协议，却继续沿用其余字段。客户端能够识别分享链接，只说明它具有相应导入逻辑，最终仍要确认生成字段受当前内核支持。

TLS 名称与传输参数不能混用

# 独立的代理列表片段，不与前面的顶层 proxies 重复粘贴
proxies:
  - name: "TLS 教学节点"
    type: trojan
    server: edge.example.com
    port: 443
    password: "your-password"
    sni: edge.example.com
    skip-cert-verify: false
    udp: true

对采用 TLS 的协议，连接地址与证书验证名称可能相关，但并非总是相同。SNI 用于 TLS 握手中的服务名称选择，HTTP Host 和 WebSocket 路径则处于不同层面。服务提供方明确要求不同取值时应按其参数填写，而不是为了消除错误随意替换域名。出现证书错误还应检查系统时间、服务端证书和中间设备，不应长期关闭证书验证。

udp: true 表示允许使用节点支持的 UDP 能力，并不会给不支持 UDP 的服务端增加该能力。游戏、语音或其他应用异常时，需要同时检查应用是否进入代理、协议是否支持、服务端是否放行，以及所用接管入口能否处理该流量。网页测试通常只覆盖一部分传输路径，不能用一次网页成功来证明节点适合全部应用。

静态节点与代理提供器的取舍

少量固定节点可以直接写入 proxies，便于阅读和比对；周期更新的节点集合可以由 proxy-providers 管理，再由策略组通过 use 引用。提供器下载地址返回的内容必须符合其要求，通常节点集合与完整配置不是同一种输入。把完整订阅填进只接受节点集合的入口，可能导致字段结构不匹配，而不是网络下载故障。

提供器还涉及更新周期、缓存路径和健康检查。远程内容更新失败时，内核可能继续使用已有缓存，因此界面仍有节点不代表刚刚刷新成功。应检查最后一次加载结果和缓存内容，而非只数列表项。若需要通过代理下载提供器，又依赖该提供器才能获得代理，就会出现首次加载的依赖问题，需要保留可用的引导路径。

节点名称重命名后，要同步检查策略组成员、规则直接引用及客户端保存的选择记录。排错时先保留一个可信且参数完整的节点，确认服务状态和认证有效性，再逐步恢复集合。分享配置时删除订阅地址中的访问凭据、节点密码及可识别个人的信息；用于公开讨论的示例应改成教学值，而不是仅遮住截图中的一小段字符。

五、策略组：组织节点与保留规则入口

策略组是规则与节点之间的稳定接口。规则可以一直指向名为“出口选择”的组，而组内节点随着订阅更新或用户选择改变。这样既减少规则对具体节点名称的依赖，也让不同业务能够使用不同出口。策略组本身不会凭空建立远程连接；最终必须落到实际节点或内置目标。阅读策略组时，应同时看类型、成员来源和最终落点，而不只看界面中的名称。

手动选择组与内置目标

# 此片段不依赖外部节点，便于验证组与规则的引用
proxy-groups:
  - name: "出口选择"
    type: select
    proxies:
      - DIRECT
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.com,出口选择
  - MATCH,DIRECT

select 组让用户手动选择成员。这里故意只放直连与拒绝两个内置目标，使结构测试不依赖远程服务；选择拒绝后，命中该组的连接会被阻止，而不是自动转向其他成员。实际使用时，可将已经定义的节点名加入列表。配置中的成员顺序与客户端保存的选择状态可能共同影响首次显示，不应假定每次重载都固定选中第一项。

DIRECT 表示由当前设备直接连接目标，REJECT 表示拒绝匹配连接。给组取名时不要复用内置目标名称，也不要把名称与协议类型混为一谈。规则目标写“自动选择”时，配置里必须存在完全同名的对象；一个字、空格或标点的差异都可能使引用失效。中文名称适合阅读，但更新链路越复杂，越需要保持稳定命名。

自动选择、故障转移与负载分配

# 前提：proxies 中已经定义并验证过“教学节点”
proxy-groups:
  - name: "自动选择"
    type: url-test
    proxies:
      - "教学节点"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

  - name: "出口选择"
    type: select
    proxies:
      - "自动选择"
      - "教学节点"
      - DIRECT

url-test 通过指定地址进行连通性测试，并依据测试结果选择成员。示例的间隔与容差只是教学数值；容差用于减少细小差异造成的频繁切换，不是对真实业务延迟的承诺。测试地址需要从节点出口访问，因此测试失败可能是该地址受到限制，并不一定代表节点完全不可用。只有一个成员时，自动选择也没有可比较的替代出口。

fallback 更接近按成员顺序进行可用性故障转移，适合主备关系；load-balance 面向连接分配，具体策略与配置选项应按当前内核文档确认。负载分配通常不会把单个下载连接拆到多个节点，也不等于带宽相加。涉及登录会话或出口地址敏感的应用时，频繁变化的出口可能带来额外验证，应优先考虑稳定性。

健康检查只能反映特定时间、特定目标和特定测试方式的结果。它不能覆盖所有地区限制、UDP 能力、认证续期及长连接表现。不要通过极短测试间隔追求看似及时的状态：测试会消耗设备与节点资源，也可能在网络波动时产生更多切换。可先用手动组建立稳定基线，确认业务正常后再引入自动组，比较其实际收益。

提供器引用、嵌套与恢复选择

当节点来自代理提供器时，策略组通常通过 use 引用提供器名称，静态节点则通过 proxies 引用。两者引用对象不同，不能把下载 URL 填进成员名称位置。节点过滤还可能把所有成员排除，导致空组；因此更新后应同时检查提供器加载成功、筛选条件命中和组内实际成员，而不是只看订阅刷新提示。

策略组可以引用其他组，但依赖关系必须有终点。例如手动组引用自动组，自动组引用节点是清晰的层次；两个组互相引用则会构成循环。为了让排错路径可追踪，嵌套层级应尽量少。若界面显示“出口选择”已选中自动组，还应继续确认自动组最终选中了哪个节点，否则日志中的实际出口可能与用户直觉不同。

部分客户端或内核会保存策略选择，配置更新后尝试恢复原成员；成员改名或被删除时，恢复行为可能不同。更新规则和订阅前记录重要组的选择，更新后检查真实落点。若出现“规则命中正确但访问结果不对”，先检查该组是否选择了直连或已失效节点，再排查更深层的 DNS 与路由。规则与策略组的协作流程也可对照连接验证步骤。

六、规则语法：匹配条件、顺序与最终目标

rules 通常按从上到下的顺序匹配，命中后交给指定目标处理。排序就是逻辑的一部分：精确例外放在广泛规则之前，最终兜底放在末尾。不要把规则列表当作可以随意排序的分类表；一条位置过早的宽泛规则，就可能让后面的精细规则永远没有机会执行。修改前先明确要改变哪类连接，以及它原来命中的位置。

域名、地址段与兜底规则

# 局部规则片段：使用内置目标演示匹配顺序
rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,DIRECT

DOMAIN 用于精确域名，DOMAIN-SUFFIX 用于域名后缀及其子域，DOMAIN-KEYWORD 用于域名中的关键词。关键词范围通常比预期更宽，可能误伤包含相同字串的其他域名，明确知道后缀时优先使用后缀规则。域名规则不识别完整网页 URL 的路径、查询参数或页面内容，不能直接按某个网址目录分流。

IP-CIDR 用于 IPv4 地址段，IPv6 地址段使用相应的 IPv6 规则类型。示例中的私有地址范围并不代表已经覆盖所有本地通信，还需要按实际网络考虑其他特殊范围与路由安排。MATCH 不带匹配值，直接指定最终目标，应位于末尾。若把它放在第一条，后续普通规则就失去了作用。

域名信息与 no-resolve 的边界

域名规则能够匹配的前提，是内核在规则判断时拥有相应域名信息。应用若先自行解析，再只发送目标 IP，内核可能无法直接使用域名规则。Fake-IP 映射、代理协议携带的主机名或适用的嗅探机制可以提供线索，但不能保证恢复所有连接的原始域名。遇到域名规则失效，应先看日志中的目标呈现为域名还是地址。

地址规则可能为了判断目标所属地址段而触发解析。添加 no-resolve 表示不为该条地址规则主动发起域名解析，并不意味着关闭全局 DNS，也不会阻止后续建立连接时所需的解析。如果连接已经具有目标 IP，规则仍可使用它进行匹配。先放域名规则，再放必要的地址规则，可以减少不必要的解析依赖，但具体顺序仍应服从业务目标。

规则提供器与本地规则维护

# 前提：已在对应位置创建规则文件
rule-providers:
  local-policy:
    type: file
    behavior: classical
    path: ./rules/local-policy.yaml

rules:
  - RULE-SET,local-policy,DIRECT
  - MATCH,DIRECT

# rules/local-policy.yaml 的内容，不是主配置
payload:
  - DOMAIN-SUFFIX,example.com
  - IP-CIDR,192.168.0.0/16,no-resolve

规则提供器把匹配集合拆到独立文件，主配置负责给这个集合指定策略。上例使用 classical 行为，集合里的规则不再写最终目标；域名集合与地址集合则需要相应的行为和内容格式。远程规则还要核对下载格式、缓存路径与更新结果。扩展名相同不代表内容结构相同，把普通文本列表当成带 payload 的 YAML 会产生加载错误。

地理数据、进程名称和进程路径规则都依赖额外条件。地理分类受数据库覆盖与更新时间影响；进程规则受系统权限、平台以及接管方式限制，不能把某个平台的写法视为通用方案。维护规则时应记录添加原因，并使用最小匹配范围。验证新规则要新建连接，因为已经建立的长连接通常不会仅因规则重载而重新选择出口。

七、覆写与合并：保留订阅更新和本地修改

直接编辑订阅下载文件往往容易在下一次更新时丢失。覆写的目的，是把订阅负责的节点与基础规则，同设备自己的端口、DNS 或规则偏好分开管理。这里没有一套对全部客户端都相同的合并算法：有的提供字段替换，有的支持规则前置或后置，有的允许脚本处理完整对象。使用前应先确认入口处理的是 YAML 片段、完整配置还是可执行脚本。

标量、映射和列表必须分别理解

# 原始配置中的相关字段
mixed-port: 7890
mode: global
allow-lan: true

# 仅用于支持此类字段替换的客户端覆写入口
mode: rule
allow-lan: false

# 假设规则：同名标量由本地覆写替换
mixed-port: 7890
mode: rule
allow-lan: false

这个例子只展示标量替换：原配置的端口保留，模式与局域网访问被本地值替换。它不能证明嵌套 DNS 字段也逐项合并，更不能证明规则列表会自动追加。若客户端界面的通用设置在覆写之后再次写入，最终结果还可能变化。实际使用时，应对照客户端生成的最终配置，而不是从覆写入口的名称推测执行顺序。

映射合并存在浅层替换与递归合并之别。例如原 DNS 映射包含上游、过滤列表和监听地址，本地只填写 enable: true；如果整个映射被替换，其他内容就可能消失。如果使用递归合并，未提及的键可能保留。字段删除也不是简单写 null 就一定有效：有的机制保留空值，有的拒绝输入，有的提供专用删除操作。

列表的追加方向决定逻辑

规则、节点和策略组都是列表，但它们不能共享一套不加区分的追加逻辑。规则有顺序语义，把本地例外放在已有 MATCH 后面通常不会生效；节点列表需要注意名称重复；策略组列表不仅涉及组名，还涉及组内成员引用。不要把“支持合并”理解为能够自动处理同名节点、循环引用与规则优先级。

# 这是最终配置中的顺序示意，不是通用覆写指令
rules:
  - DOMAIN,printer.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,出口选择

上例假设原配置已经定义“出口选择”组，并且确实需要让打印机域名直连。把这一条放在前面，只处理规则层面的出口选择；如果打印机域名解析错误、组播发现失败或局域网路由不通，仍然需要分别处理。对存在更具体拒绝规则的配置，还要确认前置规则是否会意外放行原本希望阻止的目标。

建立可重复、可撤销的处理流程

建议分别保存订阅原文、本地覆写和最终运行配置。原文用于判断服务方是否变更结构，覆写用于追踪本地意图，最终文件用于内核测试。每次只新增一个处理步骤，并注明它依赖的组名或字段。若原文中组名被服务方调整，本地规则即使语法正确也可能失去目标，应在订阅更新后重新检查引用关系。

脚本覆写需要具备幂等性：同一份输入处理一次与重复处理，结果应保持一致。常见错误是每次执行都向规则列表插入同一条内容，最终越积越多；或直接修改共享对象，使后续步骤读到意外状态。还应防御字段缺失与类型变化，不能默认每份订阅都存在 DNS 映射或同名策略组。无法解释脚本行为时，优先使用更简单的字段操作。

客户端升级、内核切换和订阅更新都可能改变合并链路。正式应用前先在副本中生成结果，对比端口、模式、DNS、组名与末尾规则，并确认没有把已有提供器路径或安全设置清空。出现异常时，先禁用最近加入的覆写，恢复原始配置和已知可用选择，再逐项重启处理步骤。保留最小差异比反复复制整份配置更容易定位问题。

八、验证与排错：从语法检查到真实连接

验证应该分层进行：文件能解析，引用能加载，监听能启动，应用能进入入口，规则能命中，出口能到达目标。前一层通过不代表后一层成功。特别是配置测试命令主要检查格式与可加载性，并不会替用户完成所有节点的在线认证和业务测试。先记录故障发生在哪一层，再选择最短的验证路径，可以减少重复重装和无关参数修改。

使用同一内核检查最终配置

# macOS / Linux：当前目录已有可执行的 mihomo
# check.yaml 是导出的最终配置副本
./mihomo -t -f ./check.yaml

# Windows PowerShell：当前目录已有 mihomo.exe
.\mihomo.exe -t -f .\check.yaml

执行前确认命令指向与客户端运行环境一致的内核，并通过该可执行文件的帮助信息核对参数。图形客户端名称不等于可执行文件名称；系统里另一份同名程序可能支持不同字段。测试应在受控目录中进行，提供器、规则文件和数据库等依赖也要可访问。相对路径通常依赖内核工作目录或配置处理方式，不能只搬走一个主文件就认为测试环境相同。

遇到解析行号时，同时检查报错行及其前几行。未闭合引号、错误缩进和列表层级偏移可能到下一字段才被检测出来。引用错误则沿名称向上追踪，检查组名、节点名和提供器名；缺少资源时检查路径、权限与内容格式。不要把所有错误都归结为 YAML 缩进，也不要为了让测试通过而删除不理解的安全或路由字段。

按入口、规则、出口逐段验证

# 前提：mixed-port 为 7890，内核已成功启动
curl --proxy http://127.0.0.1:7890 --head https://example.com/

# Windows 使用 curl.exe，避免命令别名差异
curl.exe --proxy http://127.0.0.1:7890 --head https://example.com/

显式指定代理入口，可以暂时绕开系统代理设置是否生效这一变量。成功得到 HTTP 响应说明这一次请求完成了相应链路，但响应状态不必总是成功状态，也不能由此证明所有应用都被接管。测试域名只是普通连通性目标；需要验证特定业务时，应再使用该业务允许的实际地址，并在客户端连接记录中确认命中的规则与最终策略。

如果显式代理成功而浏览器失败，重点检查浏览器独立代理、加密 DNS、扩展与系统设置。如果两者都失败，先看内核是否监听、端口是否一致，再看 DNS 和远程连接错误。如果直连正常而代理节点超时，检查订阅有效性、节点地址、认证参数和上游网络，而不是立即修改整个规则体系。相关分层顺序见代理节点超时排查。

缓存、日志与安全回滚

更换 DNS、Fake-IP 模式或规则后，应重新发起连接。浏览器连接池、应用长连接、系统 DNS 缓存以及内核缓存可能让旧状态暂时继续存在。先关闭目标应用的相关连接，再使用系统或客户端提供的适当缓存清理方式；不要通过删除整个用户目录来处理一次缓存问题。对测试前后的请求分别记录时间，才能与日志中的事件准确对应。

日志应保留错误类型、发生时间、匹配规则与必要的连接阶段，同时去除订阅凭据、认证信息和不需要公开的域名。界面闪退与内核失败是不同分支：前者需要检查运行环境和界面组件，后者更应检查配置、权限与监听错误。客户端无法打开时，可先按启动失败与配置恢复步骤保留现场，不要直接清空数据。

回滚时先关闭最近启用的接管方式，恢复已知可用配置与策略选择，再检查系统代理和 DNS 是否留下手动设置。退出客户端不一定会撤销用户自己写入的网络参数，因此应保留修改前记录。最终验收至少覆盖一次普通访问、一次目标业务访问和一次局域网访问；确认日志与路径符合预期后，再恢复常用日志级别并备份这份配置。

若只是希望完成首次连接，请回到快速上手主线；若需要重新选择图形客户端，可在选型指南比较配置管理方式，再从下载页进入对应平台。本手册的目标是让每次修改都有明确前提、可观察结果与恢复方法，而不是要求把所有可选字段同时启用。