Clash 配置文件参考

YAML 结构与配置入口

配置文件的核心是描述监听入口、解析方式、可用出站和分流顺序。文件能被 YAML 解析，只说明格式成立，不代表节点能够连接，也不代表所有字段被当前内核支持。排查时应依次区分语法错误、字段语义错误和运行环境错误，避免把网络超时归因于缩进，或把策略组名称错误当成订阅失效。

顶层映射与嵌套层级

常见顶层字段包括 mixed-port、mode、dns、proxies、proxy-groups 和 rules。顶层键从行首开始，子字段按固定空格数缩进。通常统一使用两个空格，不能用制表符代替。列表项以短横线和空格开头；同一个节点的名称、协议、地址和端口必须属于同一个列表项。

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

proxies: []

proxy-groups:
  - name: 默认出口
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,默认出口

上面是一份直连验证用的最小配置，不包含远程代理服务。它适合确认监听、策略引用与规则加载流程是否正常，不能据此判断远程节点可用性。proxies: [] 表示空节点列表；策略组引用内置出站 DIRECT，最后的规则引用已经定义的组名。实际加入节点时，应先添加节点，再把名称加入组内。

字符串、列表与布尔值

端口、间隔等数值通常不加引号，开关使用 true 或 false。节点密码、带特殊字符的名称、规则字符串和 URL 可以加引号，以减少冒号、井号或解析器差异带来的歧义。井号在合适的位置表示注释，因此密码包含井号时更应明确使用字符串。单引号字符串中的单引号需要写成两个；双引号中的反斜杠则可能触发转义。

块列表与行内列表都属于 YAML 的合法写法，但维护长配置时，块列表更容易逐行审阅。节点也可以写成花括号形式，字段较多时仍建议展开。不要为了压缩行数混用多种风格，更不要把中文冒号、全角逗号或网页复制产生的不间断空格放进键名与分隔符之间。

文件位置与有效配置

客户端界面中的订阅原文、编辑器中的本地文件和内核最终加载的配置，可能是三个不同对象。订阅更新后，客户端还可能注入监听端口、控制接口和覆写规则。查阅文件前，应先确认当前激活的配置名称、更新时间以及是否存在合并脚本，再通过客户端提供的运行配置查看入口核对最终结果。

同一层级不要重复定义相同键。某些解析器会拒绝重复键，另一些会保留后一个值，结果难以预测。需要增加规则时，应修改原来的列表或使用客户端明确支持的合并入口，而不是在文件末尾再写一段 rules。配置之间也不能仅靠复制粘贴就自动完成语义合并。

保存文件时使用 UTF-8 编码，并确认扩展名确实为 .yaml 或客户端接受的格式，而不是隐藏了额外的文本扩展名。出现解析错误时，先查看日志指出的行及其前一段列表；错误经常发生在上一行缺少引号、缩进改变或列表项未正确闭合的位置。

端口、模式与接管边界

监听端口决定应用把连接交给哪里，运行模式决定内核如何选择出站，系统代理与 TUN 则决定流量如何进入内核。这三件事相互关联，但不能替代。只修改 mode 不会让所有应用自动使用代理；只开启系统代理，也不会保证不读取系统代理设置的程序进入内核。

HTTP、SOCKS 与混合端口

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
ipv6: false

端口被占用时，应先确认占用进程属于旧客户端、另一套代理工具还是系统服务。不要直接结束不认识的进程。调整端口后，需要同步修改系统代理、浏览器扩展、终端环境变量和应用内手动填写的代理地址。操作细节见7890 冲突定位与 mixed-port 修改步骤。

规则模式与全局模式

rule 按规则列表自上而下匹配，通常适合作为日常配置基础；global 使用全局策略选择，适合临时验证出站；direct 使用直连出站。切换模式只改变已经进入内核的连接如何处理，不改变操作系统的路由机制。客户端界面的模式按钮还可能覆盖文件字段，应以运行状态为准。

