sing-box JSON 检查工具有哪些？验证配置文件格式与常见字段错误指南

sing-box 顶级模块的功能职责与联动拓扑#

1. log（系统日志管理）：
   • 控制 sing-box 运行时的日志输出行为。可指定 level（trace、debug、info、warn、error、fatal）以及 output 文件路径。在日常故障排查中，将日志临时切换至 debug 级别是捕获连接握手破损的第一手段。
2. dns（现代 DNS 调度与防污染引擎）：
   • 负责解析全局域名并实施精确防污染分流。包含 servers（声明上游 DNS 端点，支持标准 UDP、DoH、DoT、DoQ）、rules（根据域名模式匹配特定的 DNS 端点）、final（未命中任何规则时的权威兜底 DNS 服务器标签）以及 fakeip 内存地址池。
3. inbounds（多协议入站监听池）：
   • 定义客户端如何接管外部流量。支持开启基于系统虚拟网卡的 tun 模式（接管系统全局底层网络流）、监听在本地端口的 mixed 混合代理（同时兼容 HTTP 和 SOCKS5），或者在路由器软路由上开启 tproxy 实施完全透明的四层流量重定向。
4. outbounds（出站节点与调度策略组）：
   • 承载所有物理出口节点与逻辑调度器。每一个出站对象必须具备一个全局唯一的 tag（标签名）。系统内置保留标签包括 direct（物理直连）与 block（阻断丢弃）。逻辑策略组则包括 selector（用户手动切换）与 urltest（最低延迟自动测速选优）。
5. route（分流决策路由中枢）：
   • 决定接收到的网络连接流向哪一个出站节点。包含 rules 规则链、rule_set 外部规则集声明、final（未命中任何路由规则时的默认出站标签，通常指向代理策略组或 direct），以及针对 TUN 模式至关重要的 auto_detect_interface。
6. experimental（高级扩展与生态兼容）：
   • 提供与现有图形化生态的桥接能力。最著名的便是 clash_api，它在本地开放标准的 RESTful 控制端口（通常为 9090），允许用户继续使用如 Yacd、MetaCubeX 等广受欢迎的 Clash Web 仪表盘控制 sing-box 核心。

深度剖析四大致命语法缺陷#

1. 尾随逗号的毁灭性灾难（Trailing Comma）：
   • 在现代 JavaScript 或 Python 语法中，字典或列表最后一项末尾保留逗号通常是完全合法甚至被推荐的代码风格。但在严格遵循 RFC 8259 的标准 JSON 解析器中，尾随逗号是绝对致命的语法错误！
   • 例如在出站列表中：

     1
     // 错误示例: 最后一个大括号前多了一个逗号
     2
     "outbounds": [
     3
       { "type": "direct", "tag": "direct" },
     4
       { "type": "block", "tag": "block" },  <-- 致命尾随逗号！
     5
     ]

   • 当 sing-box 启动时，Go 语言底层高效的 encoding/json 状态机在扫描完第二个对象后读取到逗号，预期后面必然紧跟第三个对象的开始符号；当它紧接着读取到闭合方括号 ] 时，状态机发生严重冲突，直接抛出 invalid character ']' looking for beginning of value 并拒绝启动。
2. 单引号与无引号键名混入：
   • 从其他脚本语言转过来的技术人员，有时习惯性地写出 'type': 'direct'。在 JSON 标准中，单引号没有任何字符界定权限，解析器在遇到单引号的瞬间便会抛出 invalid character '\'' looking for beginning of object key string。所有的键名与字符串值必须严格使用成对的标准双引号。
3. Windows 路径反斜杠转义遗漏：
   • 当在配置文件中声明本地规则集或缓存路径时：

     1
     // 错误写法: 单反斜杠被识别为非法转义序列
     2
     "path": "C:UsersAdminsing-boxgeosite.db"
     3
     
     4
     // 正确合规写法: 使用双反斜杠进行严格转义, 或者直接使用标准正斜杠
     5
     "path": "C:\\Users\\Admin\\sing-box\\geosite.db"
     6
     "path": "C:/Users/Admin/sing-box/geosite.db"

