Clash YAML 配置参考

SECTION 01 / DOCUMENT MODEL

YAML 结构与配置来源

映射、列表与缩进层级

Clash 配置不是按行执行的脚本，而是一份描述监听入口、解析方式和转发决策的结构化文档。顶层字段决定全局行为，嵌套映射保存同一功能的参数，列表表达有顺序的成员。阅读时先看缩进，再看字段名。冒号后面的标量属于当前字段，下一行缩进的字段则属于父级映射；以短横线开头的条目属于列表，不能随意改成同级映射。

建议统一使用两个空格缩进，不使用制表符。同级字段必须对齐，但缩进深度本身并不代表优先级。比如 dns.enable 只有放在 dns 下面才具有预期含义；把 enable 移到顶层，文件可能仍能解析，却不再配置 DNS。错误定位不能只停留在语法检查，还要确认字段放在内核认识的位置。

mixed-port: 7890
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
proxies: []
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,PROXY

上例用于观察结构，策略组仅包含直连，不提供远程代理连接。proxies: [] 是空列表，不是字符串，也不是字段缺失。布尔值使用 true 与 false，端口通常使用整数。包含井号、冒号后接空格、星号或其他特殊字符的字符串建议加引号；密码即使看起来像数字，也应按字符串保存，避免解析器转换类型。

Profile、订阅与运行配置

在客户端中，Profile 是一份配置记录，可以关联本地文件或远程订阅。订阅下载得到的 YAML 通常包含代理条目、策略组和规则，但客户端还可能把监听端口、系统集成选项或覆写结果加入其中。内核实际读取的文件，是这些输入处理后的运行配置。编辑订阅缓存、编辑原始文件和编辑覆写内容，影响范围并不相同。

远程订阅更新时，直接写进缓存的修改可能被替换。因此，订阅负责更新的内容与用户需要长期保留的设置应分开管理。通用端口与日志级别适合由客户端统一管理，个人规则适合放在可持续应用的覆写层。具体合并行为由客户端实现，不能仅凭文件名称判断来源。需要比较差异时，应同时保存原始订阅与最终输出，而不是只看编辑器当前打开的标签。

文件编辑的基本约束

同一映射内不要重复定义相同键。两个 dns 段落不会可靠地自动合并，不同解析路径可能报错或仅保留其中一个。需要补充解析器时，应修改现有列表，而不是在文件末尾再写一份同名字段。规则列表同样只应有一个明确来源，避免订阅与本地改动分别生成两个顶层 rules。

保存文件时使用 UTF-8，并保留普通半角冒号与短横线。中文标点适合说明文字，不适合替代 YAML 结构符号。注释从井号开始，不会成为运行字段，但放在引号内部的井号属于字符串。复制示例后先检查空白字符，再检查内容引用；网页显示的视觉对齐不能代替编辑器中的实际空格。

配置文件路径由操作系统、安装方式和客户端设置共同决定，本手册不把某个用户目录写成通用路径。应从客户端提供的配置目录入口或日志中确认位置。多配置并存时，给 Profile 使用能表达用途的名称，并记录当前启用项。有关本地文件、远程订阅与配置切换的关系，可继续阅读Profile 基础与多配置管理。

SECTION 02 / LISTENERS AND MODE

监听端口与运行模式

入口协议与监听地址

代理端口用于接收应用交给内核的连接。port 提供 HTTP 代理入口，socks-port 提供 SOCKS 入口，mixed-port 在同一个端口接受 HTTP 与 SOCKS 请求。普通桌面使用通常选择混合端口即可，但应确认客户端实际写入的是哪一种字段。把网页服务地址填进代理端口位置，或把控制接口当成代理入口，都会导致协议不匹配。

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

这段配置将代理与控制入口限制在本机。需要让其他设备使用时，必须一并考虑监听地址、allow-lan、系统防火墙以及访问控制，不能只改一个开关。监听在所有网卡上意味着更多网络接口能够到达该服务。控制接口尤其不应直接暴露到公共网络；确有远程管理需求时，应配置认证并限制网络访问范围。

规则、全局与直连的区别

mode: rule 按规则列表决定出口，适合希望按域名、地址或规则集合分流的场景。mode: global 使用全局策略处理进入内核的连接，不代表系统中的所有应用已经被接管。mode: direct 让进入内核的连接直接访问目标，仍然经过代理入口的处理流程，不等于关闭客户端进程。