开启局域网共享时，需要允许局域网连接，并让监听地址覆盖相应网卡，例如按实际环境使用 bind-address: "*"。这会扩大代理服务的可访问范围，因此还应收紧防火墙来源、按需配置代理认证，并避免把端口转发到公网。仅把其他设备的代理地址填成主机 IP，不会自动开放监听。

系统代理与 TUN

系统代理依赖应用遵循系统的代理设置，覆盖范围清晰，适合作为第一次连接验证路径。TUN 通过虚拟网络接口接管流量，常需要管理员权限、路由修改与 DNS 配合。应用已经设置代理时再开启 TUN，可能形成重叠接管；应先记录现有状态，再一次只改变一种接管方式。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

这段 TUN 配置用于说明字段关系，不应在远程管理服务器上直接启用。自动路由可能影响远程会话、容器网络和企业 VPN。dns-hijack 处理进入接管范围的相应 DNS 流量，并不等于所有加密 DNS 都会被接管；具体还受系统路由、应用行为及内核支持情况影响。

顶层 ipv6 与 DNS 中的同名字段作用范围不同，不能只关掉其中一处就假定设备所有 IPv6 流量已经停止。需要 IPv6 时，应同时确认上游网络、节点能力和接管路由。进一步比较见TUN 模式与系统代理的工作机制。

DNS 解析与地址映射

DNS 配置应先保证解析链能够独立启动，再讨论分流与增强模式。请求超时不一定是节点问题：解析服务器不可达、加密 DNS 域名无法引导解析、节点服务器域名解析形成循环，都可能让连接在建立之前失败。排查时先区分目标域名解析、代理服务器解析和 DNS 服务自身的域名解析。

常用字段与启动链

enable 开启内置 DNS，listen 指定其监听地址。应用只有实际向该监听发送请求，或请求被接管到内置 DNS，相关配置才会生效。default-nameserver 可承担加密解析服务域名的引导解析，应使用内核支持的 IP 形式上游，避免再引入尚未建立的域名依赖。

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
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost"

该示例展示本机监听、引导解析与节点域名解析的分工；所列上游是否适合当前网络，需要实际测试。1053 不是操作系统默认的 DNS 端口，不能只写进文件就期待全部系统请求自动转入。若改为监听标准端口，还应检查权限、已有服务占用以及系统对解析地址的设置方式。

fake-ip 与真实地址解析

fake-ip 为域名分配映射地址，内核据此保留域名上下文，再在建立连接时选择实际出站。这有利于按域名分流，但某些局域网发现、地址比较或只接受真实 IP 的程序可能需要例外。示例网段用于内部映射，不是远程代理服务器地址，也不应直接作为其他设备的网关。

fake-ip-filter 用于让特定域名绕过该映射流程，其匹配规则应按当前内核文档核对，不要与路由规则中的 DOMAIN-SUFFIX 写法混为一谈。遇到兼容问题时，先对确切域名添加小范围例外，再观察应用是否恢复。把所有域名都排除，会使所选增强模式失去原本作用。

redir-host 返回真实解析地址，便于某些依赖真实 IP 的应用使用，但域名与 IP 的关联可能受缓存、应用自带解析和请求路径影响。两种模式不是速度排名。应根据接管方式与应用兼容性选择，切换后重建连接，并处理操作系统与应用中仍保留的旧解析缓存。

按域名选择上游

nameserver-policy 用于为指定域名选择解析服务器。企业内部域名往往需要企业 DNS，不能交给公共解析服务；局域网设备名也可能只在路由器上可查。下面使用保留域名说明结构，内网地址必须替换为当前网络真实存在且可达的 DNS 服务。

dns:
  nameserver-policy:
    "+.corp.example":
      - 192.168.50.1

