Clash 进阶配置手册

CHAPTER 01 / POLICY GROUPS

策略组类型与实战

策略组位于规则与节点之间。规则的最后一个字段通常不是具体节点名，而是策略组名；策略组再根据用户选择、健康检查或故障状态决定实际出站。把规则直接绑定到单个节点虽然写法简单，却会让节点失效后的切换、不同业务的分流和订阅更新变得困难。较稳定的配置应先划分业务意图，例如“手动选择”“自动优选”“故障转移”“流媒体”“下载直连”，再让规则指向这些稳定名称。订阅中的节点名称可以变化，只要通过筛选重新进入对应策略组，规则层就不必跟着改动。

select、url-test、fallback 与 load-balance

select 是显式选择组，适合需要长期固定出口地区、手动确认账户登录位置或临时排障的场景。它不会自行改选，当前节点不可用时通常需要用户介入，因此组内应保留“自动优选”作为可选项。url-test 按固定地址发起连通性测试，并在候选节点中选择测得延迟较低者。测试延迟只反映探测目标和测试时刻，不等于所有网站的实际速度；间隔过短还会制造额外连接，所以桌面日常使用通常把探测间隔设为数分钟，而不是持续刷新。

fallback 按列表顺序选择第一个可用节点，适合主线路明确、备用线路只在故障时接管的情形。它强调顺序和可用性，不追求最低延迟。load-balance 会把不同连接分配给多个节点，适用于无登录状态、允许出口变化的并发任务；账户登录、支付、长连接和对来源地址敏感的服务不宜随意使用，因为同一业务的连接可能从不同出口发出。采用一致性散列策略可以降低同一目标频繁换出口的概率，但仍应先确认业务能接受这种行为。

proxy-groups:
  - name: 手动选择
    type: select
    proxies:
      - 自动优选
      - 故障转移
      - DIRECT

  - name: 自动优选
    type: url-test
    use:
      - remote-nodes
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    lazy: true

  - name: 故障转移
    type: fallback
    use:
      - remote-nodes
    url: https://www.gstatic.com/generate_204
    interval: 300
    lazy: true

use 引用的是 proxy-providers，适合让远程订阅节点自动进入策略组；proxies 则列出固定节点或其他策略组。两者可以按内核支持情况组合，但配置维护时应尽量保持来源清晰。节点很多时可用 filter 正则按名称筛选地区，例如把名称含“香港”或“HK”的节点纳入某组。反向筛选应谨慎，节点命名不统一时容易把候选全部排除。每次修改过滤条件后，都要在客户端的策略组详情中确认实际成员，而不是只看 YAML 能否加载。

分层策略避免循环引用

实战中可建立三层结构：底层是节点提供者，中层是自动优选或故障转移，上层是用户可见的业务组。规则只引用上层业务组，上层可以引用中层组和少量固定节点。任何策略组都不能间接引用自身。例如“手动选择”包含“自动优选”，而“自动优选”又把“手动选择”列为候选，就会形成循环。部分客户端会在载入时直接报错，部分界面只显示空组。排查时从报错组开始逐层展开引用，直到所有叶子都落到真实节点或 DIRECT、REJECT 等内置策略。

CHAPTER 02 / RULE PROVIDERS

规则集订阅化管理

当规则数量从几十条增长到数千条后，把全部内容直接写进主配置会降低可读性，也会让订阅更新覆盖本地修改。rule-providers 用于把域名、网段或经典规则拆成独立资源，由内核定期拉取并缓存。主配置只保留提供者定义、业务策略和规则集引用，规则内容可按广告拦截、私有网络、工作服务、流媒体等主题分别维护。这样既能单独更新某一类规则，也能在异常时快速停用对应引用，而不必重写整份配置。

behavior 与 format 的匹配关系

behavior 描述规则集内容的语义。domain 适合纯域名集合，条目通常是完整域名、域名后缀或内核支持的域名表达式；ipcidr 只处理 IPv4、IPv6 网段；classical 则保存带类型和参数的完整规则，例如 DOMAIN-SUFFIX,example.com、PROCESS-NAME,example.exe。选择错误时，文件可能成功下载却无法解析，日志会出现 payload 格式或规则类型错误。format 则说明资源是 YAML 文本、纯文本还是二进制规则格式，必须与远端文件实际内容一致，不能只根据扩展名猜测。

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/private-domain.yaml
    url: https://rules.example.invalid/private-domain.yaml
    interval: 86400
    health-check:
      enable: true
      interval: 600

  office-classical:
    type: http
    behavior: classical
    format: text
    path: ./rules/office.list
    url: https://rules.example.invalid/office.list
    interval: 43200

  private-network:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./rules/private-network.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,office-classical,工作服务
  - RULE-SET,private-network,DIRECT,no-resolve
  - MATCH,手动选择