模式与系统代理属于不同层面。模式决定连接进入内核以后怎样转发，系统代理决定遵循系统设置的应用是否把请求交给该入口。部分程序使用自己的代理设置，部分程序忽略系统代理。遇到某个应用行为不同，应先检查入口覆盖范围，再检查规则。不能因为浏览器可访问，就推断其他程序也走了相同路径。

端口修改与进程边界

修改混合端口后，应用端的代理地址必须同步更新。客户端能够维护系统代理设置，但浏览器扩展、终端环境变量或开发工具中的固定端口不会必然跟随。常见现象是客户端运行正常，终端仍然连接旧端口。应分别检查 HTTP_PROXY、HTTPS_PROXY 与 ALL_PROXY 的实际值，以及应用内单独保存的代理选项。

端口冲突表示指定的本地地址与端口组合已经被占用，也可能是旧内核进程尚未退出。先停止重复客户端，再确认占用来源，不要直接把所有监听端口改成随机值。若日志明确指向权限错误，则检查运行权限或系统对端口的保留情况。端口号码并不具备连接质量上的优劣，选择它的依据是应用一致性与本地资源可用性。

日志级别建议日常保留 info，需要追踪匹配过程时短暂切换到 debug。详细日志可能包含访问目标，应在分享前删去订阅地址、认证信息与个人访问记录。首次安装阶段的端口与系统代理检查，可参照首次安装与初始设置，不必用整份订阅替换来处理一个本地入口问题。

SECTION 03 / NAME RESOLUTION

DNS 解析与 Fake-IP

解析器字段的职责

DNS 配置负责把域名转换为可用于连接与规则判断的信息。dns.enable 开启内核 DNS 功能，listen 指定它接收查询的本地地址，nameserver 列出常规上游。启用了 DNS 不代表系统中的查询自动全部交给内核；系统 DNS、应用自带加密解析器和 TUN 劫持设置，都会影响查询是否经过这条路径。

default-nameserver 常用于解析 DNS 上游本身的域名，使依赖关系能够启动。比如上游写成 HTTPS 域名地址时，必须先获得该域名的地址。它不是对所有查询强制优先使用的万能字段。另一个容易混淆的字段是 proxy-server-nameserver，用于代理服务器域名的解析，适合把代理连接启动所需的解析路径明确分开。

dns:
  enable: true
  listen: 127.0.0.1:1053
  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"
    - localhost

该片段是本地 DNS 服务示例，没有配置系统接管。上游地址应按所在网络的可达性选择；不能因为一个地址使用加密传输，就假定它在任何网络都能连接。若更改了本地监听端口，操作系统或转发程序也必须支持把查询送到该端口。常规系统 DNS 设置往往只能填写地址，不能直接附带自定义端口。

Fake-IP 与真实地址解析

Fake-IP 模式为域名分配一个供内核识别的映射地址，再利用映射保留域名信息。示例中的地址段用于这种内部映射，不是实际网站出口地址，也不应当作远程服务器填写。它的优势是请求进入内核时能够更稳定地关联域名，但依赖应用与系统的查询链路确实经过同一个内核实例。

redir-host 模式返回真实解析结果，处理链路与 Fake-IP 不同。某些依赖真实地址的本地服务可能更适合前者，但切换模式并不是 DNS 故障的通用修复。应先确认是查询失败、映射失效，还是应用绕过了内核。切换后需要考虑系统和应用中已有的 DNS 缓存，旧结果可能继续影响新连接。

fake-ip-filter 用于让特定域名不使用虚拟映射，适合确实存在兼容性需求的本地域名或服务发现域。过滤项过宽会削弱域名映射效果，因此应从明确受影响的域名开始，而不是把所有常见后缀一次性加入。过滤规则的具体匹配语义应结合当前内核文档确认，避免把普通域名列表直接当作任意格式的规则集合。

解析路径与分流闭环

当 DNS 请求本身需要遵循分流时，还要检查上游连接怎样出站。respect-rules 让 DNS 连接遵循路由规则，但需要明确代理服务器域名的解析方式，否则可能形成先有代理才有解析、先有解析才有代理的循环依赖。新增这个字段之前，应画出上游解析、代理握手和目标访问的先后关系。