4. 强类型系统下的数据类型倒错（Type Mismatch）：
   • sing-box 的底层由强类型的 Go 语言编写，其配置结构直接映射为内存中的 Go Struct 结构体。
   • 如果一个字段在核心规范中定义为布尔型（Boolean），例如 "udp": true，若你不小心写成了字符串 "udp": "true"；或者将整数型端口 "server_port": 443 写成了字符串 "server_port": "443"，Go 语言在执行 json.Unmarshal 反序列化时，会因为反射类型不匹配，直接抛出 json: cannot unmarshal string into Go struct field ... of type int。

四大里程碑破坏性变更与迁移方案#

1. 出站标签与列表命名体系标准化：
   • 在极其早期的 sing-box 中，某些地方允许使用单数形式的 outbound。在现代标准规范中，必须全量统一使用复数形式 outbounds（出站适配器列表）。
   • 任何一个出站对象，其唯一标识符必须严格使用 tag 字段。在现代内核中，出站标签区分大小写，且在整个 outbounds 数组中严禁出现任何重复的 tag。如果定义了两个同名的 "tag": "proxy"，核心在构建出站哈希表时会直接报出重复键冲突。
2. 规则集体系（Rule Set）的全面二进制革新：
   • 在 1.8 版本之后，sing-box 彻底放弃了传统的重量级全量 geosite.db 与 geoip.db 整体读取模式，全面推行了革命性的 SRS（sing-box Rule Set）二进制编译规则集。
   • 现代配置在 route.rule_set 中直接按需声明轻量级规则集（例如仅加载广告拦截或中国直连），由核心在本地利用内存映射（mmap）极速按需加载，内存占用骤降 80% 以上：

     1
     "rule_set": [
     2
       {
     3
         "type": "remote",
     4
         "tag": "geosite-geolocation-cn",
     5
         "format": "binary",
     6
         "url": "https://raw.githubusercontent.com/SagerNet/sing-box-rules/main/rule/geosite-geolocation-cn.srs",
     7
         "download_detour": "select-node"
     8
       }
     9
     ]

3. route.final 兜底出站的绝对强制性：
   • 在 Clash 规范中，规则最后一行通常写 MATCH,策略组 作为保底。而在 sing-box 的 route 路由中枢中，必须显式声明 final 字段（例如 "final": "select-node"）。
   • 如果遗漏了 final 字段，任何未能命中上面明确规则的网络连接，在到达路由决策链末端时，由于缺乏明确的出口导向，sing-box 会直接抛出路由未知异常，或者将数据包静默丢弃至黑洞，导致用户感知为大面积网络断开。
4. TUN 模式下 auto_detect_interface 的生死攸关性：
   • 在启用基于内核虚拟网卡的 tun 入站时，route 模块中必须显式配置 "auto_detect_interface": true！
   • 因为 TUN 虚拟网卡在启动后，会修改操作系统的系统全局默认路由（将默认网关指向 sing-box 的虚拟 TUN 网卡）。如果未开启自动探测真实物理网卡，sing-box 自身向海外代理服务器发起的底层加密数据包，又会被系统重新路由回 sing-box 自己的 TUN 网卡中，从而在操作系统内部形成毁灭性的网络环路死锁（Routing Loop），导致本地 CPU 瞬间飙升至 100% 且全网彻底断线。

实验性特性 clash_api 模块与可视化仪表盘集成规范#

为了方便习惯了 Clash 交互界面的用户能够无缝平滑迁移，sing-box 在 experimental 顶级对象中内置了对 Clash RESTful API 的高度兼容支持：