示例域名使用不可解析的保留后缀，仅用于说明结构；部署时应替换为实际可访问且来源明确的规则地址。path 是本地缓存位置，同一配置中的不同提供者不能复用同一个文件，否则更新时可能互相覆盖。相对路径通常以配置工作目录为基准，而不是图形客户端安装目录。容器或系统服务环境还要确认运行用户对该目录具有创建和写入权限。若日志显示下载成功但写入失败，应检查目录权限、只读挂载和路径层级，而不是反复修改远端地址。

规则顺序比规则数量更重要

Clash 与 mihomo 通常按 rules 的顺序自上而下匹配，首条命中后停止。具体域名规则应放在宽泛规则之前，私有地址和本地服务通常应早于公网网段，最终以 MATCH 收口。若先写宽泛的地域网段或通配域名，后面的精细规则就不会执行。规则集之间同样存在覆盖关系：一个域名同时属于“工作服务”和“直连域名”时，排在前面的引用决定结果。调试规则时不要只确认某个条目存在，还要在连接详情或日志中查看实际命中的规则类型、规则载荷和目标策略。

no-resolve 常用于 IP 类规则，表示匹配时不要为了获得目标 IP 而额外解析域名。它能减少不必要的 DNS 查询，也可避免规则阶段改变原始域名处理路径，但不是所有规则都应机械添加。域名规则依赖域名本身，不需要该参数；需要依据解析结果匹配地域或网段时，禁止解析反而会让规则无法命中。正确做法是先明确该规则使用域名、目标 IP 还是进程信息，再决定是否跳过解析。

更新失败与缓存回退

远程规则更新失败不一定意味着现有流量立即中断。只要本地缓存仍存在且格式有效，内核通常可以继续使用旧内容；首次加载、缓存被清空或路径变化时则没有回退基础。维护前应记录规则文件的缓存目录和最后一次成功更新时间。遇到异常时依次检查系统时间、DNS 解析、远端响应状态、代理出站路径、证书错误和文件权限。若规则地址本身需要代理访问，而规则又决定代理访问路径，首次启动可能形成依赖环。可让规则下载使用已知可用的代理设置，或先准备本地文件完成启动，再恢复远程更新。

规则集并非越多越好。多个来源可能重复收录相同域名，维护口径也可能冲突。建议为每个提供者记录来源、用途、更新频率和目标策略，并定期删除不再引用的缓存。调整前可先在小型本地规则集验证行为，再把稳定条目迁移到远程资源。关于订阅结构和兼容差异，可继续阅读Clash 订阅格式详解，避免把节点订阅、完整配置和规则集订阅混为一类。

CHAPTER 03 / DNS PIPELINE

DNS 配置优化

DNS 配置决定域名如何获得地址，也会影响规则能否看到原始域名、连接是否绕过代理以及 TUN 模式下的兼容性。常见误区是把所有解析器堆进一个列表，希望数量越多越稳定。实际运行中，解析器协议、访问路径、地域响应和规则模式必须相互配合。排查时应把流程拆为四段：客户端是否把查询交给 mihomo、mihomo 选择了哪个 nameserver、查询通过直连还是代理发出、返回地址如何参与后续规则匹配。只有明确故障位于哪一段，修改才不会扩大变量。

基础解析器与业务解析器

default-nameserver 用于解析加密 DNS 服务器自身的域名等引导任务，通常应填写可直接访问的 IP 地址解析器，避免“先解析解析器域名”的循环依赖。nameserver 是主要查询来源，可以包含普通 UDP/TCP DNS、DoT 或 DoH。加密协议能保护到解析器之间的查询传输，但其连接仍需要正确路由。若 DoH 地址被规则分到代理，而代理节点域名又等待同一 DoH 解析，就可能在启动阶段卡住，因此节点域名和解析器域名的引导路径必须单独考虑。