nameserver-policy 可以按域名条件指定解析器。它解决的是使用哪条解析路径，不会自动为对应网站生成访问规则。DNS 分流与连接分流是两个阶段：前者选择解析服务，后者选择访问出口。一个域名使用某个解析器，并不表示它的实际连接一定使用相同出口。需要一致行为时，应同时核对两处配置。

排查时先保留一个可达的上游，确认基本查询，再逐项加入策略与过滤。遇到局域网名称无法解析，应检查路由器或本地 DNS 的职责，而不是把全部查询交给公共上游。若浏览器与命令行结果不同，分别清理它们的缓存并检查独立解析选项。DNS 修改应与端口、模式改动分批进行，这样日志与行为差异才有明确对应关系。

SECTION 04 / OUTBOUND DEFINITIONS

代理字段与远程提供器

通用字段与协议字段分层

proxies 用于描述可选择的出站代理。完整条目通常需要名称、协议类型、服务器地址与端口，再根据协议加入密码、用户标识或传输设置。名称承担内部引用作用，应与策略组成员引用保持一致；服务器字段描述实际连接目标，两者不能互相替代。为了避免把教学信息误当成可用服务，本节仅展示协议字段片段，不提供实际连接条目。

type 决定内核采用哪一种协议解析后续参数。不同协议即使共享 server 与 port，认证字段也不能混用。某些类型需要密码，某些类型需要用户标识，某些类型还要求指定加密方式。把另一协议的字段原样保留，可能导致字段被忽略，也可能直接造成配置加载失败。

# 仅展示 Shadowsocks 协议字段，不是完整代理条目
type: ss
server: proxy.example.com
port: 443
cipher: aes-128-gcm
password: "your-password"
udp: true

示例域名与密码均为教学值。实际使用必须由服务提供方给出一致的协议参数，不能根据端口推断类型。443 只是常见服务端口之一，并不自动表示启用了 TLS。udp: true 表示允许相关能力，仍取决于协议、服务器实现与完整网络路径，不能保证应用的每一种 UDP 通信都可用。

TLS 与传输层参数

对支持 TLS 的协议，服务器地址与证书验证名称可以不同。servername 一般用于指定握手使用的服务器名称，应与服务配置和证书匹配。skip-cert-verify 控制证书验证，不应当作为连接失败时的常规修复。证书错误可能来自域名填错、系统时间异常或服务端证书链不完整，绕过验证会掩盖这些问题。

WebSocket、HTTP 等传输设置通常放在协议支持的嵌套字段内。路径、请求头与握手名称分别属于不同层，不能看到它们都像域名就相互替换。若服务方提供原始 YAML，应优先保留该协议块的结构，再检查内核是否支持相关选项。订阅转换可能遗漏扩展字段，故原链接可用而转换结果不可用时，应比较结构差异。

proxy-providers 的职责边界

proxy-providers 将远程代理条目作为独立资源管理，策略组通过 use 引用提供器。它与完整 Profile 订阅不是同一个层级：完整配置可能还包含 DNS、规则与分组，而代理提供器的负载需要符合对应格式。将完整订阅地址直接填入提供器，并不能保证内核能够按代理集合读取。

proxy-providers:
  REMOTE:
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/remote.yaml
    interval: 86400
proxy-groups:
  - name: PROXY
    type: select
    use:
      - REMOTE

这里的 REMOTE 是提供器标识，不是单个代理条目。示例地址不提供实际配置，应替换为自己有权访问且格式兼容的资源。interval 的单位为秒，描述资源更新间隔；它与策略组的探测间隔作用不同。path 是缓存位置，其可访问范围还受内核工作目录和路径安全限制影响，桌面客户端可能另外管理这些文件。

提供器下载失败时，先判断是 URL 无法访问、认证失效、返回了网页，还是 YAML 负载结构不符合要求。缓存存在时可能继续保留旧内容，因此界面仍有成员不代表更新成功。远程订阅 URL 往往包含访问凭据，不能贴到截图或公开日志中。导入格式的区别与完整操作流程见订阅链接导入与格式说明。

SECTION 05 / POLICY GRAPH

策略组字段与引用关系

策略组不是接管入口

proxy-groups 把可用出口组织成可引用的决策单元。规则中的目标可以是策略组，组内再指向代理、内置动作或其他允许引用的组。它回答连接被送到这里以后怎样选择下一跳，不负责让应用开始使用代理。若应用请求没有进入内核，再完善的组结构也不会产生作用。