1
"experimental": {
2
  "cache_file": {
3
    "enabled": true,
4
    "path": "cache.db",
5
    "cache_id": "my_profile_cache"
6
  },
7
  "clash_api": {
8
    "external_controller": "127.0.0.1:9090",
9
    "external_ui": "ui",
10
    "external_ui_download_url": "https://github.com/MetaCubeX/Yacd-meta/archive/gh-pages.zip",
11
    "external_ui_download_detour": "direct",
12
    "secret": "MySuperSecretAdminToken123",
13
    "default_mode": "rule"
14
  }
15
}

主流检测工具核心指标与能力深度横评#

使用 sing-box 官方核心执行静态配置合规性审查#

sing-box 官方提供了极其强大且专用的 check 子命令。该命令会完整加载指定的配置文件并对所有字段进行严格的类型映射与依赖审查，验证完毕后立即退出，绝不干扰正在后台运行的代理守护进程：

1
# 1. 对指定的 JSON 配置文件执行静态合规性检查
2
sing-box check -c ./config.json
3

4
# 2. 如果配置完全合规无误，终端将直接静默退出 (返回退出码 0):
5
echo $?
6
# 输出: 0
7

8
# 3. 如果存在 JSON 语法错误 (例如存在尾随逗号)，终端将给出极其精准的报错:
9
# fatal: read config: decode config/config.json: invalid character ']' looking for beginning of value at line 62, offset 1845
10

11
# 4. 如果存在未知字段或字段类型错误，终端将指出结构体映射失败:
12
# fatal: create service: json: unknown field "network" in struct type outbound.VLESSOptions

使用 jq 工具深度展开并快速提取全部出站标签#

利用 Unix 哲学中最强大的 JSON 处理器 jq，可以在终端中实现极速格式清洗与逻辑抽取：

1
# 1. 验证 JSON 语法完整性并以标准 2 空格美化高亮输出 (如果语法报错会当场拦截打印行号)
2
jq . config.json > config.formatted.json
3

4
# 2. 一键提取出站列表 (outbounds) 中定义的所有节点 tag 标签名称
5
jq -r '.outbounds[] | select(.tag != null) | .tag' config.json
6

7
# 3. 快速过滤出所有类型为 urltest 的策略组并检查其内部引用的出站节点
8
jq '.outbounds[] | select(.type == "urltest") | {tag: .tag, outbounds: .outbounds}' config.json

三大协议栈模式的物理优缺点与排障场景#

1. system（操作系统内核原生网络栈）：
   • 技术特性：直接利用 Linux 内核或 Windows 系统底层的原生网络协议栈进行数据包处理。
   • 核心优势：在万兆或千兆大流量长时间下载时，CPU 占用率极低，转发吞吐量处于理论天花板，发热量小。
   • 故障隐患：对宿主机系统的驱动兼容性要求较高。在某些老旧 Linux 内核或精简版 Windows 系统上，可能会因缺少特定网络套接字支持导致偶发丢包。
2. gvisor（Google 开源用户态网络栈）：
   • 技术特性：在 sing-box 的 Go 语言内存堆栈中，通过纯软件算法完整模拟并实现了一整套符合 RFC 标准的 TCP/IP 状态机。
   • 核心优势：跨平台兼容性达到惊人的百分之百！完全不依赖底层操作系统的特权网络驱动或内核模块，无论在多么畸形、受限的容器内，只要具备基本的 TUN 读写句柄就能绝对稳定启动。
   • 性能代价：由于所有的 TCP 确认应答、滑动窗口计算与重传全部在用户态由 Go 语言完成，在超大吞吐量压测时，CPU 使用率会有轻度上升。
3. mixed（混合渐进网络栈）：
   • 兼顾两者的折中产物。在日常办公和常规个人电脑上，通常首选 system 追求极致丝滑；而在遇到奇异网络断连的排障现场，将 stack 临时切换为 gvisor 是验证是否属于操作系统驱动缺陷的黄金参照物。