proxy-server-nameserver 可专门负责代理节点域名解析，使节点连接不依赖面向业务域名的 Fake-IP 结果。nameserver-policy 则按域名指定解析器，例如让内部域名使用局域网 DNS、特定区域域名使用对应解析服务。策略匹配应从具体到宽泛，并留意规则集表达式是否受到当前内核支持。企业内网中，内部域名常返回私有地址；若交给公网解析器，不仅会失败，还可能把查询发到不应访问的解析路径。

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "ntp.*.com"
  default-nameserver:
    - 1.1.1.1
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver-policy:
    "*.corp.example.invalid":
      - 192.168.1.1

监听地址决定哪些设备可以使用该 DNS 服务。仅供本机使用时可绑定回环地址；需要局域网设备访问时才绑定所有接口，并同时检查防火墙、局域网访问许可和端口冲突。把 DNS 暴露到可被外部网络访问的接口会增加滥用风险，因此服务器环境应通过防火墙限制来源。ipv6 是否启用应依据本地网络和代理节点的 IPv6 能力决定。简单关闭 IPv6 可能掩盖路由问题，也可能让仅提供 AAAA 记录的服务不可达；开启后若上游或出口没有可用 IPv6，则可能出现连接先尝试 IPv6、等待失败后再回落的延迟。

redir-host 与 Fake-IP 的取舍

redir-host 返回真实地址，传统兼容性较直观，但在透明接管中，后续连接只携带目标 IP 时可能丢失域名信息，域名规则需要借助映射或嗅探恢复。fake-ip 为域名分配保留地址，内核通过映射表在连接到来时恢复原始域名，因此规则匹配通常更稳定，也能减少应用绕开内核自行连接解析结果的情况。它的代价是少数依赖真实 DNS 响应、局域网发现、时间同步、游戏或特殊设备服务可能不兼容，需要加入 fake-ip-filter。

过滤列表不应从一份巨大模板直接复制。条目过宽会让大量域名退出 Fake-IP 流程，削弱规则一致性；条目过窄则会留下具体应用故障。更可靠的方法是从默认配置开始，在日志中观察异常域名，并一次加入一个明确条目。修改后清理操作系统 DNS 缓存、应用缓存和内核映射，再重新建立连接，否则旧结果可能让测试结论失真。浏览器还可能启用自己的安全 DNS，应在排查阶段暂时确认其解析入口是否与系统一致。

DNS 泄漏与错误归因

所谓 DNS 路径异常，通常不是单一开关造成的。系统可能同时存在浏览器 DoH、系统 DNS、TUN DNS 劫持、容器内部解析器和局域网路由器转发。应先用日志确认查询是否进入 mihomo，再检查解析器连接走向。若日志完全看不到目标域名查询，问题在应用或系统层；若能看到查询但超时，检查上游可达性和路由；若解析成功却连接失败，再转向规则、策略组和节点，而不是继续替换 DNS。对比测试时每轮只更换一个解析器或一个增强模式，并保留时间点，便于与日志对应。

缓存可以降低解析延迟，却也会延长错误记录和旧地址的影响。域名切换服务端、规则刚修改或 Fake-IP 模式刚变更时，应同时考虑应用缓存、系统缓存和内核缓存。重启整个设备并不是唯一办法，优先使用客户端提供的 DNS 缓存清理功能，再关闭并重开目标应用。若故障只发生在某个浏览器、某个容器或某台局域网设备，应比较它们的 DNS 设置，不要把全局配置改到所有设备都承担额外复杂度。

CHAPTER 04 / TUN AND FAKE-IP

TUN 与 Fake-IP 的接管边界

系统代理只影响遵循代理设置的应用，TUN 则通过虚拟网络接口接管更广泛的 IP 流量。命令行程序、部分游戏、系统服务和不读取代理设置的软件，在系统代理下可能直接连接，而 TUN 能把这些连接送入内核规则链。接管范围扩大也意味着路由、DNS、防火墙、虚拟机和其他网络工具之间更容易发生冲突。启用前应先确认普通系统代理模式可以正常使用，确保订阅、节点和规则本身有效，再单独验证 TUN。否则节点故障与路由故障会叠在一起。

核心参数与系统差异

stack 决定 TUN 使用的网络栈实现。system 倾向使用系统网络栈，兼容性通常较直观；gvisor 使用用户态网络栈，在某些环境能改善隔离或特定协议表现，但也可能增加开销；mixed 会按流量类型组合处理。没有一种选择适用于所有系统，出现特定应用超时、UDP 异常或吞吐下降时，可在保持其他配置不变的前提下逐一测试。