这是一段应并入原有 dns 映射的配置，不是第二个顶层 DNS 声明。配置 respect-rules 让 DNS 连接遵循路由规则时，需要特别防止依赖循环，并明确安排代理服务器域名的解析路径。没有确认引导解析和出站依赖之前，不宜把所有解析请求都强行送入代理组。

如果普通应用正常，而启用了安全 DNS 的浏览器表现不同，应检查浏览器是否直接使用自己的加密解析服务。该路径可能绕过预期的系统 DNS 设置。先在单一测试应用内确认解析路径，再决定是否调整应用设置或接管策略，避免同时改变多个变量。

代理节点与协议字段

proxies 描述可用的远程出站，不负责定义何时选择它们。一个节点至少需要唯一名称、正确协议类型、服务器地址，以及协议要求的认证与传输参数。服务端地址和密码正确仍不代表配置完整；传输方式、TLS、服务器名称和路径不一致，都可能导致握手失败。

基础字段与命名引用

name 是配置内部的引用标识，也是策略组与界面的显示名称，应保持唯一且稳定。server 填服务器 IP 或域名，不能填带路径的网页地址；port 填服务端监听端口，不是本机混合端口。type 决定其余字段的解释方式，不能通过只改类型把一种协议转换成另一种协议。

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: proxy.example.net
    port: 443
    password: "your-password"
    sni: proxy.example.net
    skip-cert-verify: false
    udp: true

示例域名与密码仅用于展示字段结构，不能用于实际连接。Shadowsocks 的 cipher 与密码必须和服务端一致；Trojan 的密码、服务器名称与证书配置也要对应。不要根据客户端名称猜测协议参数，应以服务提供方的原始连接资料或兼容订阅为准。

TLS 与传输参数

TLS 服务器名称不一定等于连接地址，但必须符合服务端部署与证书要求。不同协议可能使用 sni 或 servername，不能机械地统一替换。证书错误首先检查设备时间、域名拼写、证书覆盖范围和服务端配置；关闭证书验证会降低身份验证能力，不应作为常规修复步骤。

WebSocket 节点还可能要求特定路径和 Host 请求头，gRPC 节点可能要求服务名称。这些参数不是任意的优化项，而是握手的一部分。节点资料写明某种传输时，应同时核对对应的嵌套选项。把另一个节点的路径复制过来，即便地址和密码相同，也可能收到拒绝响应。

协议兼容与分层排错

mihomo 与早期 Clash 内核的协议和扩展字段支持并不完全相同。订阅能在一个客户端导入，不代表换到另一个内核后仍能识别全部节点。选型时先确认内核能力，再确认客户端是否保留并正确传递字段；需要安装客户端可前往客户端下载页，普通用户可优先从 Clash Plus 开始配置。

排错应按域名解析、TCP 或 UDP 可达性、协议握手、认证和目标请求逐层推进。解析失败先查 DNS，拒绝连接先查端口与服务状态，TLS 错误先查名称和证书，认证失败再核对密码或标识。不要每次都把整个节点删除重建，否则容易丢失能够定位问题的日志线索。

udp: true 只是允许相应节点尝试处理 UDP，并不会让所有接管方式都自动支持 UDP。应用通过 HTTP 代理发送的请求与 TUN 接收的 UDP 数据路径不同；服务端、协议实现和网络防火墙也可能限制流量。测试时应先明确应用实际使用的协议，而不是只根据页面连接成功判断 UDP 可用。

策略组类型与选路逻辑

proxy-groups 把节点组织成可选择的出站集合。规则通常指向一个稳定的组名，由组决定具体节点，这样更新订阅后不必逐条改写规则。理解策略组时，应把手动选择、健康检查与实际业务请求分开：检测成功只是某个测试条件成立，不代表所有目标都能正常访问。

手动选择与自动选择

