先定位超时阶段：规则命中、DNS 解析还是远端连接

GitHub、npm 或 Docker Hub 超时，不一定是“规则没写对”。请求可能在域名解析、TLS 握手、代理节点连接、身份认证或下载大文件时失败。先确认客户端当前使用的配置、代理模式和策略组状态，再用连接日志找出实际访问的域名与命中规则，避免把所有开发流量一股脑切到全局代理。

以 mihomo 内核的图形客户端为例，先确认内核正在运行，并在客户端的连接或日志页面观察一次失败请求。日志字段名称会随客户端版本变化，重点记录目标主机、匹配规则、使用的策略组、最终节点和错误阶段。若日志只有域名而没有规则详情，可以临时提高日志等级进行复现，完成后恢复原等级，避免长期产生大量记录。

  • 浏览器访问正常，命令行失败：终端程序可能没有读取 macOS 系统代理设置。确认当前工具是否支持代理环境变量，或在网络接管确有需要时单独测试 TUN。
  • 日志显示命中 DIRECT：检查规则顺序、域名是否覆盖请求实际访问的主机，以及自定义规则是否排在兜底规则之前。
  • 日志已选代理组，但连接仍超时：检查策略组当前选中的节点、节点可用性、DNS 与目标服务连接情况。规则只决定出口策略，不会修复不可用节点。
  • Docker 已完成认证但拉取层超时：除了认证和注册表域名，还要观察日志中实际出现的内容分发主机。镜像层可能从不同域名下载，不能只凭一次登录成功判断整个拉取链路正常。

开发工具分流：覆盖 GitHub、npm 与 Docker 的关键域名

按域名分流时，优先依据连接日志中真实出现的主机名，而不是只看网页地址栏。GitHub 的网页、Git 操作、静态资源和下载可能分别访问不同域名；npm 常见请求会访问包注册表；Docker 拉取则可能涉及认证端点、镜像注册表和内容分发主机。服务端部署和域名可能调整，下面的清单应作为排查起点，而不是保证覆盖所有网络请求的固定名单。

  • GitHub：可从 github.com、githubusercontent.com、githubassets.com 等域名开始检查。Git over SSH 通常连接 TCP 22；域名规则不会把 SSH 端口自动改成 HTTPS，也不会修复网络对该端口的限制。
  • npm：常见注册表主机是 registry.npmjs.org。若使用企业私有 registry、镜像源或自定义 .npmrc，应按配置中的 registry 地址检查，而不是假定所有包都走公共源。
  • Docker Hub：可检查 auth.docker.io 与 registry-1.docker.io，并在拉取日志中继续确认实际内容分发主机。企业镜像、加速器及私有仓库需要以自身配置为准。

如果只需要让这些服务走代理，可以把明确的域名规则放在通用规则之前，并指向一个确实存在的代理组。例如，以下片段说明规则顺序与策略引用方式；Developer 是示例组名，必须替换成当前配置中已经定义的名称。不要把示例当作可直接导入的完整配置。

proxy-groups:
  - name: Developer
    type: select
    proxies:
      - Proxy
      - DIRECT

rules:
  - DOMAIN-SUFFIX,github.com,Developer
  - DOMAIN-SUFFIX,githubusercontent.com,Developer
  - DOMAIN-SUFFIX,githubassets.com,Developer
  - DOMAIN,registry.npmjs.org,Developer
  - DOMAIN,auth.docker.io,Developer
  - DOMAIN,registry-1.docker.io,Developer
  - MATCH,其他策略

此处的 Proxy 与 其他策略 也只是占位名称，必须与现有策略组中的名称完全一致，包括大小写、空格和标点。若客户端已经由订阅生成策略组，不要直接复制并覆盖整个 proxy-groups；应按客户端支持的覆写方式添加组，或在已有组中维护选择项。

规则优先级与策略组：避免正确规则被提前截断

Clash 风格规则通常按配置中的顺序逐条匹配，先命中的规则决定连接使用的策略。若通用的 GEOIP、RULE-SET 或 MATCH 已经命中，写在它后面的 GitHub 精确规则就不会再参与判断。排查时先看连接记录中的实际命中项，再决定是否调整顺序；仅凭 YAML 中“存在一条规则”不能证明它会生效。

  1. 将需要单独控制的精确域名规则放在覆盖范围更大的规则之前。
  2. 确认规则指向的策略组已经定义，并且组内至少有可用的节点或明确的直连选项。
  3. 把兜底规则放在规则列表末尾。兜底可以是项目定义的策略组或 DIRECT，应根据自身网络需求选择。
  4. 保存后重新加载配置，再产生新的连接进行验证。已有连接可能沿用旧的连接状态，不能只观察修改前建立的连接。

策略组决定“命中后如何选择出口”，不负责识别域名。对于开发流量，手动选择组适合临时切换代理与直连；自动选择组可按延迟测试结果筛选节点，但测速通过不等于 Git、npm 发布或 Docker 大文件传输一定稳定。建议先用手动组排除节点因素，确认规则正确后再考虑自动化选择。

也不要为了处理某个站点的超时就直接把所有连接改成全局代理。全局模式会改变其他应用的出口，可能影响局域网服务、公司内网、软件更新和本地开发容器。用少量目标域名的规则建立可控范围，再通过连接日志检查未覆盖的主机，通常更容易回退和维护。

动手配置 rule-providers：把维护规则与主配置分开