auto-route 让内核自动添加路由，把目标流量导向虚拟接口。auto-detect-interface 用于识别真实出站网卡，笔记本在有线、无线、热点和 VPN 之间切换时尤其有用。Windows 上通常还需留意防火墙、网络配置文件和其他虚拟网卡；macOS 可能需要系统授权；Linux 服务环境则涉及运行权限、策略路由和防火墙框架。图形客户端往往会代为处理部分权限，但权限弹窗被拒绝、服务组件未启动或旧路由未清理时，界面上的开关仍可能无法真正接管。

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-redirect: true
  auto-detect-interface: true
  strict-route: true
  mtu: 1500

dns-hijack 把指定端口的 DNS 请求导入内核解析流程，是 Fake-IP 正常工作的关键环节之一。部分应用使用内置 DoH 时不会访问传统 53 端口，因此仅靠劫持不能覆盖所有查询。strict-route 可减少流量从其他接口绕行，但在虚拟机、局域网共享、企业 VPN 或多网卡环境中也可能阻断原本需要保留的路径。启用后若本地打印机、NAS 或公司内网突然不可达，应检查路由排除和私有网段规则，而不是直接把全部私有地址都交给代理。

MTU、回环与路由冲突

MTU 不匹配常表现为部分网站能打开、较大请求卡住、上传失败或特定隧道内连接超时。因为小数据包仍可通过，问题容易被误判为节点不稳定。可以在保持节点固定的情况下逐步降低 TUN MTU 做对照，但不应随意降到很小；过低会增加分片和处理开销。若只有经过另一个 VPN、移动热点或 PPPoE 的环境出现问题，应优先考虑底层链路额外封装造成的有效 MTU 减少。

内核自身发出的代理连接必须从真实接口出站，不能再次被 TUN 捕获，否则会形成回环。自动路由和接口检测通常会处理这一点，但自定义路由、容器网络、策略路由或多个透明代理同时存在时仍可能出错。典型现象是开启 TUN 后所有节点同时超时，关闭后立即恢复。此时应查看路由表和出站接口，确认代理服务器地址是否被排除、默认路由优先级是否正确，以及旧客户端残留的虚拟接口是否仍在工作。

Fake-IP 映射如何参与规则

应用向 DNS 请求域名时，内核返回 Fake-IP 并记录域名到该地址的映射。应用随后连接 Fake-IP，TUN 捕获连接，内核恢复域名并按域名规则匹配，最后再通过选定策略访问真实目标。这个过程中 Fake-IP 只存在于本机接管链路，不是实际远端地址。若应用缓存了旧 Fake-IP，而内核映射已因重启或配置切换丢失，就可能出现连接无法还原域名。清理应用连接和 DNS 缓存通常比继续增加规则更有效。

局域网服务、广播发现和需要真实地址返回的应用可通过 fake-ip-filter 排除，但还要确保对应私有网段规则位于合理位置。仅排除域名并不自动保证流量直连；解析得到私有地址后，后续规则仍可能把它送进代理组。反过来，仅添加私有网段直连，也不能修复依赖真实 DNS 回答内容的应用。排错时要把“DNS 返回什么”和“连接最终走哪里”视为两个独立问题。

若启用 TUN 后出现全局无法上网，可按固定顺序检查：先关闭 TUN 验证基础代理；再开启 TUN 但保持 DNS 配置不变；查看虚拟接口是否创建；确认默认路由和物理接口；检查 DNS 查询日志；最后测试固定 IP 与域名访问的差异。固定 IP 可通而域名不可通，重点检查 DNS；两者都不可通，重点检查路由、权限和回环。更通用的断网定位流程可参考Clash 运行日志怎么看。

CHAPTER 05 / DOMAIN SNIFFING

域名嗅探与目标还原

透明代理接收到的连接有时只包含目标 IP，没有原始域名。域名嗅探会检查连接初期的协议特征，从 HTTP Host、TLS ClientHello 中的服务器名称或支持的 QUIC 信息恢复域名，再让域名规则参与匹配。它主要解决“应用已经自行解析，内核只看到 IP”的问题，不是 DNS 的替代品，也不能从所有加密或非标准协议中恢复目标。配置时需要明确嗅探对象、端口范围和覆盖条件，避免把无关流量错误识别。

override-destination 的影响