每个组需要唯一且稳定的 name，并通过 type 指定选择方式。select 提供手动选择，适合需要明确控制当前出口的场景。url-test 按探测结果选择成员，fallback 偏向按成员顺序维持可用出口，load-balance 按其策略分配连接。不同类型的选择逻辑不能仅凭界面的显示顺序判断。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
      - REJECT
rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,DIRECT

这是一份用于理解引用的片段。DIRECT 表示直连，REJECT 表示拒绝；选择后者会使命中该组的请求被拒绝。它们是内核内置目标，不需要在 proxies 中再次定义。实际配置可将已有合法出口加入组中，但不能把未定义的名称写进列表后期待内核自动创建。

成员来源与探测设置

proxies 表达显式成员列表，use 引用代理提供器。显式列表适合固定结构，提供器适合独立更新的资源集合。混用时应确认当前内核对组成员组合的处理方式，并检查提供器是否已经加载。一个组在界面上存在，不代表它一定具有可供选择的成员；空提供器、筛选条件过严或资源读取失败都可能使组变空。

自动选择类型通常需要 url 与 interval 等探测参数。探测地址应是稳定、体积小且能通过目标路径访问的 HTTP 服务，探测结果只反映到该地址的请求情况。它不能证明所有网站、认证流程或应用协议都可使用。测试地址被网络策略拦截时，也可能导致实际可用的成员被判为不可用。

tolerance 等参数用于减少频繁切换，是否适用取决于组类型与当前内核。不要为了让界面看起来变化更快而把探测间隔设置得过短。高频探测会产生额外请求，也可能让不稳定网络中的选择持续抖动。调整前先确定目标是自动择优、保持备用，还是按连接分配，选择类型比微调参数更重要。

分层设计与循环引用

分层策略组适合把用户选择与规则分类分开。例如，规则可以指向一个稳定的业务策略组，再由该组引用统一的手动选择组。这样远程资源变化时，不必逐条改动规则。但层级越深，故障定位也越复杂；应让每层具有明确职责，避免多层只做同样的转发包装。

组不能形成循环引用。甲组引用乙组、乙组又回到甲组，会让出站路径无法终止。大型配置中即使没有直接互相引用，也可能经第三层形成环。检查方法是从规则目标开始逐层展开，直到走到实际代理或内置动作。每条路径都应有终点，不应再次遇到已经经过的组。

对需要保持登录状态的服务，分散新连接可能导致出口变化，从而触发额外验证。应根据应用需求选择稳定路径，而不是把分配连接当作默认优化。组选择发生变化后，已有连接通常不会自动迁移，新连接才会使用新的决策结果。验证改动时应关闭目标应用旧连接再重试，并结合规则命中与最终出口链路观察，避免将旧会话误判为配置未生效。

SECTION 06 / FIRST MATCH

规则语法与匹配顺序

首条命中与兜底规则

在规则模式下，内核从上到下检查 rules，命中第一条适用规则后使用它指定的目标，不会继续比较后面的规则哪一条更精确。因此，优先级由位置决定，而不是由规则名称或域名长度自动计算。常见组织方式是将明确例外放前面，普通分类放中间，兜底规则放最后。

大多数规则采用类型、条件、目标的逗号分隔格式。MATCH 不带匹配条件，直接指定剩余连接的处理目标。它前面的规则处理明确分类，它后面的规则通常不会再有机会执行。排查某条规则为什么不生效时，先向上寻找更早命中的条目，而不是重复添加同一条规则。

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,github.com,PROXY
  - 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

这段规则要求已有名为 PROXY 的策略组。局域网地址示例不是所有私有网络范围的完整清单，部署时应根据实际网络补充。GEOIP 依赖对应地理数据可用，其分类也不等同于服务运营主体所在地。涉及明确业务需求时，优先使用可解释的域名或地址规则，而不是仅依赖地理推断。

域名与地址规则的差异

DOMAIN 匹配完整域名，适合单个主机的例外。DOMAIN-SUFFIX 匹配指定域名及其子域，适合整个服务域。DOMAIN-KEYWORD 按关键字匹配，范围容易超出预期，应谨慎使用。规则条件中通常不填写协议头、URL 路径或端口；把完整网页地址写进域名条件，并不会形成路径级匹配。

IP-CIDR 与 IP-CIDR6 根据目标地址范围判断。对原本以域名发起的请求，部分地址规则可能触发解析。no-resolve 用于避免该条规则主动触发这一步，不表示整条访问路径完全不使用 DNS。若连接本来已有目标 IP，地址匹配仍可进行；若只有域名而没有地址，该规则可能无法据此命中。

