日志定位问题：先看第一条错误，再改配置

日志先调到能看的程度

官方日志结构很简单，新手先看这两个字段：

{
  "log": {
    "level": "info",
    "timestamp": true
  }
}

• level：可选 trace、debug、info、warn、error、fatal、panic，从详细到简略依次排列。平时用 info 就够，排查时临时调到 debug，查完调回来；长期开 trace 或 debug 会让日志量暴涨，还可能把敏感信息写进日志文件。
• output：日志文件路径；设了它，日志就写文件、不再输出到控制台，适合长期留档。没设时，看控制台或图形客户端的日志面板。
• timestamp：每行是否带时间，排查“什么时候开始出问题”时很有用，建议保持开启。
• disabled：设为 true 就不输出日志，排查期间不要开它。

图形客户端的日志入口各不相同，有的在设置里，有的在主界面面板里；命令行用户则看控制台输出或 journalctl（systemd 服务时），见服务端那篇的日志命令。

启动前先跑 check，不要靠重启碰运气

命令行用户在启动前先跑：

sing-box check -c config.json
sing-box format -w -c config.json

check 会指出第一处校验错误，format 会把格式理顺。图形客户端用户没有命令行时，同样要看客户端弹出的第一条启动错误，而不是反复点启动、反复重装。

排查时只盯第一条错误：后面的错误常常是第一条引起的连锁反应，修了第一条，后面的可能自己消失。一次只修一个错误，修完重新校验、重新启动、重新验证，不要一次改五处。

常见报错按四类查

1. 字段与格式类

表现：启动直接报错，提到字段名、类型、JSON 语法。

• 字段名拼错、大小写错、括号或逗号缺失，先 format 再看。
• 字段类型不对，例如该填数字的地方填了字符串，该填数组的地方只填了一个值。
• 引用了不存在的 tag：出站、DNS 服务器、规则集的 tag 都要和声明处一模一样。
• 字段在当前版本已改名或移除：对照官方文档和版本变更说明，不要从旧教程里照搬旧字段。

2. 端口与文件类

表现：提到端口占用、文件找不到、规则集读取失败。

• 入站监听端口被别的程序占了，换一个端口再试；不要和系统服务、其他代理程序抢同一个端口。
• 本地规则集、证书、密钥文件路径不对，或服务用户读不到那个文件；以 root 检查通过，不代表服务用户也能读到。
• 远程规则集下载失败，先看 URL、网络和缓存，不要直接换结构凑合。

3. 权限与冲突类

表现：服务能启动，但流量不进来，或 TUN、VPN 建不起来。

• VPN、网络扩展、防火墙权限没给，见各平台篇。
• 同时开了两个 VPN 或代理程序，先关掉其他的，只留一个验证。
• TUN 路由环路、局域网排除没设，见 TUN 那篇。

4. 版本与协议类

表现：旧配置在新版本上启动失败，或某个协议突然不支持。

• 先看报错提到的字段在目标版本里还存不存在，再看配置提供方有没有按目标版本更新。
• 不要只删掉报错字段硬启动，删 DNS 或路由字段会改变流量处理方式。
• 协议支持变化要查官方说明，例如 SSR 支持已移除、GeoIP 写法已移除，都是版本层面的变化，不是客户端坏了。

求助前准备什么

• 系统、客户端与内核版本，失败步骤，脱敏后的第一条错误。
• 脱敏：远程地址里的令牌、节点密码、密钥、真实服务器地址，先换成占位符再发；日志文件里也可能含这些信息，分享前先搜一遍。
• 不要发整份配置：发第一条错误和相关的一小段配置就够了，整份配置既暴露隐私，也让别人难定位。