只识别域名而不覆盖目标时，内核可用恢复出的域名完成规则匹配，但连接仍指向应用原先解析得到的 IP。启用 override-destination 后，内核可能根据嗅探结果重新确定目标，适合修复应用解析结果与代理侧访问路径不一致的情况。不过，CDN、私有解析、分流 DNS 和固定地址服务可能期望连接原始 IP；覆盖后若域名重新解析到另一地址，可能导致地区差异、证书问题或访问内部服务失败。因此应优先按协议和端口缩小范围，并为已知不兼容域名设置跳过列表。

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: true
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"
  skip-src-address:
    - 192.168.0.0/16
  skip-dst-address:
    - 10.0.0.0/8

parse-pure-ip 允许对目标为纯 IP 的连接尝试嗅探，正是透明接管中常用的能力，但会增加检查范围。force-dns-mapping 与 DNS 映射协同工作，适合需要从已有映射恢复域名的环境。协议端口应根据真实业务填写：HTTP 并不只运行在 80 端口，TLS 也可能使用 8443 等端口；反过来，把所有端口都交给所有嗅探器会增加误判和处理成本。应从常用端口开始，只有日志证明某个应用运行在其他端口时再补充。

嗅探不能解决的情况

加密客户端问候、ECH、非标准封装、证书固定和没有域名字段的协议，都可能让嗅探无法获得有效主机名。UDP 协议的信息也往往少于 HTTP。此时日志只显示目标 IP 并不意味着功能失效，而是连接本身没有可读取的域名。可以改用 IP 规则、进程规则或让应用 DNS 进入内核，而不是不断扩大嗅探范围。进程规则依赖平台权限和内核能力，服务器或移动系统的可用性可能不同，部署前应以客户端实际日志为准。

误嗅探通常表现为某个局域网设备、游戏、推送服务或特殊客户端在开启功能后失败。先关闭 override-destination 但保留嗅探，判断问题来自识别本身还是目标覆盖；再按源地址、目标地址或域名加入跳过项。局域网网段通常没有必要全面嗅探，因为内部 DNS 和固定地址更应保持原路径。跳过规则也不宜写成覆盖所有公网的宽泛网段，否则嗅探功能形同关闭。

与 Fake-IP 和规则匹配的协同

Fake-IP 已能通过映射恢复大多数由内核 DNS 处理的域名，因此嗅探更多是补足绕过系统 DNS的应用、历史连接或直接连接真实 IP 的场景。两者同时启用时，要观察日志中最终使用的是 DNS 映射域名还是嗅探域名。若同一连接得到不同结果，目标覆盖可能改变访问地址。可先采用“Fake-IP 负责常规域名，嗅探只检查常见 HTTP/TLS 端口且默认不覆盖”的保守方案，稳定后再为明确应用开启覆盖。

验证嗅探不应只看网页是否打开。应查看连接详情中的目标主机、命中规则和策略组：关闭嗅探时记录一次，开启后用同一应用、同一域名重新建立连接，再比较目标是否从 IP 变为域名、规则是否由 IP 类切换为域名类。已有长连接不会因为修改配置自动重建，需要彻底退出应用或等待连接关闭。浏览器的连接复用和 QUIC 会延长旧会话，因此测试时可使用新的隐私窗口并暂时清理站点连接状态。

域名嗅探属于补充手段。若 DNS 查询本来就能稳定进入内核，规则也能按域名命中，不必为了配置完整而扩大嗅探范围。每增加一种协议和端口，都应有明确问题作为依据，并记录启用前后的日志差异。这样在应用更新或网络环境变化后，才能判断旧的兼容性例外是否仍然需要。

CHAPTER 06 / PROFILE MERGE

本地覆写与多订阅合并

订阅更新会重新生成远程配置，直接在订阅文件里修改规则、DNS 或策略组，下一次更新时通常会被覆盖。可维护的做法是把远端订阅视为只读输入，把本地长期配置放入覆写、扩展脚本或独立主配置。不同客户端对覆写格式和合并顺序的实现并不完全相同，因此不能把某个客户端的扩展语法当成 mihomo 原生 YAML。迁移客户端前，应先区分哪些字段属于内核，哪些属于图形客户端的配置管理层。

覆盖、追加与删除是三种操作

标量字段如 mixed-port、mode 通常可以直接覆盖；映射字段如 dns 可能按键合并，也可能整段替换；数组字段如 rules、proxy-groups 更复杂，简单覆盖会丢掉订阅内容，简单追加又可能让兜底规则提前截断后续条目。尤其是 MATCH 必须位于规则末尾，如果把本地规则追加到远端 MATCH 之后，它们永远不会命中。可靠的合并器应支持前置、后置、按名称替换和显式删除，并在输出阶段检查最终顺序。

