sing-box v1.14.3 安装后的配置检查与常见问题
简答：安装 sing-box v1.14.3 后，建议先确认实际运行版本，再使用 sing-box check 检查配置文件，必要时用 format 格式化配置；如果检查通过但仍无法连接，再按日志、DNS、路由、证书、端口和 TUN 权限顺序排查。v1.14.3 的官方发布说明只写明为修复与改进，因此不要仅凭版本号推断配置字段发生了变化。
定义：sing-box 配置检查，是在启动代理服务前，用 sing-box 自带命令和官方 JSON Schema 验证配置结构、字段和引用关系是否符合当前版本要求的过程。
先确认 v1.14.3 是否真的在运行
安装包名称、桌面客户端显示的版本和命令行实际调用的二进制文件可能不是同一个对象。排查前先确认当前终端调用的是目标版本，否则可能出现“配置在另一台设备可用、当前设备报字段错误”的情况。
- 打开终端或命令提示符，执行
sing-box version。 - 确认输出版本为
1.14.3，并记录实际执行文件所在目录。 - 如果系统提示找不到命令，先检查 PATH，或在 sing-box 可执行文件所在目录执行命令。
- 如果你使用的是图形客户端，在客户端的核心、内核或关于页面确认版本；图形客户端的配置管理方式可能与独立命令行程序不同。
官方 GitHub 的 v1.14.3 发布页将本次发布说明概括为“Fixes and improvements”，没有在发布说明中列出可据此直接修改的新增配置字段。因此，升级后应以当前版本文档和配置检查结果为准，不要照搬不适用的旧示例。可查看v1.14.3 官方发布说明。
安装后第一步：检查并格式化配置文件
sing-box 使用 JSON 配置文件。进入配置文件所在目录后，先执行检查命令：
sing-box check -c config.json
如果你的构建版本对参数显示方式不同，也可以先执行 sing-box check --help 查看帮助。官方中文配置文档明确提供了 sing-box check 检查命令，以及用于格式化配置的 sing-box format -w -c config.json -D config_directory 示例，参见sing-box 官方配置引言。
- 复制一份原始配置文件，保留备份，不要直接覆盖唯一副本。
- 检查 JSON 语法：键名必须使用双引号，不能留下多余逗号，字符串中的反斜杠需要正确转义。
- 执行
sing-box check -c config.json，先处理第一条报错，再重新检查。 - 检查通过后，再执行格式化命令，统一缩进，方便人工比对。
- 如果配置来自订阅或远程地址，先保存到本地，再检查本地文件内容和文件编码。
配置能通过检查，只代表结构和字段基本符合当前程序要求，不等于服务器地址、认证信息、DNS 或路由一定可用。后续仍需要查看启动日志并进行实际连接测试。
用 JSON Schema 提前发现字段拼写错误
sing-box 官方提供 JSON Schema，可供支持 Schema 的编辑器进行补全和验证。配置文件可以加入：
"$schema": "https://sing-box.sagernet.org/schema.json"
也可以使用当前安装二进制生成与版本匹配的本地 Schema：
sing-box schema -o schema.json
官方说明指出，生成的 Schema 反映当前构建中包含的功能。对于 v1.14.3，优先使用当前程序生成的 Schema，有助于减少“文档版本与程序版本不一致”的误判。具体用法见sing-box JSON Schema 文档。
编辑器提示未知字段时，重点检查以下问题：字段是否拼写错误；字段是否放错层级；字段是否属于其他类型的入站、出站或路由规则；复制的示例是否来自更高版本；是否仍在使用已经废弃的旧字段。
v1.14 系列配置升级时重点检查什么
v1.14 系列的迁移文档列出了若干需要留意的兼容性问题。即使 v1.14.3 的发布说明没有展开列出变化，旧配置仍可能因为此前版本的弃用项或 DNS 规则行为而在启动时失败。
- DNS 旧字段：
independent_cache已被标记为废弃，迁移时应按照官方迁移文档处理。 - DNS 地址过滤规则：部分旧式地址过滤字段与 v1.14 系列新增的 DNS 规则能力组合时可能被拒绝，需要参考官方的 response matching 迁移方式。
- DNS 缓存：如果需要持久化 DNS 缓存，应核对
store_dns等当前字段，不要继续照抄旧的store_rdrc示例。 - 证书配置：旧的内联 ACME 配置已被标记为弃用，相关场景应查看 certificate provider 的迁移说明。
- 规则集：规则集源格式和版本要与当前程序支持范围对应，不能只看文件扩展名判断是否兼容。
这些项目不代表每个配置都必须修改。正确做法是先运行 check，再根据具体报错定位；不要为了“升级兼容”而盲目删除字段。可参考官方迁移指南和官方 DNS 配置文档。
检查通过但启动失败：按这个顺序排查
- 先看完整日志：临时将日志级别设为
info或debug，确认错误发生在加载配置、解析域名、建立 TLS 连接，还是监听本地端口。日志字段包括disabled、level、output和timestamp，可参照官方日志配置说明。 - 再查路径：相对路径通常受工作目录影响。证书、规则集、数据库和日志文件如果使用相对路径，确认启动方式与手动执行时的工作目录一致。
- 检查端口占用：如果提示 bind、listen 或 address already in use，确认本地监听端口没有被其他程序使用，并核对配置中的
listen与listen_port。 - 检查 DNS：能启动但域名无法解析时，确认 DNS 服务器标签、
dns.final和 DNS 规则引用的标签确实存在。官方文档说明final用于指定默认 DNS 服务器标签。 - 检查 TLS：若出现证书、SNI 或握手错误，核对服务器名称、证书校验选项、系统时间和远端配置，不要先把证书校验关闭作为长期解决方案。
- 最后检查 TUN：若命令行服务正常但系统流量不通，确认 TUN 所需权限、系统网络扩展、防火墙和路由是否允许；这类问题通常不是 JSON 语法错误。
常见问题快速对照
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
sing-box check 直接失败 | 命令路径、配置路径、JSON 语法 | 先执行 sing-box version 和 sing-box check --help，再确认配置文件位置 |
| 提示 unknown field | 字段版本、拼写、层级 | 用当前二进制生成 Schema，并对照官方配置文档 |
| 配置检查通过但无法启动 | 端口、文件权限、证书路径 | 查看完整日志，按第一条错误处理 |
| 启动正常但域名打不开 | DNS 服务器、规则顺序、final | 确认 DNS 标签存在，并检查规则是否把请求送到预期服务器 |
| TUN 开启后没有网络 | 系统权限、路由、DNS 劫持与排除项 | 先关闭 TUN 验证基础出站，再逐项恢复 TUN 设置 |
一套可复用的安装后检查清单
如果你不确定问题位于哪里，可以按下面顺序执行，避免同时修改多个参数：
- 确认文件来源和配置备份。
- 执行
sing-box version，确认实际版本。 - 执行
sing-box check -c config.json。 - 用 JSON Schema 检查字段拼写和层级。
- 执行格式化命令，减少缩进和隐藏字符造成的误读。
- 启动后先观察日志，不要立即打开 TUN。
- 先测试本地入站或基础出站，再测试 DNS 和路由规则。
- 最后启用 TUN、规则集和系统代理，并记录每次修改。
如果配置来自第三方订阅，建议把订阅导入、核心启动、DNS 解析、路由匹配和实际应用访问分成五个阶段验证。这样可以判断问题是在配置内容、客户端界面、系统权限，还是网络本身，避免把所有故障都归因于 v1.14.3。
常见问题
sing-box v1.14.3 安装后必须修改配置吗？
不一定。v1.14.3 官方发布说明只写明为修复与改进，不能据此判断所有配置都需要改动。建议先备份配置并执行 check，只有出现具体报错或使用了已废弃字段时再按官方迁移文档调整。
sing-box check 检查通过，为什么还是连接不上？
check 主要验证配置结构和字段使用情况，不能证明远端地址、认证信息、DNS、TLS、端口或系统权限一定可用。请查看启动日志，再按 DNS、TLS、端口、路由和 TUN 权限顺序排查。
配置文件中加入 $schema 有什么用？
$schema 可以让支持 JSON Schema 的编辑器提供字段补全和校验。官方还支持用 sing-box schema -o schema.json 生成与当前构建匹配的本地 Schema，适合检查字段拼写和层级。
升级到 v1.14.3 后出现 unknown field 怎么办？
先确认当前实际运行的二进制版本，再检查字段是否来自更高版本、旧版本或其他程序的示例。不要直接删除字段，先对照官方配置文档和迁移指南确认替代写法。
TUN 模式启动后没有网络，是配置语法问题吗？
不一定。若配置已经通过 check，问题可能来自系统权限、网络扩展、路由排除项、DNS 或防火墙。建议先关闭 TUN 验证基础出站，再逐项恢复 TUN 相关设置。