教程

用 sing-box check 与 format 管理 JSON 配置

把配置检查、格式化和合并命令纳入修改及部署前流程,减少配置错误。

sing-box 是配置驱动的软件。即使只改了一条规则,也值得在运行服务之前做机器可执行的检查。配置页面列出了 checkformatmerge 三类命令,本页把它们整理为维护步骤。

修改前:保存输入来源

先保留当前可工作的配置副本,或将配置纳入版本控制。若配置中有密钥、服务器地址或个人标识,备份和仓库都必须采用适当的访问控制,不能直接发布为公开示例。

同时记录当前二进制版本。配置字段随版本演进,一份在旧版本可解析的文件,不一定能在升级后的稳定版继续使用。

启动前:执行配置检查

检查命令为:

sing-box check

它应成为这些动作前的固定步骤:

  • 初次安装并准备启动服务之前;
  • 修改 DNS、路由、入站或出站之后;
  • 更换规则集来源或格式之后;
  • 二进制升级且完成迁移修改之后。

检查通过说明配置能被当前程序接受,但不代表路由选择、DNS 结果或远端连接一定符合预期。启动后仍需检查日志并验证目标流量路径。

编辑后:格式化配置

格式化命令为:

sing-box format -w -c config.json -D config_directory

-w 会写回文件。在执行写回操作前,先保留变更记录,这样可以查看格式化和人工编辑分别带来的差异。格式统一能够降低审查配置时的噪声,但不能代替字段兼容性核验。

多份输入:谨慎使用 merge

合并多份输入时可以使用:

sing-box merge output.json -c config.json -D config_directory

当维护流程把配置分成多个输入时,生成输出后仍需重新执行 check,并明确哪个文件是真正部署输入。不要在不清楚覆盖顺序时直接以合并结果替换运行中的配置。

升级时加一层检查

检查命令只能针对已经安装的版本执行。准备升级时,应先对照弃用列表和迁移说明,再对修改后的配置执行检查。特别是来自旧教程的 GeoIP 或 Geosite 写法,已经在 1.12.0 被移除。

相关文档