select 提供手动选择，适合顶层出口或明确指定用途。url-test 根据周期性探测结果选择候选项，tolerance 可减少微小差异造成的频繁切换。fallback 按列表优先级使用可用项，不以最短探测耗时作为首要选择依据。需要固定首选线路时，应先考虑这个优先级差异。

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

  - name: 故障切换
    type: fallback
    proxies:
      - SS示例
      - Trojan示例
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: 默认出口
    type: select
    proxies:
      - 自动选择
      - 故障切换
      - DIRECT

示例引用上一章定义的节点名；如果节点没有导入，需要先补齐或改成已有名称。测试 URL 是运行时探测目标，不是页面依赖资源，应确认它在当前网络与各个出站上适合使用。不同目标的响应行为不同，修改测试地址后，原有探测结果也不能直接横向比较。

检测间隔与可用性含义

interval 通常以秒为单位，tolerance 在相应自动测试组中通常以毫秒表示切换容差。降低间隔会增加探测请求和网络活动，不一定提高业务稳定性。移动设备还应考虑后台运行与电量影响。应先使用合理间隔观察，再根据确切故障恢复需求调整，而不是把所有数值都设得很小。

lazy 可按支持情况减少未使用组的主动检测，因此刚打开界面时没有新探测结果，不一定意味着节点故障。组检测、资源提供者健康检查以及用户点击的节点测速可能由不同机制触发。查看结果时要确认检测对象、最近执行时间与测试地址，避免把一处结果误认成全局状态。

负载分配与嵌套引用

load-balance 面向多个连接的分配，可根据具体策略维持一定的目标一致性或轮流使用候选出站。它不会把一个下载连接拆成多条线路来叠加速度。对来源地址敏感的登录、支付或长会话业务，频繁改变出口可能引发额外验证，应使用较稳定的组或单独规则处理。

策略组可以引用其他组，但应保持结构简洁，禁止形成循环引用。例如默认出口可以引用自动选择，自动选择则不应再引用默认出口。命名时也不要让组名与节点名重复，否则审阅与日志定位容易产生歧义。调整名称后，应同时查找规则、嵌套组和覆写脚本中的旧引用。

如果界面仍保留以前的手动选择，应检查客户端是否保存组选择状态，以及配置中的 profile.store-selected 是否参与恢复。文件中候选项的第一项，不一定等于此刻实际选择。完整类型对比与写法见url-test、fallback 与 load-balance 配置说明。

规则顺序与匹配语法

rules 通常按从上到下的顺序匹配，首先命中的规则决定出站。配置正确却走错线路时，优先检查较早的宽泛规则，而不是只确认目标规则是否存在。最终兜底通常使用 MATCH；它会接收前面没有命中的请求，因此放在列表中间时，后面的普通规则就失去执行机会。

域名规则与地址规则

DOMAIN 匹配指定域名，DOMAIN-SUFFIX 匹配该域名及其子域名，DOMAIN-KEYWORD 按域名中的关键词匹配。关键词规则范围较宽，不适合代替已经明确知道的域名集合。规则目标可以是内置出站、节点名或策略组名；实际维护通常使用组名，以便后续换线路而不改分流逻辑。

rules:
  - DOMAIN,router.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,默认出口
  - 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
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - MATCH,默认出口

示例把几个常见私有地址范围送往直连，并将其余请求交给默认出口。这不是适用于所有设备的完整局域网规则：企业网络、虚拟网段与特殊路由可能还需要额外处理。example.com 是演示域名；实际分流应根据真实目标及其依赖域名逐步补充，不宜直接照搬大范围关键词。

no-resolve 与域名上下文

no-resolve 表示该地址类规则不主动触发域名解析来完成匹配。如果连接已经带有可用的目标 IP，仍可能命中对应地址规则；它并不是禁止 DNS。遇到域名请求时，加不加这个选项会影响匹配过程和解析开销，因此不能把它当成每条规则都应附加的固定后缀。