同一个网站可能访问多个域名，静态资源、登录与接口请求不一定共享后缀。只给首页域名写规则，不能保证整个使用流程走同一路径。排查时应观察具体失败请求，而不是看到网页能打开就结束验证。对于直接连接 IP 的应用，域名规则也未必有足够信息可用，需要结合实际连接目标确定策略。

规则提供器与负载格式

rule-providers 管理可独立更新的规则集合，通过 RULE-SET 在主规则列表中引用。提供器负责存储匹配条件，主规则负责指定使用位置与目标。一个规则集合即使下载成功，如果没有被主规则引用，也不会参与匹配。引用放在兜底之后，同样不会产生预期效果。

rule-providers:
  LOCAL-DOMAINS:
    type: inline
    behavior: domain
    payload:
      - "+.example.com"
rules:
  - RULE-SET,LOCAL-DOMAINS,DIRECT
  - MATCH,PROXY

示例使用内联域名集合，避免依赖外部文件。behavior: domain 的负载表达域名条件，不应直接放入带策略目标的完整规则行。ipcidr 与 classical 的负载语义不同，远程资源必须与声明匹配。修改提供器类型或格式时，应同步检查内容，而不是仅修改字段名称。

整理规则时，建议为每条本地新增规则记录原因，定期删除已经被上层覆盖的重复项。主规则不宜被多个覆写脚本无序追加，否则难以确定最终顺序。较长的类型说明、排序案例与命中分析见Clash 自定义规则语法与优先级。本页后续的覆写章节说明如何让个人规则在订阅更新后继续保留。

SECTION 07 / CONFIGURATION PIPELINE

覆写、合并与更新边界

区分客户端处理与内核字段

覆写是客户端在原始配置之外应用修改的一种处理机制，不是所有 YAML 文件共有的顶层字段。Clash Nyanpasu 的配置生成过程可能包含客户端管理项、合并配置与脚本处理。不同客户端的覆写入口、执行顺序与可用语法并不相同，不能把某个客户端的增强配置原样当成 mihomo 配置交给内核。

理解覆写时，应把输入、转换与输出分开。输入包括订阅或本地 Profile；转换包括字段覆盖、列表操作或脚本修改；输出才是内核读取的运行配置。排查时要确认改动在哪一层发生，并查看最终输出。只看覆写编辑框中有目标字段，无法证明它没有被后续步骤重新覆盖。

# 仅用于支持普通字段合并的覆写入口
mode: rule
log-level: info
dns:
  enable: true
  enhanced-mode: fake-ip

片段表达希望保留的字段值，不保证所有客户端采用相同合并算法。某些实现会递归合并映射，某些入口则替换整个对象。若整个 dns 被替换，原订阅里的上游列表、过滤项和策略也可能一起消失。因此应用后必须查看最终 dns 对象，而不是仅确认 enable 已经变为真。

列表追加、前置与替换

映射合并与列表合并必须分别理解。监听端口是单一标量，通常可以直接覆盖；规则与策略组则是有结构的列表，处理方式可能是整段替换、追加、前置，或由脚本自行决定。不要假设写一个较短的 rules 列表就会自动保留订阅的其余条目。若入口采用替换语义，原来的分类规则可能全部消失。

规则的顺序尤其重要。个人例外通常需要插入通用规则之前，追加到 MATCH 后方不会得到预期匹配。策略组则需要按唯一名称定位后再修改成员，不能简单重复插入同名组。对自动更新的配置，覆写过程还应具备幂等性：相同输入反复执行，结果不应不断增加重复规则或重复成员。

让订阅更新与个人设置分工

适合交给订阅管理的内容包括服务方维护的代理参数与资源集合。适合本地管理的内容包括本机端口、日志偏好和明确的个人访问规则。分工不意味着所有本地值都要覆盖订阅：服务方提供的协议参数若被过时覆写固定下来，更新后可能出现认证或传输不兼容。因此，应让覆写只承担必要差异。

脚本修改比普通字段合并更灵活，也更需要边界检查。处理前先确认目标数组存在，找到预期组后才修改，不应在找不到组时悄悄构造一个不完整对象。组名称变化是远程配置更新中的常见风险，脚本应产生可理解的错误或安全跳过，而不是生成无法加载的运行配置。执行顺序改变后，也要重新验证引用关系。