TUN 模式下的 MTU 物理取值与路径黑洞规避准则#

在 TUN 虚拟网卡配置中，mtu（最大传输单元）字段的设置直接关乎整体网络的传输吞吐与稳定性：

1. 默认 MTU 9000（巨型帧 Jumbo Frame）的设计哲学：
   • 在较新的 sing-box 版本中，当使用 stack: "system" 或 gvisor 时，系统默认的 TUN MTU 通常会被分配为极大的 9000 字节。
   • 这是因为数据包在虚拟网卡与 sing-box 进程之间传输时，完全是在主机内存中通过 DMA 或内存指针直接交换，根本没有真实的物理网线与以太网 1500 字节帧限制。使用 9000 字节的巨型报文能够成倍减少系统上下文切换与软件中断次数，显著降低 CPU 占用。
2. 物理出口封装溢出与降级规避（MTU 1400 保守设置）：
   • 然而，当底层运行着复杂的嵌套隧道（如使用基于 UDP 的 Hysteria2、TUIC 或 WireGuard）且外部物理网络为 PPPoE 拨号（物理 MTU 为 1492）时，过大的数据包在被加密并打上外层 UDP/IP 报头后，极易超过公网路由器的承载上限。
   • 如果遇到在 TUN 模式下网页文字秒开但大文件下载或视频播放频繁死锁挂起时，最稳健的排查手段是在 inbounds.tun 模块中显式添加：

     1
     "mtu": 1400

   • 将虚拟网卡的 MTU 强制保守锁定在 1400 字节，并在内核层面开启 MSS Clamping，彻底消灭由于嵌套封装开销引发的隐形路径黑洞。

【排查案例一】复制粘贴在 outbounds 末尾多加逗号导致生产网关直接停摆#

某跨境数据同步团队在 Linux 软路由网关上部署了 sing-box 作为全透明代理。在一次扩容维护中，运维人员使用 vim 手动向 outbounds 数组中添加了一台全新的美国落地服务器节点。保存并执行 systemctl restart sing-box 后，全网网络瞬间陷入瘫痪，内部办公机所有出海 API 全部报错断网。

工程师登录网关服务器，首先查看服务状态：

1
systemctl status sing-box

终端输出了致命的系统报错：

1
sing-box.service: Main process exited, code=exited, status=1/FAILURE
2
Dec 08 14:10:02 gateway sing-box[18241]: fatal error: read config: decode config.json: invalid character ']' looking for beginning of value at line 89, offset 2614

工程师查看第 89 行附近的上下文：

1
    {
2
      "type": "direct",
3
      "tag": "direct"
4
    },  <-- 后面没有其他节点了，但末尾保留了逗号！
5
  ]

原来，运维人员在复制上一段配置时，将末尾的逗号顺手带了过来，且将其粘贴在了数组的最后一项。由于 JSON 语法对尾随逗号的绝对排斥，Go 语言在反序列化该行时直接抛出致命异常并退出。

工程师删除了多余的逗号，运行 sing-box check -c config.json 确认无输出后重启服务，网关瞬间恢复全速运行。

【排查案例二】TUN 模式未配置 auto_detect_interface 导致系统陷入路由自卷死锁#

某移动办公工程师在 macOS 笔记本上配置了基于 TUN 虚拟网卡的 sing-box 客户端。在首次点击启动后，不仅海外网站无法访问，连本地局域网的 WiFi 连接也瞬间断开，笔记本散热风扇狂转，系统监视器中显示 sing-box 进程占用了 100% 的单核 CPU。

高级网络工程师介入后，调取了系统的底层路由表：

1
netstat -rn

发现系统的默认网关 default 已经被修改并指向了 singbox-tun 虚拟网卡。 随后审查了用户的 config.json：

• 在 inbounds 中配置了 "type": "tun", "auto_route": true；
• 但在 route 顶级对象中，遗漏了 "auto_detect_interface": true！

