远程 rule-set 把规则从主配置里拆出去，配置文件会更短，启动链路却多了几步：下载远程文件、按 format 解析、写入缓存、再被 route.rules 引用。任何一段失败，界面都可能只给出一个笼统的更新失败。

排查时别同时改规则源、DNS、TUN 和订阅。先保留原配置，拿同一份 config.json 跑静态检查，再用日志里的错误字符串对字段。这样能区分是规则文件问题、缓存问题，还是旧字段迁移问题。

##看日志属于哪一类？

故障表现更可能原因第一处检查
invalid sing-box rule-set fileformat 与文件内容不一致route.rule_set[].format
每次启动都重新下载规则缓存没启用或不可写experimental.cache_file
新版提示 download_detour 弃用旧模板字段没迁移deprecated 文档和当前配置结构
route 启动后找不到规则集tag 名称不一致route.rules 里的 rule_set
更新间隔异常频繁update_interval 写得太短远程 rule-set 的更新周期

如果表里有两项同时命中，处理更靠前的报错。配置解析失败时，缓存和规则命中都不会进入正常流程；缓存不可写时，下载成功也可能在下一次启动重来一遍。

为什么不要一上来重装客户端？

重装客户端会清掉日志、缓存和服务状态，也可能短暂释放端口或刷新 DNS 缓存。看起来像修好，下一次更新远程规则时同一个错误还会回来。

更稳的做法是保留原配置副本，只做一次最小化验证：同一台设备、同一个配置文件、同一个测试域名。每次只改一个字段，改完立即重启并看日志。

现场先跑哪 4 条命令？

用 sing-box check 排除静态配置错误，再看 rule-set、cache_file 和旧字段是否存在。

sing-box check -c config.json
jq ".route.rule_set" config.json
jq ".experimental.cache_file" config.json
grep -n "download_detour\|http_client\|rule_set" config.json

这 4 条命令不负责证明代理链路可用，只负责定位配置段。若 check 已经失败，先别去改 DNS、策略组或系统代理；静态配置没过，后面的运行状态没有参考价值。

rule-set 字段怎么逐个对？

字段或组件应该确认什么出错时常见表现
type: remote这是远程规则来源缺 url 或被当成本地规则处理
format与远程文件类型一致invalid sing-box rule-set file
url返回的是规则文件，不是登录页或 HTML更新失败、解析失败
update_interval更新周期不要过短频繁请求规则源
tag被 route.rules 精确引用route 找不到规则集

最容易误判的是 url。浏览器打开能看到内容，不等于 sing-box 能解析；如果返回的是登录页、错误页或重定向后的 HTML，仍然会在 rule-set 解析阶段失败。

cache_file 应该查什么？

检查点正常状态异常信号
experimental.cache_file.enabled已启用每次重启都重新下载
path服务运行用户可写日志出现 cache 写入失败
cache_id同一套配置保持稳定多套配置缓存互相干扰
服务权限systemd、桌面客户端或容器用户能访问目录手动运行正常，后台服务失败

缓存问题和规则源问题的区别很明显：规则源问题通常第一次下载就失败；缓存问题可能第一次能下载，重启后又重复下载或写入失败，看日志里有没有 cache 相关错误，再看路径权限。

download_detour 怎么迁移才不容易翻车？

旧模板里经常把下载规则集的出站写在 download_detour。新版提示弃用时，不要直接删字段上线，确认当前 sing-box 版本的官方弃用说明，再把下载链路迁移到当前版本支持的配置位置。

迁移时建议按这个顺序做：

  1. 复制一份原始配置，文件名带日期。
  2. 搜索所有 download_detour，确认只影响远程下载链路。
  3. 按官方文档改成当前版本支持的写法。
  4. 跑 sing-box check -c config.json。
  5. 重启后观察第一次下载和第二次启动的日志差异。

多端共用同一套订阅时，先拿一台测试机验证下载链路和缓存。手机、桌面端、软路由一起改，会把客户端差异和配置差异混在一起；如果需要一份能在 Clash、Singbox、V2Ray 客户端之间做基线测试的输入，可以准备兼容 Clash / Singbox / V2Ray 的订阅，但排错仍然以本机日志为准。

route.rules 为什么会找不到 rule-set？

rule-set 能下载成功，不代表 route 一定引用成功。route.rules 里写的是 tag 名称，大小写、横线、下划线只要有一个字符不一致，就可能变成找不到规则集。

排查时把 route.rule_set[].tag 和 route.rules[].rule_set 放在一起看，确认每个被引用的 tag 都存在，再看规则顺序是否把流量提前打到兜底规则。

怎么验证已经恢复？

  • 第一次重启能下载远程 rule-set，第二次重启不再重复下载同一批文件。
  • 日志里不再出现 invalid sing-box rule-set file、cache 写入失败或 download_detour 弃用提示。
  • route.rules 命中的 rule-set tag 与配置里的 tag 一致。
  • 用同一个测试域名连续访问 3 次，连接记录进入预期出站或策略。

验证要回到最初的失败样本。只看 UI 绿色状态不够；能复现同一个动作，并在日志里看到规则命中和缓存复用，才算完整链路。

哪些证据值得留下？

处理这类问题时，最有用的不是截图，而是一行变更记录：sing-box 版本、系统版本、配置文件路径、缓存路径、失败 URL、日志关键词、最后一次改动字段。

如果配置由多人维护，变更前后各留一份导出文件。不要只写“改了规则”或“修了 DNS”，而是写清 format 从什么改到什么、cache_file.path 指到哪里、哪个 rule_set tag 被 route 引用。下一次换设备或升级版本时，这些记录能直接判断是环境差异还是配置差异。

相关阅读