修改前保留一份可工作的 Profile 与覆写备份，并避免把含订阅凭据的文件提交到公开代码仓库。备份应覆盖配置来源、个人规则与必要的客户端设置；仅复制一份临时生成的运行文件，未必能恢复原来的更新关系。记录本次修改目标，例如只改变 DNS 或只前置一条规则，能够显著缩小回退范围。

应用覆写后按三层验证：先确认 YAML 可解析，再确认组与提供器引用完整，最后用新建连接验证实际行为。若更新后突然失效，先比较资源变化与覆写目标是否仍存在，不要立即删除所有个人设置。通过禁用单个处理步骤定位冲突，比同时替换订阅、内核与客户端更容易保留有效信息。配置来源的基本概念可回看Profile 管理说明。

SECTION 08 / VALIDATE AND ISOLATE

配置验证与故障定位

先验证输出，再验证流量

一份配置需要通过语法、语义与运行行为三层检查。语法检查处理缩进、引号与列表结构；语义检查处理字段支持、策略引用与资源格式；运行检查处理端口、网络可达性和实际匹配。某一层通过不能替代下一层。尤其是远程资源尚未加载、系统代理尚未接管时，文件成功读取并不表示应用已经能够使用。

能够直接调用 mihomo 的用户，可以使用测试参数检查指定文件。应使用客户端实际运行的内核，并在相同工作目录或明确的数据目录下测试，以便找到相对路径资源。桌面客户端已经提供测试或运行配置查看入口时，优先使用这些入口，避免另启一个进程与现有监听服务发生冲突。

# 在配置所在目录执行，按实际可执行文件位置调整命令
mihomo -t -f ./config.yaml

# Windows PowerShell，当前目录存在对应可执行文件时
.\mihomo.exe -t -f .\config.yaml

测试输出中的行号通常指向解析失败的位置，但真正原因可能在上一行，例如未闭合的引号或错误缩进。先检查首个明确错误，再重复测试，避免在多个由同一问题引发的提示之间反复修改。若提示不支持字段，应确认内核类型与当前选项支持情况，而不是把字段移动到其他层级碰运气。

按连接链路缩小范围

第一步确认客户端与内核正常启动，日志中没有监听失败。第二步确认应用确实连接正确的代理地址，必要时使用显式代理测试。第三步检查 DNS 是否能够通过预期路径解析目标。第四步查看规则与策略组的最终决策。第五步再分析远程协议握手与服务端响应。这个顺序可以把本地配置问题与远程连接问题分开。

# 只验证本机 HTTP 代理入口及后续请求路径
curl --proxy http://127.0.0.1:7890 --head https://example.com

# SOCKS 测试中由代理侧处理目标域名
curl --proxy socks5h://127.0.0.1:7890 --head https://example.com

命令需要系统已安装 curl，且端口与运行配置一致。测试网站仅用于观察请求链路；命令失败应结合具体错误判断，不能直接认定整个配置无效。连接被拒绝通常先检查本地监听，名称解析失败先检查 DNS，代理握手错误则继续检查协议入口与认证。不同错误发生在不同阶段，处理动作不应相同。

系统差异与最小回退

Windows 上的系统代理与防火墙配置、macOS 上的服务权限、Linux 桌面环境的代理设置，都会影响接管范围，但它们不改变 YAML 的基本层级。遇到系统提示，应按提示定位安装与权限层，不要在规则列表中寻找解决方式。macOS 相关设置路径可参照安装授权与钥匙串提示处理，是否需要某项权限以当前安装方式为准。

最小回退不是删除全部配置，而是撤销最近一项改动并保留故障证据。先关闭新加入的覆写，再恢复单个字段，最后才考虑切换到备份 Profile。每次只改变一个变量，并在新建连接上重复同一测试。若同时更新客户端、内核和订阅，很难判断哪一步改变了结果，也难以复现问题。

分享排错信息时，应保留错误文本、字段层级和操作顺序，去掉订阅 URL、密码、认证参数与个人访问目标。截图不能替代可读的错误信息，但也不应直接公开完整配置。问题定位完成后，恢复常规日志级别，删除临时测试规则，并记录最终有效改动。日常查阅可使用术语手册确认字段概念；需要重新完成导入与验证时，返回快速上手教程，避免把系统查阅步骤与首次使用流程混在一起。