由于缺失物理网卡自动感知，当 sing-box 内部尝试将加密后的数据包发送给远端 VPS 服务器（例如 IP 为 104.28.x.x）时，操作系统查询路由表，发现发往 104.28.x.x 的默认出口仍然是 singbox-tun！于是这个本应发往公网物理光纤的数据包，被操作系统无情地再次塞回了 sing-box 自己的虚拟网卡接收队列中。数以万计的数据包在虚拟网卡与内核网络栈之间以微秒级的速度无休止死循环反弹，最终将 CPU 完全打满并造成整机断网死锁。

工程师在 route 模块中补全了 "auto_detect_interface": true，sing-box 启动时自动将发往远端 VPS IP 的静态路由绑定至真实物理 WiFi 网卡，死锁死循环当场解除。

【排查案例三】远程规则集二进制文件写入损坏导致核心启动触发 Panic#

某开发团队在其自动化持续集成（CI）服务器上部署了 sing-box 守护进程，并配置了自动拉取远程二进制规则集（.srs）。某天晚上机房因断电发生突发硬重启，第二天全量自动化部署流水线均由于网络连接失败而报错中断。

工程师在终端手动运行 sing-box 检查日志：

1
sing-box run -c config.json

终端打印了令人震惊的 Panic 崩溃：

1
panic: unexpected EOF reading binary rule-set
2
goroutine 1 [running]:
3
github.com/sagernet/sing-box/common/srs.Read(...)

工程师进入规则集缓存目录：

1
ls -lh /var/lib/sing-box/
2
# 发现 geosite-cn.srs 的文件大小竟然是 0 字节！

原来，在前一天晚上服务器断电的瞬间，sing-box 恰好正在向磁盘写入新下载的 geosite-cn.srs 规则集。由于断电导致文件写入中断，在磁盘上残留了一个损坏的 0 字节空文件。当服务器重启并再次启动 sing-box 时，核心尝试利用内存映射加载该文件，在读取二进制头部魔数（Magic Number）时遇到了非预期的文件截断 EOF，触发了底层的崩溃。

工程师删除了损坏的 0 字节缓存文件并重新启动服务，sing-box 自动重新拉取了完整的远程二进制规则集并完成加载，系统完全恢复正常。

【排查案例四】缺少 route.final 兜底出站导致未知流量全量静默丢失#

某团队在自建的海外中转节点上配置了基于 sing-box 的企业分流网关。在日常业务中，访问白名单内的国际主流云服务一切正常；然而员工在访问某些冷门的海外小众企业官网时，网页永远提示无法连接超时，且终端 curl 报错 Empty reply from server。

工程师审查了网关的完整路由表规则：

1
"route": {
2
  "rules": [
3
    { "rule_set": "geosite-cn", "outbound": "direct" },
4
    { "rule_set": "geosite-google", "outbound": "proxy-hk" }
5
  ]
6
}

原来，负责编写配置的工程师只关注了白名单内的域名，而在整个 route 字典的末尾，根本没有声明 "final" 兜底出站对象！

在 sing-box 的路由决策流水线中，如果一个网络连接既不是国内域名、也不是 Google，当它顺延流经完全部规则后，由于系统不知道该把这个未匹配的连接交给谁，内核只得将其静默丢弃，造成了冷门网站全部静默蒸发的奇特故障。

工程师在 route 模块中追加了一行：

1
"final": "proxy-hk"

将所有未明确命中的兜底流量全量导向主力代理策略组，小众网站瞬间秒开恢复。

问题一 为什么我的 sing-box 配置文件在在线 JSON 校验网站上显示完全正确但 sing-box check 依然报错#