策略组按 name 关联时，同名组可能被替换，也可能形成重复项。重复名称会让规则引用结果不明确，客户端界面也可能只显示其中一个。合并前应建立固定命名约定，例如本地业务组使用清晰的中文名称，远端自动组保留来源前缀。节点名同样可能冲突：两个订阅都含“香港 01”时，内核可能报重复代理名称。解决方式是在导入层为不同来源添加前缀，而不是手工改每个节点，因为下次更新仍会再次冲突。

# 本地维护的主配置片段
proxy-providers:
  provider-a:
    type: http
    url: https://subscription.example.invalid/a
    path: ./providers/a.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

  provider-b:
    type: http
    url: https://subscription.example.invalid/b
    path: ./providers/b.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: 所有来源
    type: select
    use:
      - provider-a
      - provider-b
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,corp.example.invalid,DIRECT
  - RULE-SET,private-domain,DIRECT
  - MATCH,所有来源

使用 proxy-providers 汇总多个节点订阅，通常比把多份完整配置直接拼接更清晰。完整配置可能各自包含端口、DNS、规则和同名策略组，机械拼接极易冲突；节点提供者只提供代理条目，主配置统一控制其他部分。若上游返回的是完整 Clash 配置而不是 provider 格式，应先确认客户端能否提取节点，或者在可信的本地流程中转换。不要把包含访问凭据的订阅交给来源不明的在线转换页面。

覆写层级与回退文件

推荐保留四层：原始订阅、本地覆写、合并后的最终配置、最近一次可用配置。原始订阅用于确认上游内容；本地覆写进入版本管理时应移除订阅地址和访问凭据；最终配置用于定位合并结果；可用配置用于故障回退。每次修改只动本地覆写，生成后先做语法检查，再让内核加载。若客户端没有导出最终配置的功能，可从运行目录找到实际加载文件，但要注意该文件可能被客户端自动重写，不适合作为编辑入口。

本地覆写最适合维护稳定意图：自定义规则、固定策略组框架、DNS 选择和局域网例外。节点列表、认证字段和上游随时变化的属性应继续由订阅提供。这样更新时既能获得新节点，又不会覆盖本地分流。若某个上游开始提供不兼容字段，应在覆写层做最小删除或转换，并记录原因；不要复制整份旧配置长期冻结，否则节点与协议能力会逐渐失去更新。

多订阅的可用性与故障隔离

多个提供者不应共用相同缓存路径，健康检查也应独立。某一来源更新失败时，其他来源仍可加载；若所有组都只引用失败来源，表面上配置加载成功，策略组却会没有可用成员。可在上层手动组中保留多个自动组，并明确显示来源。自动选择组若混入不同用途、不同地区的全部节点，探测结果可能频繁变化；更合适的方式是先按来源或地区分组，再在业务层选择这些子组。

合并后的验证重点包括：策略组名称是否唯一、每个引用是否存在、提供者路径是否不同、规则末尾是否只有预期的兜底、DNS 映射是否完整、敏感字段是否意外写入日志或导出文件。更新订阅前后可对最终配置做结构化比较，关注字段变化而不是只比较文本行。若一次更新后无法启动，先恢复最近可用配置，再比较上游新增字段，避免在不可用状态下连续修改多个覆写规则。

图形客户端的覆写入口和保存位置各不相同。Clash Plus 适合需要图形化管理配置和策略组的桌面用户；Clash Verge Rev、FlClash、Clash Nyanpasu 等客户端也可能提供扩展或脚本能力，但语法应以其当前界面说明为准。需要重新选型时可查看客户端选型指南，不要仅凭某段可复制脚本决定客户端。

CHAPTER 07 / EXTERNAL CONTROLLER

外部控制面板与 API 边界

mihomo 的外部控制接口允许图形界面或 Web 控制面板读取运行状态、切换策略、查看连接并更新配置。它是管理接口，不是代理端口。将 external-controller 设置为监听地址后，客户端通过 HTTP 与 WebSocket 连接该端口。控制面板通常只包含静态前端文件，真正的数据和操作能力来自内核接口。因此页面打不开、能打开但没有数据、能查看却不能操作，分别对应静态资源、接口连接和鉴权权限等不同问题。

监听地址与访问范围

仅在本机使用时绑定 127.0.0.1 最稳妥，其他设备无法直接访问。需要从局域网管理服务器或路由器时，才绑定 0.0.0.0 或指定局域网地址，并通过防火墙只允许可信网段。监听所有接口不等于应该开放到公网。控制接口可以切换节点、读取连接目标并重新加载配置，暴露范围应小于普通代理端口。远程维护优先使用 SSH 隧道或受控的反向代理访问本地接口，而不是直接开放控制端口。

