sing-box常见问题排查：99%的用户都会遇到的坑

引言

sing-box作为一款功能强大的通用代理平台（The universal proxy platform），在使用过程中难免会遇到各种问题。本文将针对用户最常遇到的配置错误、连接失败、日志分析等问题提供系统性的排查方案，帮助你快速定位并解决99%的常见故障。官方配置文档可参考docs/configuration/index.zh.md。

一、配置文件错误：新手最容易踩的坑

1.1 JSON格式校验失败

配置文件采用JSON格式，任何语法错误都会导致启动失败。典型错误包括缺少逗号、引号不匹配或括号未闭合。

解决方法：使用官方提供的配置检查工具：

sing-box check -c config.json

该命令会验证配置文件的语法正确性，对应源码实现见box.go中的New函数，它会在初始化阶段解析并验证配置。

1.2 必选字段缺失

sing-box配置有严格的结构要求，缺少必选字段会触发明确的错误提示。例如入站（inbounds）和出站（outbounds）配置是核心必填项。

常见错误示例：

{
  "inbounds": [],  // 缺少具体入站配置
  "outbounds": []   // 缺少具体出站配置
}

正确配置参考：

{
  "inbounds": [
    {
      "type": "socks",
      "listen": "127.0.0.1",
      "port": 1080
    }
  ],
  "outbounds": [
    {
      "type": "direct"
    }
  ]
}

完整配置结构说明见docs/configuration/index.zh.md。

二、连接失败：网络问题的诊断流程

2.1 "Connection refused"错误排查

当出现连接拒绝错误时，通常有以下三种可能：

1. 服务未启动：检查sing-box进程是否正常运行
2. 端口被占用：使用netstat -tulpn | grep sing-box查看端口占用情况
3. 防火墙拦截：确保系统防火墙允许对应端口通信

2.2 超时问题（Timeout）

超时错误通常与网络延迟或目标服务器不可达有关。可通过以下方式定位：

增加日志 verbosity 级别： 在配置文件中设置详细日志：

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

日志系统实现见log/目录下的相关文件，调试模式下会输出详细的网络交互过程。

启用调试HTTP服务器： sing-box内置调试HTTP服务，可通过源码debug_http.go中的ServeDebugHTTP函数启用，访问http://127.0.0.1:9090/debug查看实时连接状态。

三、日志分析：故障排查的核心工具

3.1 日志级别配置

日志级别从低到高分为：trace、debug、info、warn、error、fatal。默认级别为info，排查问题时建议设为debug。

配置示例：

{
  "log": {
    "level": "debug",
    "output": "sing-box.log",
    "timestamp": true
  }
}

日志工厂实现见log/factory.go，可通过log/level.go查看详细的日志级别定义。

3.2 关键错误日志解析

错误关键词	可能原因	解决方案
invalid config	JSON语法错误或字段缺失	使用sing-box check验证配置
failed to dial	网络连接问题	检查目标服务器可达性
certificate verify failed	TLS证书问题	配置insecure: true临时绕过（生产环境不建议）
address already in use	端口冲突	更换监听端口或终止占用进程

四、高级调试：开发者模式技巧

4.1 启用内存调试

通过设置调试选项可以监控内存使用情况，相关代码见debug.go:

debug.SetGCPercent(100)        // 调整GC频率
debug.SetMaxStack(1 << 20)     // 设置最大栈大小
debug.SetMemoryLimit(1 << 30)  // 设置内存限制

4.2 运行时调试HTTP服务

启用内置的调试HTTP服务器：

sing-box run -c config.json --debug http://127.0.0.1:6060

实现代码见debug_http.go，启动后可访问/debug/pprof查看性能分析数据。

五、常见问题速查表

5.1 启动问题

症状	检查项	参考文档
进程立即退出	日志文件权限、配置格式	docs/configuration/index.zh.md
无任何输出	日志级别设置过高	log/level.go
权限错误	监听端口是否需要root权限	constant/os.go

5.2 网络问题

症状	检查项	参考代码
所有网站无法访问	路由规则配置、DNS设置	route/router.go
部分网站无法访问	分流规则错误	rule/conds.go
速度慢	启用mux多路复用	common/mux/client.go

六、总结与社区支持

遇到本文未覆盖的问题时，可通过以下途径获取帮助：

1. 查阅官方完整文档：docs/
2. 检查现有GitHub Issues（搜索关键词）
3. 提交新Issue时务必附上详细日志和配置文件

通过系统的排查流程和工具链，绝大多数sing-box问题都能在几分钟内定位并解决。记住：详细的日志是排查问题的关键，善用sing-box check和调试模式可以大幅提高排障效率。