通用的在线 JSON 校验工具仅仅是一个通用的格式检查器。它的职责只是检查文件是否符合大括号闭合、引号成对与无非法字符等通用的纯语法要求。但是，通用的 JSON 校验工具完全不懂 sing-box 的强类型结构体定义！例如：sing-box 要求 outbounds 必须是一个数组，而你在 JSON 中写成了一个字典对象；或者 sing-box 要求出站类型必须是官方注册的 shadowsocks、vless，而你手滑拼写成了 v-less。对于这种业务层面的类型映射错误与非法字段注入，通用的 JSON 工具根本无法察觉，只有原生的 sing-box check 才能实施精准穿透排查。

问题二 sing-box 中的 mixed 混合入站端口有什么优势#

传统的代理客户端通常需要分别监听 HTTP 代理端口（如 7890）与 SOCKS5 代理端口（如 7891）。而 sing-box 原生支持的 mixed 入站类型，能够在操作系统的一个单一物理端口上（例如 127.0.0.1:2080），通过首包自动嗅探技术同时兼容 HTTP、HTTPS 与 SOCKS5 协议。无论客户端发来的是标准浏览器 HTTP 代理流量、还是终端命令行 Git 发起的 SOCKS5 握手，sing-box 均能微秒级自动识别并派发给对应的处理管道，极大精简了本地端口管理并杜绝了端口冲突。

问题三 为什么编辑 sing-box 配置文件时强烈推荐使用 VS Code 而非普通文本工具#

VS Code（Visual Studio Code）是编写 sing-box JSON 配置的终极生产力工具。其核心杀手锏包括：

1. 自动语法高亮与尾随逗号实时标红：一旦在末尾多敲了一个逗号，编辑器会在毫秒级出现醒目的红色波浪线预警；
2. 支持关联官方 JSON Schema：在配置文件头部加入 Schema 声明后，VS Code 可以直接从网络拉取 sing-box 官方的字段定义，提供全局字段自动补全、未知废弃字段实时警告以及枚举值下拉建议，从源头上杜绝拼写笔误；
3. 强大的双括号匹配与格式化：快捷键一键格式化（Shift + Alt + F）能够自动对齐缩进，并对反斜杠等转义字符提供严谨的视觉着色。

问题四 sing-box 中的 rule_set 远程规则集与本地规则集到底有什么区别#

• type: remote（远程规则集）：规则集托管在 GitHub 或私有 CDN 服务器上，sing-box 会在后台自动按周期将其拉取至本地并执行持久化缓存。适合维护需要频繁动态更新的广告拦截列表（AdBlock）以及各主流流媒体平台的分流规则。
• type: local（本地规则集）：规则集文件已经以 .srs 二进制或 .json 格式预先存放在服务器的物理磁盘中。适合在没有外网访问权限的离线内网环境、企业私有网段分流，或者追求绝对零网络加载开销的高可靠生产网关环境中使用。

问题五 为什么在 TUN 模式下开启了 auto_route 还需要开启 strict_route#

auto_route: true 的作用是在系统层面自动创建针对 TUN 虚拟网卡的默认路由。而在多网卡、双栈网络（IPv4 + IPv6）或存在复杂局域网接口的环境下，操作系统的网络栈有时会通过其他物理网卡绕过 TUN 路由发送特定协议的数据包（例如由于 IPv6 路由未完全接管引发的物理真实 IP 泄漏）。开启 strict_route: true（严格路由规则） 后，sing-box 会在内核底层配置极其严苛的物理反向路径过滤与黑洞规则，确保所有未经授权旁路的流量被绝对无条件掐死，彻底消灭一切潜在的 DNS 泄漏与旁路通信风险。

问题六 为什么升级到 sing-box 1.10 之后以前运行正常的配置文件突然报错 unknown field#

这通常是因为你的配置文件中残留了已经被官方正式移除的历史弃用字段。sing-box 团队在版本迭代中遵循非常现代的工程规范：对于被宣布废弃的字段，通常只保留两个次要版本的向下兼容警告；当演进到后续大版本时，废弃字段对应的代码将被彻底物理删除。如果在现代版本中继续传入这些未知字段，且未在反序列化中忽略未知字段，Go 语言在执行类型绑定时就会直接报错中断。排查时应查阅 sing-box 官方 GitHub Release Notes 中的 Breaking Changes 说明，将旧字段替换为新标准语法。

