Clash YAML
配置文件参考

通用字段：端口、模式与控制接口

监听端口如何分工

port 提供 HTTP 代理监听，socks-port 提供 SOCKS5 监听，mixed-port 则让同一个端口同时接受 HTTP 与 SOCKS5。桌面图形客户端通常只需要一个 mixed-port，系统代理会自动指向它。若另一个程序明确要求 SOCKS5 地址，可以单独配置 socks-port。多个监听端口不能占用同一个端口号，也不能与系统里其他服务冲突。

redir-port 和 tproxy-port 主要用于 Linux 网关、路由器或透明代理规则，桌面用户不应仅为“覆盖更多流量”而随意开启。TUN 模式有独立的虚拟网卡和路由处理路径，也不等于简单增加一个监听端口。需要比较两种接管机制时，可阅读TUN 模式与系统代理区别，先确定流量从哪里进入内核，再选择相关字段。

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

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"

profile:
  store-selected: true
  store-fake-ip: true

局域网访问与绑定地址

allow-lan 决定其他设备能否通过当前设备的代理端口连接。设为 false 时适合单机使用；设为 true 后，还要检查操作系统防火墙、监听地址和局域网隔离设置。开放局域网访问并不会自动把手机或电视设置为代理，仍需在目标设备中填写运行 Clash 的局域网地址和监听端口。地址变化会导致连接失效，因此长期共享时应为主机设置稳定的局域网地址。

bind-address 用来约束监听范围。某些客户端会根据“允许局域网连接”开关自动生成该字段，因此文件中的值可能在启动时被界面设置覆盖。排查时应查看实际监听地址：若只监听 127.0.0.1，其他设备无法访问；若监听所有接口，则应确保控制接口和代理端口没有被直接暴露到不可信网络。代理监听与外部控制接口是两套服务，不应混淆。

运行模式、日志与状态保存

mode: rule 按 rules 自上而下匹配，是日常配置的主体。global 会把流量交给全局策略，适合临时验证某个节点是否可用；direct 让请求直接连接，适合确认问题是否由代理路径引起。图形客户端的模式按钮通常会在运行时切换状态，未必回写订阅原文件。因此不要只看文件里的 mode，还要看客户端当前界面。

log-level 常用 info，排错时可临时提高到 debug，完成后恢复，避免日志过多干扰判断。ipv6 控制内核是否处理 IPv6 相关能力，但它不能修复本地网络本身缺少 IPv6 路由的问题。开启后若出现连接等待，应检查 DNS 是否返回 IPv6 地址、系统是否有可用 IPv6 出口，以及规则是否覆盖对应地址。

external-controller 提供界面与内核通信的控制地址，通常绑定本机回环地址。secret 是控制接口的访问凭据，示例值必须替换。它不是代理节点密码，也不会参与远端连接。profile.store-selected 可保存策略组选择，profile.store-fake-ip 可保存 Fake-IP 映射状态。若订阅更新后策略选择总被重置，应同时检查客户端自己的持久化选项，而不是只修改 YAML。

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

节点对象的共同结构

proxies 是静态节点列表，每个列表项至少包含名称、类型、服务器地址和端口，再按协议补充认证与传输字段。name 是整个配置中的引用标识，策略组通过它找到节点。重名节点会导致选择和覆写结果不确定，因此订阅合并后应检查名称是否唯一。server 可以是域名或 IP，port 必须与服务端实际监听一致。

协议类型决定可用字段，不能把一种协议的参数机械复制到另一种协议。加密方式、用户标识、传输层、TLS 和服务器名称都必须与服务端设置一致。客户端能够加载 YAML，只表示语法和字段结构基本有效，不表示远端认证一定成功。日志中的握手失败、认证失败、连接拒绝和超时分别指向不同阶段，应按错误阶段处理。

proxies:
  - name: "SS 演示节点"
    type: ss
    server: ss.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: service.example.com
    skip-cert-verify: false
    udp: true

  - name: "Hysteria2 演示节点"
    type: hysteria2
    server: hy2.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false