GEOIP 依据地址数据库判断目标 IP 的区域归属，GEOSITE 则依赖相应域名分类数据与内核支持。数据库分类不等于服务的实际经营范围，也不能保证一个站点的全部依赖都属于同一集合。配置引用相关数据后，应确认文件存在、来源适配且更新成功，不能只看到字段被接受就认为数据已加载。

进程规则与接管范围

进程名称或路径规则需要当前平台与接管机制能够提供进程信息。路由器通常无法获知局域网另一台设备上发起请求的应用进程；某些移动系统也有权限限制。使用此类规则前先在连接详情中确认能看到进程字段，再判断应匹配名称还是完整路径，不要仅根据应用窗口标题填写。

规则只能处理已经进入内核的请求。某个程序在连接列表中完全没有记录时，应先检查系统代理、应用代理设置或 TUN 路由，而不是继续添加域名规则。如果列表中能看到请求，则核对目标域名、目标 IP、命中规则和最终出站，沿着这四项定位，通常比连续更换节点更有效。

规则验证的最小范围

验证一条规则时，先暂时缩小到单个域名和明确出站，确认命中后再扩大到后缀或规则集。网页常同时请求静态资源、接口和身份验证域名，只把主域名改成代理，可能仍存在部分资源走另一出口的情况。应根据连接记录补齐必要依赖，而不是把所有未知域名都加入同一个宽泛匹配。

修改规则后重新加载配置，再建立新的测试连接。已有 HTTP 连接复用、下载任务和实时通信会话可能继续使用旧出站，不适合作为新规则的唯一验证依据。常见连接问题可继续查阅FAQ 故障排查，接管方式的操作顺序则以使用教程为准。

资源提供者与更新机制

资源提供者把经常更新的节点或规则从主配置中拆出，使主文件保留稳定结构。proxy-providers 管理节点资源，rule-providers 管理规则资源，两者内容格式和引用位置不同。提供者下载成功，只表示取得了文件；还需要确认内容格式正确、被组或规则引用，并在当前配置中实际生效。

节点资源与订阅格式

节点提供者使用的 YAML 资源通常以 proxies 为主要结构。完整 Clash 配置、单独节点资源和 Base64 编码的节点链接列表并不等价。某些客户端支持导入转换，不代表内核的 HTTP 提供者也能直接解析同一种原始内容。导入前可参考订阅 URL、本地 YAML 与 Base64 格式说明辨认资源类型。

proxy-providers:
  远程节点:
    type: http
    url: "https://subscription.example.com/nodes.yaml"
    path: ./providers/nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: 订阅选择
    type: select
    use:
      - 远程节点

示例地址需要替换为服务方提供的兼容资源。path 是本地缓存位置，相对路径通常基于内核工作目录或客户端指定的数据目录，并非网页所在目录。目录不可写、多个提供者共用同一路径，都会造成更新或缓存异常。给不同资源使用独立文件名，可以减少误覆盖和排查成本。

外层 interval 控制资源更新周期，health-check.interval 控制节点探测周期，两者单位通常都是秒，但用途不同。订阅尚未更新不代表健康检查没有执行，健康检查成功也不表示订阅内容已经刷新。界面中的更新时间与探测结果应分别核对，不能用其中一个推断另一个。

规则资源与 behavior

规则提供者需要让内容格式、format 和 behavior 相互匹配。domain 面向域名集合，ipcidr 面向地址段集合，classical 则适合包含规则类型的条目。不要只改行为名称来迁就任意文件；资源实际内容不同，需要正确转换或选用相应格式。

rule-providers:
  本地直连:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/local-direct.yaml

rules:
  - RULE-SET,本地直连,DIRECT
  - MATCH,默认出口

对应的 local-direct.yaml 只存放匹配条件，不在每一项后面重复写出站；出站由主配置的 RULE-SET 行指定。下列文件展示 classical YAML 的基本结构，需实际保存到声明的路径。规则集中的先后次序与主配置中的引用位置都应保持清晰。

payload:
  - DOMAIN,router.lan
  - IP-CIDR,192.168.0.0/16,no-resolve