问题七 可以在 sing-box 配置文件中添加注释吗，为什么加了双斜杠会报错#

在标准的 RFC 8259 JSON 规范中，是绝对不支持任何形式的注释（Comments）的！无论是在行首添加 // 还是使用 /* ... */，均会被标准 JSON 解析器判定为非法字符并抛出崩溃异常。 虽然部分宽松的 JSON 解析器（如 JSON5 或 JSONC）支持注释，但 sing-box 为了追求极限解析性能与原生标准规范，采用了原生的标准 Go 解析器。如果你确实需要在配置文件中做标记，最佳工程实践是利用空字段或专有的描述性字符串作为标记（例如在规则对象内部声明未被使用的自定义字段），或者在日常开发中使用 YAML 编写并配合工具自动化编译输出为纯净的生产 JSON。

问题八 为什么同一份 sing-box 配置文件在 Linux 下测试正常但在 Windows 下启动报错#

这通常是由两大跨平台环境差异引发的：

1. 文件路径表示法的冲突：Linux 采用标准斜杠 /，而 Windows 采用反斜杠 \。在 Windows 环境下如果不小心写了单反斜杠，会触发致命的转义错误；在跨平台部署中，全量统一使用标准正斜杠（如 C:/sing-box/cache.db）是唯一通用的最佳实践；
2. TUN 驱动与虚拟网卡权限差异：Linux 需要特权用户组或 CAP_NET_ADMIN 权能来创建 TUN 设备；而在 Windows 环境下，sing-box 强依赖底层的 Wintun 驱动程序。如果 Windows 系统的驱动签名被安全软件拦截、或者运行时未右键以管理员身份执行，核心在尝试加载 TUN 网卡时便会在系统调用层面抛出权限拒绝异常。

问题九 什么是 sing-box 的 DNS strategy 参数，应该如何合理选择#

strategy（DNS 查询解析策略）决定了 sing-box 在向上游发起域名解析时，究竟优先向客户端返回哪种协议类型的 IP 地址。常见取值包括：

• prefer_ipv4（优先返回 IPv4）：当前互联网全球最推荐、最稳定的黄金配置。即使目标域名同时拥有 A 记录（IPv4）与 AAAA 记录（IPv6），系统也会优先采用 IPv4 建立连接，彻底规避当前部分运营商 IPv6 国际出口骨干网拥塞与路由绕洋缺陷；
• prefer_ipv6（优先返回 IPv6）：适合本地拥有极高品质原生 IPv6 专线且需要绕过 IPv4 CGNAT 限制的特定场景；
• ipv4_only / ipv6_only：硬性强制剥离并彻底屏蔽另一种协议的解析结果，专用于排查单栈纯净度通信故障。

问题十 如何在没有 GUI 界面的 Linux 服务器上优雅热重载 sing-box 配置文件#

在云服务器生产环境中，当修改了 config.json 配置文件后，绝对不应该粗暴地使用 kill -9 或重启系统。推荐使用标准的 Linux 进程控制信号实现平滑优雅重载（Graceful Reload）：

1
# 1. 在重载前，务必先执行静态测试确保新配置百分之百合法！
2
sing-box check -c /etc/sing-box/config.json
3

4
# 2. 向正在运行的 sing-box 守护进程发送 SIGHUP 信号触发热重载
5
sudo systemctl reload sing-box
6
# 或者直接向进程 PID 发送信号:
7
sudo kill -HUP $(pgrep sing-box)

sing-box 接收到 SIGHUP 信号后，会在后台安全启动新的路由工作线程并加载新配置；确认新配置正常接管后，再平滑释放旧连接，全程实现用户完全无感知的零秒业务中断平滑升级。