认证、TLS 与传输字段

Shadowsocks 节点常见字段包括 cipher、password 和 udp。加密方法必须与服务端相同，名称相近也不能互换。Trojan 类节点依赖 TLS，除密码外还经常需要 sni。SNI 表示握手时使用的服务器名称，它可能与连接地址相同，也可能由服务提供方指定。填写错误时，TCP 连接可能成功，但 TLS 握手会失败。

skip-cert-verify 控制证书验证。正常配置应保持 false，优先修正服务器名称、系统时间和证书链问题。把它改为 true 只能用于定位证书验证是否为故障点，不应作为通用修复。系统时间偏差、受限网络拦截和错误 SNI 都可能产生证书相关报错。只看“连接失败”四个字不足以判断原因，必须结合日志中的握手阶段。

VMess、VLESS、TUIC、Hysteria2 等类型还可能包含用户标识、网络类型、WebSocket 路径、HTTP 头、流控或拥塞控制字段。字段集合随内核能力和服务端部署方式变化。手工迁移节点时应以原始订阅和当前内核文档为准，不要仅凭另一个节点的外观补字段。关于原版 Clash、Meta 与 mihomo 的名称和兼容关系，可阅读内核版本选型说明。

proxy-providers 的按需加载

节点较多或需要远程更新时，可以使用 proxy-providers。提供者是节点集合，策略组通过 use 引用它。常见类型为 HTTP 或本地文件，远程提供者包含地址、更新间隔、保存路径和健康检查。保存路径应位于客户端允许写入的位置；容器或服务模式下还要确认目录权限。远程地址中的查询参数可能包含访问凭据，不应写入公开日志或公开示例。

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

proxy-groups:
  - name: "订阅节点"
    type: select
    use:
      - provider-main
    proxies:
      - DIRECT

interval 是刷新间隔，不代表每次启动都一定立即下载。客户端还可能有自己的更新按钮和缓存策略。health-check 用固定地址检查节点可达性，结果用于界面展示或自动策略选择，但单一检测地址不能代表所有网站都可访问。检测失败时先确认测试地址在当前网络中可达，再判断节点是否故障。

proxies 与 use 可以在同一策略组中共同出现：前者列出固定节点或内置动作，后者引入提供者集合。覆写工具处理这两类字段时行为可能不同，追加静态节点不一定会自动加入提供者。订阅更新后节点消失，通常应检查远程提供者是否刷新成功、保存路径是否可写、策略组是否仍引用正确的提供者名称。

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

规则按从上到下的顺序匹配

rules 是有序列表。请求遇到第一条匹配规则后即停止继续检查，因此具体规则应放在宽泛规则之前，末尾使用 MATCH 承接其余流量。若把 MATCH 放在顶部，后续规则永远不会生效。若先写宽泛的域名后缀，再写其子域名的特殊规则，子域名也会被前一条提前接走。

规则通常由“类型、匹配值、策略目标”组成，部分规则还可以附加参数。逗号是字段分隔符，策略名称必须在 proxy-groups 中存在，或使用 DIRECT、REJECT 等内置动作。规则行中的多余空格可能成为值的一部分，手工编辑时应保持格式统一。

rules:
  - DOMAIN,api.example.com,节点选择
  - DOMAIN-SUFFIX,example.com,节点选择
  - DOMAIN-KEYWORD,example,节点选择
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - PROCESS-NAME,example-app.exe,DIRECT
  - GEOIP,CN,DIRECT
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,节点选择
  - MATCH,节点选择

域名、地址与进程规则

DOMAIN 只匹配完整域名，适合单个主机；DOMAIN-SUFFIX 匹配指定域名及其子域，适合完整站点范围；DOMAIN-KEYWORD 只要域名包含关键词就可能命中，覆盖范围最宽，也最容易误伤。能用完整域名时不要使用关键词，能用明确后缀时不要写过短的片段。