更新依赖与离线缓存

远程资源更新本身也需要可用的解析与网络路径。首次启动时如果资源下载必须依赖尚未取得的节点，可能形成启动依赖环。应保留可达的更新路径或有效缓存，并按客户端与内核支持情况安排下载出站。不要在未确认远程资源可取得之前，删除唯一可用的本地节点与缓存文件。

遇到更新失败，应分别查看 HTTP 状态、响应内容类型、解析错误和本地写入权限。服务器返回登录页面或错误页时，文件可能仍被下载，但不是有效节点或规则资源。订阅链接包含访问凭据，应只在可信的客户端或受控环境使用，不应提交给来源不明的在线转换服务。

覆写、合并与生效验证

订阅负责提供远程内容，覆写负责保留本地意图，两者应尽量分离。直接修改订阅生成文件，往往会在下一次更新时丢失；复制成完全独立的本地配置，则需要自行承担节点变化维护。合理的流程是明确哪些字段由订阅管理，哪些由本地设置接管，再检查最终运行配置是否符合预期。

字段归属与合并顺序

客户端可能先读取订阅，再合并界面设置，最后执行规则补丁或脚本；具体顺序并不统一。不要假定所有客户端都支持同一种覆写文件，也不要把其他客户端的脚本语法直接放进 YAML。Clash Plus、Clash Verge Rev 等客户端的入口应以实际界面为准，内核本身不会替客户端解释所有合并扩展。

标量、映射和列表需要分别处理。端口这样的标量通常被后一个值替换；DNS 映射可能按键合并，也可能整段替换；规则和策略组列表则可能被覆盖、追加或前置。合并工具如果没有明确承诺，不能推断数组会自动去重，更不能认为同名节点会按名称安全融合。

前置规则与稳定引用

自定义规则通常需要插在订阅兜底之前，而不是简单加到文件末尾。如果客户端提供前置规则入口，可用下面两行表达局域网直连意图；它们是规则列表项，不是通用的覆写文件格式。采用哪种外层结构，必须根据当前客户端的合并机制填写。

- DOMAIN,router.lan,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

本地规则尽量引用稳定组名。订阅更新后若删除或重命名某组，原来的规则可能无法加载；把规则写死到易变的节点名称上，维护成本更高。需要本地固定入口时，可以在客户端支持的覆写层建立自己的组，再引用订阅提供者，但要确保提供者名称也有稳定来源。

保存、检查与重载

提交修改前，保存当前可用配置及覆写设置副本。一次只调整一个功能域，例如先改端口并验证，再调整 DNS。拥有内核命令行环境时，可以使用测试模式检查配置；桌面客户端也可能提供内置检查功能。下面命令中的工作目录应与资源相对路径的实际基准一致。

mihomo -t -d ./profile -f ./profile/config.yaml

测试通过只说明配置能够被当前测试环境接受，不表示所有远程服务已连接成功，也不表示客户端运行时没有再覆盖字段。若依赖外部资源，应确认文件位置和可用性。之后回到客户端重载配置，查看启动日志，核对端口监听、DNS 初始化和提供者加载是否有错误，再发起新的业务连接。

回退与问题记录

配置重载失败时，客户端可能继续保留旧配置运行。界面仍可联网不代表新文件已经生效，应检查错误通知与当前激活状态。如果无法确认问题来源，先恢复最近可用副本，再逐项重放修改。涉及 TUN、系统代理或 DNS 时，还要核对系统层设置是否随回退恢复，避免文件回退而网络接管仍保持新状态。

有效的问题记录应包含所用客户端与内核名称、接管方式、出现问题的字段片段、日志中的第一条相关错误，以及复现前后的变化。不要只描述无法连接，也不要提交完整敏感订阅。常规问题先对照FAQ；需要重新走一遍安装与导入流程时，返回快速上手教程，无需为排错反复重装整个环境。