external-controller: 127.0.0.1:9090
secret: "your-password"
external-ui: ./ui
external-ui-name: dashboard

# 从另一台设备临时通过 SSH 转发本地接口
ssh -L 9090:127.0.0.1:9090 [email protected]

secret 用于控制接口鉴权，应设置为独立且不可猜测的值。示例中的字符串只是明显的教学值，部署时需要自行替换。控制面板通常要求在设置中填写 API 地址和密钥；API 地址应指向内核监听位置，而不是代理的 mixed-port。若页面通过 HTTPS 加载，却尝试访问 HTTP 控制接口，浏览器可能因混合内容策略阻止请求。此时应通过同源反向代理或安全隧道统一访问方式，而不是关闭浏览器安全限制。

external-ui 与静态资源目录

external-ui 指向控制面板静态文件目录，目录中应存在入口 HTML 和配套资源。该字段不负责下载面板，路径也以内核运行工作目录为基准。系统服务与手工运行命令的工作目录可能不同，因此“终端启动可见、服务启动空白”通常是相对路径解析差异。可改用明确的绝对路径，或确认服务单元的工作目录和文件权限。只读文件系统中，面板文件应预先部署到可读取位置。

部分配置支持通过外部 UI 下载地址维护静态资源，但生产环境仍应记录来源并固定更新流程。面板更新与内核更新是两个独立过程，新面板可能调用旧内核不支持的接口，旧面板也可能无法显示新字段。遇到界面按钮失效时，先在浏览器开发者工具中查看请求状态和接口响应，再对照内核日志；不要先删除主配置，因为控制面板异常通常不会改变代理核心是否能工作。

CORS、鉴权与反向代理

控制面板与 API 位于不同来源时，浏览器会执行跨域检查。mihomo 可通过允许来源相关配置限制可访问的页面来源。为了省事允许任意来源，会扩大浏览器侧攻击面；更合理的是只列出实际控制面板地址。即使配置了来源限制，也不能替代密钥和网络层限制。三者职责不同：防火墙限制谁能连端口，鉴权决定请求是否有操作权限，来源策略限制哪些网页可以由浏览器发起调用。

使用反向代理时应正确转发 WebSocket 升级请求，否则普通状态接口可能可用，实时日志和连接列表却持续断开。代理层还要保留鉴权头，并限制请求体大小和访问路径。不要让反向代理同时把代理端口、控制接口和静态面板混在无区分的路径下。若只需要局域网访问，直接绑定局域网地址并配防火墙往往比复杂的公网代理更容易维护。

接口故障的分层检查

先用系统工具确认端口是否监听，再请求基础接口验证鉴权，随后检查浏览器控制台。连接被拒绝说明内核未监听、地址错误或防火墙阻断；返回未授权说明接口可达但密钥不匹配；普通请求成功而实时内容失败，重点检查 WebSocket；面板资源返回找不到，则检查 external-ui 路径。若控制面板显示策略组为空，应直接查看 API 返回和内核配置，判断是面板渲染问题还是策略组本身没有成员。

外部控制接口也适合自动化健康检查，但脚本不应高频轮询全部连接，更不应把密钥写进公开仓库、命令历史或前端页面。自动化只读取必要端点，并为失败设置超时和退避。配置重载属于有状态操作，执行前应保留当前可用文件，重载后确认内核返回成功并重新检查策略组。控制面板提供了便利入口，但最终判断仍以配置文件、接口响应和内核日志为准。

CHAPTER 08 / VALIDATION

配置验证、日志定位与安全回退

进阶配置的难点通常不在某个字段本身，而在多个子系统同时变化后无法定位因果。有效的维护流程应把语法验证、静态引用检查、启动日志、运行连接和业务结果分开观察。网页能打开只证明某条路径可用，不代表 DNS、规则和 TUN 都按预期工作；反过来，某个网站失败也不等于节点不可用。每次修改前记录基线，修改后用固定目标和固定策略测试，才能得到可比较的结论。

加载前的静态检查

首先检查 YAML 缩进、冒号、列表层级和重复键。YAML 使用空格缩进，制表符可能导致解析错误；包含冒号、井号或特殊字符的名称可加引号，避免被解释为结构或注释。语法通过后再检查语义引用：规则指向的策略组是否存在，策略组引用的节点或 provider 是否存在，规则集名称是否一致，缓存路径是否冲突，控制接口端口是否与 mixed-port、DNS 监听端口重复。