IP-CIDR 和 IP-CIDR6 按目标地址段匹配。局域网、容器网段和公司内网通常应优先直连，但地址范围必须符合实际网络。no-resolve 表示匹配时不为取得 IP 而额外解析域名，可避免不必要的 DNS 查询。它不表示禁止已有 IP 流量，也不会改变应用自身已经完成的解析。

PROCESS-NAME 和进程路径类规则依赖平台能力、权限与接管方式。系统代理模式下，并非所有流量都能可靠获得进程信息；移动平台也可能不支持同样的进程规则。跨平台配置应把域名和地址规则作为基础，进程规则作为特定设备上的补充。出现桌面端命中而手机端不命中时，先检查规则类型是否具备平台可移植性。

GEOIP 根据 IP 数据库分类，GEOSITE 或规则集则按域名集合分类，具体可用能力取决于内核及数据文件。数据库规则方便覆盖大范围目标，但分类数据存在更新周期，不能替代明确的业务规则。需要强制某个域名走指定策略时，应把它的精确规则放在数据库规则之前。

rule-providers 管理大型规则集

大量规则适合放入 rule-providers。每个提供者需要名称、类型、行为、来源、保存路径和更新间隔。behavior 决定内容格式：域名集合、IP 地址段或传统规则行不能混用。提供者下载成功不代表已参与分流，还必须在 rules 中使用同名 RULE-SET。

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example/private-domain.yaml"
    path: ./rules/private-domain.yaml
    interval: 86400

  service-domain:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/service-domain.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,节点选择
  - MATCH,节点选择

domain 行为适合域名或域名后缀集合，ipcidr 适合地址段，classical 允许传统规则表达式。远程内容格式必须与声明一致。若提供者文件本身包含完整 payload 结构，保存后由内核按对应格式读取；若把普通订阅文件误当规则集，配置会在解析阶段报错。

规则集刷新失败时，先看网络请求状态，再看保存目录权限和文件格式。旧缓存仍可能继续工作，因此“当前还能访问”不能证明更新成功。服务模式下相对路径以运行目录或客户端配置目录为基准，不一定是 YAML 文件所在目录。迁移设备后规则提供者失效，路径差异是高频原因。

验证规则命中而不是凭结果猜测

客户端连接记录通常会显示目标域名、命中规则和最终策略。测试时应先清除浏览器已有连接或使用新的请求，否则复用连接可能继续沿用旧策略。修改规则后重新载入配置，再查看新连接是否命中新规则。只看网页能否打开，无法区分它走了直连还是代理。

自定义规则应从少量精确条目开始。先写一条明确域名规则，确认命中，再逐步扩大到后缀或规则集。若新增规则导致大量网站异常，立即检查是否使用了过短的关键词、过宽的地址段或提前出现的 MATCH。规则分流的核心不是数量，而是顺序清晰、目标存在、范围可解释。

配置检查、载入流程与故障分层

先检查语法，再检查网络

配置故障应按固定顺序处理：文件编码与 YAML 语法、字段结构与引用、监听端口、DNS、节点连接、策略组、规则命中、应用接管。上一层没有通过时，不要跳到下一层。语法错误会让整个配置无法载入，节点错误只影响对应连接，规则错误则可能让流量走错策略。分清故障范围，才能避免无目的地更换所有设置。

图形客户端通常提供配置检查或重新载入按钮。服务端和命令行环境可使用当前内核提供的测试参数，但具体可执行文件名与参数应以安装包内说明为准。检查命令必须指向实际配置目录；相对路径错误时，可能测试了另一份同名文件。看到“配置有效”后仍需观察启动日志，因为端口占用、目录权限和网络连接属于运行阶段问题。

# 示例：先进入实际配置目录，再调用当前内核的配置检查参数
cd /path/to/clash-config
mihomo -t -d .

# 查看本机端口是否已被占用时，可按操作系统使用对应工具
# Linux
ss -lntup

# Windows PowerShell
Get-NetTCPConnection -State Listen