mihomo 的 rule-providers 用于声明外部规则集，具体字段和支持的行为应以当前内核版本为准。配置中声明的 provider 还需要通过 RULE-SET 规则引用；只添加 provider 不会自动让它参与匹配。以下示例中的 URL 是无效占位地址，必须替换为自己能够访问、内容格式符合 mihomo 要求的规则文件地址，不能直接用于生产配置。

  1. 先确认内核：在客户端的内核信息页记录 mihomo 版本，并确认该版本支持准备采用的 provider 类型、字段及规则语法。旧内核不认识某个字段时，配置可能在启动阶段就失败。
  2. 准备规则文件：把 GitHub、npm 或 Docker 所需域名整理成经过审核的规则集。检查文件确实返回规则内容，而不是登录页面、访问拒绝页面或 HTML 错误提示。
  3. 声明 provider：为规则集设置唯一名称、规则类型、下载地址、本地缓存路径和更新周期。远程地址应使用可信的 HTTPS 来源。
  4. 引用并安排优先级：在 rules 中用 RULE-SET 引用 provider，并把需要优先处理的集合放在可能提前命中的宽泛规则之前。
  5. 加载后验证：重新加载配置，检查 provider 是否成功下载和解析，再发起新的请求确认日志显示对应规则集及目标策略。
rule-providers:
  developer-domains:
    type: http
    behavior: domain
    url: "https://rules.example.invalid/developer-domains.yaml"
    path: ./ruleset/developer-domains.yaml
    interval: 86400

rules:
  - RULE-SET,developer-domains,Developer
  - MATCH,其他策略

behavior: domain 适用于以域名匹配为主的规则集；若文件包含 IP 网段或传统规则类型，不能不经核对就沿用该行为。interval: 86400 表示按秒设置的更新间隔示例，并不保证客户端始终在线时也能准点完成更新。path 是本地缓存路径示例；不同客户端的运行目录、沙盒权限与相对路径解析可能不同，应结合客户端文档确认。

超时排查：用日志和命令逐层验证

遇到超时先缩小问题范围：同一域名在代理与直连之间是否有差异？同一策略组换一个节点是否改善？失败发生在 TCP 建连、TLS 握手、认证还是下载阶段？每次只改变一个因素，并记录时间、目标域名、命中规则和客户端内核版本，才能区分规则问题与上游链路问题。

在 macOS 终端可以用 curl 指定本地 HTTP 代理，检查目标站点的 HTTPS 握手。下面的端口仅为示例；命令中使用代理地址，不会自动改变 Clash 的分流规则，因此还应同时查看客户端连接日志。

curl -I --connect-timeout 10 \
  --proxy http://127.0.0.1:7890 \
  https://registry.npmjs.org/

返回 HTTP 状态码表示请求至少得到了一次 HTTP 响应，但不能单独证明所有包下载或身份验证流程都正常。若命令报告无法连接本地代理，先检查客户端运行状态、监听端口和本机代理类型；若本地代理可连接但请求超时，再对照日志检查规则命中、节点出口和远端连接。

  • GitHub 网页可开，Git 操作失败：核对仓库远程地址是 HTTPS 还是 SSH。SSH 可能使用不同端口；可在日志中确认它是否进入代理内核，再按网络策略处理，而不是只增加网页域名规则。
  • npm 安装卡在少数包：检查 npm config get registry 的结果，以及包元数据和压缩包实际访问的主机。代理规则只匹配连接目标，不会修正错误的 registry 配置或失效的认证令牌。
  • Docker 登录成功但拉取中断：检查完整拉取期间的连接记录，确认认证域名、注册表和内容分发主机分别命中了什么策略。不要仅因 docker login 成功就排除网络问题。
  • 日志显示 DNS 错误：检查域名解析路径、DNS 设置和当前网络环境。规则决定连接策略，DNS 配置决定名称如何解析；两者相关但不能互相替代。

分享日志或配置前，删除订阅链接、节点地址、密码、令牌、私有仓库名称和本机 IP 等敏感信息。诊断需要保留的通常是错误阶段、规则类型、策略组名称、目标域名以及脱敏后的时间信息，不需要公开完整凭据。

版本管理与回退：让规则更新可审阅、可恢复

自定义规则会随着客户端、内核、订阅和远程规则集变化而变化。不要把所有改动同时塞进一个难以追溯的 YAML 文件。至少保留一份可恢复的配置副本，并记录修改日期、mihomo 版本、provider 来源、规则集更新结果及预期影响。若使用 Git 管理本地规则，提交前检查差异，避免把真实订阅令牌、节点密码和个人网络信息一并提交。

  • 修改前备份：复制当前可用配置，并记下正在使用的配置名称和策略组选择。备份文件应保存在受控位置，不要公开上传含有访问凭据的完整配置。
  • 分批调整：先加一条明确域名规则，再观察日志；确认有效后再扩展规则集。避免同时改 DNS、TUN、节点订阅和多组规则，导致故障来源无法判断。
  • 更新后检查：核对配置解析是否成功、provider 下载是否成功、规则集文件是否更新，以及目标请求是否命中预期策略。
  • 失败时回退：若更新后出现配置加载错误或开发流量异常，先恢复上一份已验证配置，再分别检查 provider 地址、YAML 缩进、组名引用和内核兼容性。
  • 定期清理：删除不再使用的 provider、过期的本地规则文件和重复规则，保留必要的变更记录，减少后续排查时的噪声。

一套可靠的开发工具分流方案，不是收集尽可能多的域名，而是能解释每条请求为什么命中某个策略，并能在规则源失效或内核升级后安全回退。先从连接日志定位真实主机，再用清晰的策略组和有序规则建立最小覆盖范围；只有在规则确实增长到难以维护时，才把它们拆到 rule-providers 中统一管理。