sing-box常见问题排查：99%的用户都会遇到的坑
【免费下载链接】sing-box The universal proxy platform 
项目地址: https://gitcode.com/GitHub_Trending/si/sing-box
引言
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"错误排查
当出现连接拒绝错误时，通常有以下三种可能：
- 服务未启动：检查sing-box进程是否正常运行
- 端口被占用：使用
netstat -tulpn | grep sing-box查看端口占用情况 - 防火墙拦截：确保系统防火墙允许对应端口通信
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 |
六、总结与社区支持
遇到本文未覆盖的问题时，可通过以下途径获取帮助：
- 查阅官方完整文档：docs/
- 检查现有GitHub Issues（搜索关键词）
- 提交新Issue时务必附上详细日志和配置文件
通过系统的排查流程和工具链，绝大多数sing-box问题都能在几分钟内定位并解决。记住：详细的日志是排查问题的关键，善用sing-box check和调试模式可以大幅提高排障效率。
【免费下载链接】sing-box The universal proxy platform 项目地址: https://gitcode.com/GitHub_Trending/si/sing-box
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