解析错误的常见位置

报错包含行号时，应同时查看该行和它上方数行。YAML 解析器往往在无法继续理解时才报错，真正问题可能是前一行漏了引号、冒号后缺空格或列表缩进中断。若提示映射键重复，搜索同一层级的同名字段；若提示类型不符，检查原本应为列表的位置是否少了短横线，或整数是否误写成了对象。

从聊天软件或富文本复制的内容可能包含全角冒号、弯引号、不间断空格和不可见字符。最稳妥的处理方式是在纯文本编辑器中重新输入问题行。中文策略组名称可以正常使用，但标点应保持普通半角 YAML 分隔符。注释必须从井号开始，并与有效值保持适当空格。

配置能解析但提示目标不存在时，检查节点名、提供者名、策略组名和规则集名。常见情况包括策略组引用已被订阅更新改名的节点、规则指向被覆写删除的组、RULE-SET 名称与提供者键不一致。搜索名称时应包含引号内的完整文本，注意末尾空格和形似字符。

端口、系统代理与 TUN 的分支

客户端显示运行但应用无法联网，先确认监听端口是否存在，再核对系统代理地址。若 YAML 的 mixed-port 已改为新值，而系统代理仍指向旧值，浏览器会立即连接失败。若只有不遵循系统代理的应用无法接管，说明基础代理可能正常，需要评估 TUN，而不是继续修改节点协议。

开启 TUN 后完全断网，应检查权限、虚拟网卡、路由、DNS 接管和其他网络软件冲突。先关闭 TUN，确认系统代理路径可工作，再单独处理 TUN。若关闭客户端后仍无法上网，检查系统代理是否残留开启、虚拟网卡路由是否恢复。不要在同一测试中同时启用多个代理客户端，它们可能竞争系统代理、端口和路由。

节点可用性与规则命中的验证

节点测试失败时，先区分 DNS 解析失败、TCP 连接超时、连接拒绝、TLS 握手失败和认证失败。解析失败检查节点服务器域名与 proxy-server-nameserver；超时检查网络和远端地址；拒绝通常表示目标端口没有接受连接；握手失败检查系统时间、SNI 和证书；认证失败检查密码、用户标识和协议字段。不同错误不能用同一种修复方式处理。

节点测试成功但目标网站失败时，查看连接记录中的命中规则和策略。若命中 DIRECT，问题在规则顺序或模式；若命中预期节点，继续检查目标域名解析、节点出口和网站侧限制。临时切换到全局模式可用于区分规则问题，但测试后应恢复规则模式。全局模式能访问并不表示原规则正确，只说明某个代理路径可用。

建立最小可工作配置

复杂配置无法定位时，可从一个端口、一个节点、一个手动策略组和两条规则开始。确认它能载入并连接后，依次加入 DNS、自动策略、规则提供者和 TUN。每加入一层就保存可工作的副本。这个过程比在数千行订阅中反复猜测更快，也能明确客户端与内核实际支持哪些字段。

最小配置测试使用的节点必须确认信息完整，测试域名也应稳定。若最小配置仍失败，问题多半不在规则集，而在节点、系统网络、权限或客户端安装。此时可回到使用文档核对初始化步骤，或阅读订阅、模式与连接状态十问。需要重新安装时，从下载中心选择对应平台，桌面与移动平台均优先查看 Clash Plus。

完成排错后，应把临时的 debug 日志、宽泛测试规则和证书验证变更恢复到正常设置。删除不再使用的端口、重复策略组与失效提供者，给自定义部分写简短注释。配置的长期可维护性取决于每个模块都有清晰职责，而不是字段数量。能够说明每条规则为何存在、每个组引用谁、每个 DNS 解析器负责什么，才是一份可持续更新的配置。

从可运行配置继续

尚未安装客户端时，先按平台取得安装包；已完成安装但不熟悉界面操作时，按快速上手流程导入订阅、选择策略并验证连接。

前往下载中心 查看使用文档