TL;DR：sing-box rule-set 缓存失败时，先别改一大串路由。用最小配置确认 core 能启动，再检查远程 URL 返回的到底是不是规则文件。很多失败不是规则写错，而是下载到 HTML、格式填错或缓存目录写不了。
sing-box 的 rule-set 很好用，但它比 Clash 的 rule-provider 更严格。route.rule_set 负责定义规则集，route.rules 再引用这些 tag。远程下载、格式解析、缓存写入、路由引用，任意一段出错，GUI 里都可能只显示「更新失败」。
先读日志里的动词
看日志时，注意它是在 download、parse、cache 还是 route 阶段失败。
| 日志线索 | 更可能的原因 | 先查什么 |
|---|---|---|
| download failed | URL 不可达、TLS 错误、状态码异常 | 地址、网络、证书、重定向 |
| invalid rule-set | 文件内容不是声明的格式 | format 与文件类型 |
unexpected character < | 下载到 HTML 页面 | URL 是否指向 raw 文件 |
| permission denied | 缓存目录不可写 | 客户端数据目录权限 |
| rule_set not found | tag 引用不一致 | route.rule_set 与 route.rules |
unexpected character '<' 很有辨识度。它通常说明 sing-box 正在把 HTML 当 JSON 或规则文件读。
一个可工作的 remote rule-set 结构
不同版本字段会有变化，写配置时以官方文档为准。排障时可以先看结构是否清楚：
{
"route": {
"rule_set": [
{
"type": "remote",
"tag": "geosite-example",
"format": "binary",
"url": "https://example.com/example.srs",
"download_detour": "direct"
}
],
"rules": [
{
"rule_set": ["geosite-example"],
"outbound": "proxy"
}
],
"final": "direct"
}
}更该先看看三件事：tag 有定义，rules 有引用，format 和文件内容一致，而不是照抄字段。
URL 要拿 raw 文件，不要拿页面地址
GitHub 页面地址、release 页面、文档页面都不是规则文件。sing-box 需要直接下载文件内容。
检查方法很简单：
curl -L -I "https://example.com/rules/example.srs"再看内容开头：
curl -L "https://example.com/rules/example.json" | head如果你看到 <html>、登录提示、CDN 错误页、rate limit 页面，就不是规则文件。换成 raw 地址或官方发布的下载地址。
format 不能靠文件名猜
.srs 常见是 binary 格式，但不要只看后缀。JSON source rule-set、inline rule-set、二进制 SRS 的配置写法不同。
| 文件内容 | 常见 format | 排查方式 |
|---|---|---|
| 二进制 SRS | binary | 不要用文本编辑器改 |
| JSON 规则集 | source 或文档指定值 | 能看到 JSON 对象结构 |
| 内联规则 | 不走 remote URL | 直接写在配置里 |
如果你从别的生态迁移规则，尤其要注意格式差异。Mihomo 的 .mrs 或传统 list 文件不能直接当 sing-box SRS 用。
缓存目录也会出问题
GUI 客户端常把 sing-box 放在应用数据目录里运行。系统升级、迁移用户目录、从只读位置运行应用，都可能导致缓存写入失败。
处理顺序：
- 退出客户端。
- 备份 profile。
- 找到客户端的 rule-set cache 目录。
- 删除失败规则对应的缓存文件。
- 重新启动并触发下载。
不要把整个应用数据目录直接删掉，除非你已经备份配置。
用本地最小规则隔离问题
如果你怀疑是远程下载问题，可以临时改成一个本地或内联规则。最小 route 能启动，说明 sing-box core 和出站结构没问题。
排障期间也可以先关闭复杂分流，只保留 final outbound。等 rule-set 下载稳定后，再恢复完整规则。
如果配置还要给多客户端导入，建议先确认订阅本身能在目标客户端解析。需要同一份订阅覆盖 Clash、Singbox、V2Ray 客户端时，可以用兼容 Clash / Singbox / V2Ray 的订阅做导入测试；rule-set 仍按 sing-box 文档单独检查。
最后检查表
- URL 返回的是规则文件本体，不是网页。
-
format与文件内容一致。 -
route.rule_set[].tag和route.rules[].rule_set完全一致。 - 下载 detour 没有指向不存在的 outbound。
- 缓存目录可写。
- 清理旧缓存后已重新拉取。
- 最小 route 配置可以启动。