mihomo 可通过命令行指定配置目录并执行检查，不同部署包的可执行文件名和参数入口可能由客户端封装。直接使用内核时，可在实际运行环境中执行配置测试，确保相对路径、权限和资源文件与服务环境一致。只在个人终端验证而服务使用另一个账户，可能漏掉路径和权限问题。

# 进入实际配置目录后执行
mihomo -t -d /path/to/config-directory

# 前台启动以观察完整日志
mihomo -d /path/to/config-directory

# Linux 查看路由和监听端口
ip route
ss -lntup

配置测试通过不代表远程资源一定可下载，也不代表节点可连接。它主要确认本地结构和部分资源是否可读取。首次启动时继续观察 provider 更新、DNS 监听、TUN 接口、控制端口和代理端口的日志。日志中的第一条错误往往比后续连锁错误更接近根因。例如 DNS 监听端口冲突会导致解析不可用，随后出现的大量节点域名解析失败只是结果。

按执行链建立测试矩阵

测试应从最小链路逐步增加功能。第一轮关闭 TUN，使用系统代理和固定手动节点，验证基本 TCP 连接；第二轮保持节点不变，验证域名解析和规则命中；第三轮切换自动策略组，确认健康检查；第四轮启用 TUN；第五轮再启用嗅探、覆写或复杂规则集。每轮只增加一个变量。若在第三轮失败，就不必继续怀疑第五轮的嗅探参数。

读日志时区分阶段

启动阶段关注配置解析、端口绑定、资源加载和虚拟接口创建；订阅阶段关注 HTTP 状态、超时、格式解析和缓存写入；DNS 阶段关注查询来源、上游选择和返回结果；连接阶段关注目标、规则、策略组和实际节点；运行阶段再观察健康检查和连接关闭原因。不要看到“timeout”就立即更换节点，同一个词可能来自规则下载、DNS 查询、代理握手或业务服务器，每种超时的处理方向不同。

连接详情通常能给出源地址、目标域名或 IP、网络类型、命中规则、策略链和出站节点。把这些字段按顺序读一遍，可以判断请求在哪一层偏离预期。例如目标域名正确但命中 MATCH，说明前面的规则没有覆盖；命中规则正确但策略组落到意外节点，检查组内选择和自动测试；策略与节点都正确仍失败，再检查节点连接、目标服务和 MTU。这样的顺序比反复切换模式更容易收敛。

回退不是简单恢复一个文件

配置故障可能同时留下路由、虚拟接口、DNS 缓存和远程资源缓存。恢复 YAML 后若现象仍在，需要确认内核已重新加载该文件、旧进程已经退出、TUN 路由已经清理、系统代理已恢复、DNS 缓存已刷新。图形客户端可能保存一份界面配置和一份实际运行配置，恢复错文件不会改变内核行为。回退完成后应重新查看启动日志中的配置路径。

建议每次稳定变更形成一个可回退节点，至少保存配置文件、相关规则集版本、客户端使用的配置目录和变更说明。说明应写清“解决什么问题、修改哪些字段、如何验证、如何撤销”，而不是只记录“优化 DNS”。订阅地址和控制密钥不应进入公开版本库；可以用独立的本地私密文件或运行环境注入，再让配置引用。分享日志时也要移除订阅参数、节点认证信息、控制密钥和内部域名。

形成可重复的维护顺序

一次完整调整可按以下顺序执行：复制当前可用配置；导出或记录最终合并结果；只修改一个主题；运行静态检查；前台加载观察第一条错误；固定节点验证系统代理；检查 DNS 查询与规则命中；最后启用 TUN 和嗅探；稳定后再恢复自动策略和远程更新。若任一步失败，回到上一份可用配置，并清理该步骤产生的运行状态。这个流程看似较慢，却能避免多个变量叠加后进行更长时间的盲目排查。

对于日志量较大的环境，可按目标域名、源进程或时间范围过滤，不必长期使用最详细日志级别。详细日志适合短时定位，持续开启会产生大量记录并增加敏感信息暴露范围。问题解决后恢复常规级别，并保留精简的故障摘要。若需要理解启动、订阅、DNS、连接和规则阶段的典型报错，可结合运行日志定位顺序逐项核对；局域网共享涉及 mixed-port、监听地址与防火墙时，可阅读混合端口与局域网代理设置。