sing-box报错怎么办？按关键词定位启动、连接与DNS问题
简答：把 sing-box 日志里的报错原文复制下来，先判断是导入、启动、连接还是部分网站打不开，再分别检查 JSON、端口、权限、TLS、DNS 与路由，通常能缩小到一类原因。
定义：sing-box 报错是核心读取配置、启动入站、连接远端或处理 DNS 与路由时输出的错误提示，必须结合完整日志和发生阶段判断。
先看这张表：报错发生在哪一步，处理路径就不同
把日志里的报错原文复制下来，先按出现阶段定位，不要一看到错误就删除配置或反复重装。sing-box 使用 JSON 配置，官方配置引言列出了日志、DNS、入站、出站和路由等主要结构，并提供配置检查命令。查看 sing-box 配置引言
| 发生阶段 | 常见报错或表现 | 先验证什么 | 修复后如何确认 |
|---|---|---|---|
| 下载或导入失败 | invalid character、unexpected end、远程内容无法解析 | 确认返回内容是完整 JSON，而不是 HTML、登录页或其他格式 | 配置可以保存，并能进入核心检查或启动阶段 |
| 核心启动失败 | unknown field、unknown value、address already in use、permission denied | 运行 sing-box check，再检查端口、文件权限和 TUN 权限 | 核心保持运行，日志不再出现启动中断 |
| 节点连接失败 | timeout、connection refused、handshake failure | 区分地址不可达、端口拒绝、TLS 或认证参数不匹配 | 日志出现连接建立或成功选择目标出站 |
| 部分网站打不开 | 部分域名失败、应用不走代理、IP 可访问但域名失败 | 检查 DNS、路由规则、系统代理端口和 TUN 权限 | 连接日志显示命中预期策略，并对比出口 IP 或访问结果 |
30 秒结论：check 不通过就先改配置；check 通过但启动失败就查端口和权限；启动成功但连不上就区分 timeout 与 handshake；能连接但部分网站打不开，就查 DNS、路由和 TUN。
这是一篇第三方使用指南，不代表任何客户端或线路服务的官方页面。
先收集版本、日志和配置检查结果
- 记录核心和客户端信息。记下系统、客户端名称、客户端版本、sing-box 核心版本、安装方式，以及报错发生在导入、启动、连接还是访问阶段。不同客户端可能只是图形界面不同，真正报错仍来自核心日志。
- 检查配置文件。在配置文件所在目录执行
sing-box check -c config.json。官方配置页将sing-box check列为配置检查命令；检查通过只能说明配置能够被读取和初始化，不能证明远端节点在线、端口可达或浏览器流量已经经过代理。查看官方配置检查说明 - 提高日志等级并保留上下文。官方日志配置支持
trace、debug、info、warn、error、fatal和panic等级，也支持输出到文件。排查时可临时使用：
{ "log": { "level": "debug", "output": "box.log", "timestamp": true } }
日志不要只截最后一行。应从第一处 FATAL、ERROR或WARN开始，连同后面的启动阶段、入站或出站名称一起保留。例如脱敏后的检索重点可以是：FATAL start service: initialize inbound[0]: ...，或 ERROR outbound: ... timeout。这只是截取示意，真正判断仍以你的完整原文为准。查看 sing-box 日志字段
分享日志前隐藏订阅令牌、节点密码、私钥、UUID、服务器地址、完整域名和个人 IP。只保留错误前后几行、系统版本、核心版本、配置字段名和复现步骤。
报错原文速查卡：先复制关键词，再执行验证
| 报错原文 | 通常表示 | 验证命令或检查 | 修复动作与复测 |
|---|---|---|---|
invalid characterunexpected end of JSON input | JSON 不完整、括号或引号错误，或把其他格式直接交给 sing-box | 运行 sing-box check -c config.json，并查看远程响应内容 | 修正 JSON 或改用 sing-box 格式；再次执行 check，确认无错误 |
unknown fieldunknown value | 字段不属于当前核心，或字段值不在当前版本支持范围内 | 对照官方配置文档，确认字段属于 sing-box，而不是其他内核 | 按官方字段替换，不要只删除报错行；重新 check 并启动 |
deprecated | 配置仍可被识别，但使用了官方标记为废弃的字段或功能 | 查看迁移指南和废弃功能列表 | 按迁移页的替代写法调整，完成 check 后再启动 |
address already in use | 本地监听端口已被其他进程占用 | Windows 用 Get-NetTCPConnection -LocalPort <端口>；macOS 用 lsof -nP -iTCP:<端口> -sTCP:LISTEN；Linux 用 sudo ss -ltnp | grep :<端口> | 关闭重复客户端或更改入站端口，并同步系统代理设置；重启后再次检查监听 |
permission deniedoperation not permitted | 配置、证书、规则集不可读，或创建 TUN、网络接口时权限不足 | 检查文件权限、服务用户、系统安全提示和 VPN/TUN 权限 | 只授予必要目录读取权限，按平台放行组件；重新启动并观察日志 |
rule-set 下载失败或超时 | 启动依赖的远程规则集无法下载、解析或保存 | 查看日志中的规则集 URL、超时和 HTTP 错误；测试域名解析与 HTTPS 访问 | 确认 URL、网络和保存目录可用；必要时暂时移除该依赖后单独启动验证 |
outbound not founddependency not found | 路由或入站引用了不存在的出站标签、选择器或 URLTest 标签 | 逐项比对引用名称与 outbounds中的 tag | 补齐或改正标签，确保引用对象在同一配置中声明；重新 check |
geosite、geoip 数据错误 | 旧数据文件或旧字段与当前配置方式不匹配 | 检查是否仍依赖旧 GeoIP、Geosite 数据文件和旧字段 | 按官方迁移指南改用当前规则集方式，再检查启动日志 |
timeout | 规定时间内没有完成连接，可能是地址、端口、路由或网络切换问题 | 测试域名解析和目标端口连通性 | 先修正地址、端口或网络；复测时观察日志是否进入握手或连接建立 |
connection refused | 目标地址主动拒绝连接，常见于服务未监听或端口不对 | 确认目标端口、服务端监听和本地配置 | 修正端口或启动对应服务；用端口测试确认不再立即拒绝 |
handshake failure | 已经进入握手阶段，但 TLS、认证或传输参数不匹配 | 核对 server_name、ALPN、证书校验、传输方式和认证字段 | 逐项与服务端参数一致，重新连接并确认日志进入握手完成 |
官方迁移页明确列出 TUN stack的迁移说明：应按迁移文档移除该选项；废弃列表也说明该选项已进入废弃流程。不要把其他客户端的 TUN 参数或取值直接复制到 sing-box。查看 sing-box 迁移指南 查看 sing-box 废弃功能列表
timeout、端口和 DNS：把“先测试”变成可执行命令
目标端口连不上：按系统执行测试
把 <地址>和<端口>替换为配置中的服务器地址和端口，不要使用客户端界面里显示的本地入站端口代替远端端口。
- Windows：
Test-NetConnection -ComputerName <地址> -Port <端口>。重点看TcpTestSucceeded。 - macOS：
nc -vz <地址> <端口>。系统没有可用的nc时，先安装对应系统工具或使用已安装的网络诊断工具。 - Linux：
nc -vz <地址> <端口>。若系统没有nc，按发行版包管理器安装 netcat 后再测试。
端口测试失败时，优先检查地址、端口、网络切换和远端监听；测试成功但出现 handshake failure，则不要继续反复测端口，应转向 TLS、Reality 或认证参数。
域名解析失败：分别查 Windows、macOS 和 Linux
- Windows：
Resolve-DnsName <域名>。 - macOS/Linux：
dig <域名>；没有dig时可使用nslookup <域名>。
如果系统解析失败，先检查当前网络、DNS 服务器和域名是否拼写正确；如果系统解析正常但 sing-box 仍失败，则查看 sing-box 的 DNS 配置、路由规则和日志中实际使用的解析器。官方文档把 DNS 与路由作为独立配置部分，不能把其他内核的字段直接套用。查看 sing-box 路由配置
验证本地代理是否真正转发
如果配置声明了本地 SOCKS 入站，可用：
curl -x socks5h://127.0.0.1:<端口> https://example.com -I
端口必须以配置中入站的 listen_port为准。官方监听字段文档显示，监听地址和端口由 listen与listen_port控制，sing-box 核心没有 Clash 系客户端那种固定默认端口。查看 sing-box 监听字段
复测不要只看客户端按钮是否变绿，应同时查看连接日志中命中的策略或出站标签，并对比出口 IP 或实际访问结果。
TLS、Reality、规则集和标签引用怎么分开排查
Reality 握手失败
如果日志明确指向 Reality，优先核对客户端与服务端是否使用同一组参数：客户端的 public_key、short_id、server_name以及传输方式；同时确认系统时间没有明显偏差。官方 TLS 文档列出了 Reality 的 public_key、short_id和服务器握手字段，也列出了客户端 utls及指纹字段。查看 sing-box TLS 与 Reality 字段
不要把 Reality 的握手失败直接归结为线路速度慢。端口测试成功而握手失败时，先逐项核对密钥、短 ID、服务器名称和服务端配置，复测时观察是否从握手错误变为连接建立。
rule-set 下载失败或启动卡住
如果启动日志停在远程规则集下载、解析或保存阶段，先确认规则集地址可以访问，域名能够解析，配置指定的保存路径对运行用户可读写。若规则集依赖另一个出站或 HTTP 客户端，还要检查相关标签是否已经声明。不要只删除错误日志中的最后一行，否则可能把路由依赖删掉而留下新的引用错误。
selector、urltest 或 outbound 标签不存在
sing-box 的配置通过标签关联对象。出现 not found、dependency not found或类似错误时，搜索完整配置中的引用名称，再与出站对象的 tag逐字比较，注意大小写和连字符。修复后先执行 sing-box check -c config.json，再启动并观察是否还出现初始化失败。
旧 GeoIP、Geosite 数据方式
官方迁移页面把 GeoIP 和 Geosite 的迁移列入历史变更。遇到旧数据文件、旧字段或规则集初始化错误时，应按照迁移页的对应章节改用当前配置方式，不要将旧数据库文件、其他客户端的规则格式和 sing-box 配置混用。查看官方迁移章节
Windows、macOS、Linux、Android 和 iOS 的日志入口
| 平台 | 优先查看位置 | 验证动作 | 重点差异 |
|---|---|---|---|
| Windows | 图形客户端日志页、配置指定的输出文件 | PowerShell 查询本地端口，检查核心版本、服务状态和安全软件拦截 | TUN、系统服务和防火墙权限可能影响启动 |
| macOS | 客户端服务日志或配置指定的输出文件 | 使用 lsof查端口，在“隐私与安全性”中处理系统扩展提示 | 不要照搬 Linux 的 ss命令；应用隔离和系统扩展可能影响运行 |
| Linux | systemd 服务日志或终端输出 | sudo systemctl status sing-box；sudo journalctl -u sing-box --output cat -n 50 | 专用用户必须能读取配置、证书和规则集；TUN、低端口和路由标记依赖系统权限 |
| Android | 客户端服务日志；崩溃日志位于工作目录的 stderr.log | 检查 VPN 权限、电池限制、网络切换和当前配置 | TUN 由 Android VPN 服务提供，不能照搬桌面端网卡命令 |
| iOS | 客户端设置中的服务日志 | 检查 VPN 配置允许、按需连接和当前网络权限 | NetworkExtension 提供网络扩展能力，命令行检查方式有限 |
官方 Android 客户端文档给出了工作目录和 stderr.log位置；Apple 平台文档说明可在设置中的服务日志查看崩溃信息。Linux 的官方包管理器文档则列出了 systemd 启动、重启和实时日志命令。查看 Android 客户端日志说明 查看 Apple 平台日志说明 查看 Linux 服务管理命令
仍然无法定位时，按模板提交脱敏信息
只说“sing-box报错”通常无法判断问题在哪一层。可以按下面模板整理，但不要粘贴完整订阅地址、私钥或节点密码：
系统：
客户端名称与版本：
sing-box 核心版本：
安装方式：
报错阶段：导入 / 启动 / 连接 / 部分网站打不开
完整报错原文：
sing-box check 结果：
最近 50 行日志：
目标端口测试结果：
DNS 查询结果：
是否同时运行其他代理客户端：
已隐藏：订阅令牌、密码、私钥、UUID、服务器地址、个人 IP
配置片段只保留能复现问题所需的字段，用占位符替换敏感值。若日志涉及远端服务状态，还需要单独确认远端监听、端口放行和节点参数；仅凭本地一行报错，不能判断远端服务是否正常。
完成自查后，下一步可按客户端类型继续进行sing-box 添加订阅教程，或查看sing-box 连接失败排查。
常见问题
sing-box 报错后要不要先重装？
通常不要。先保留原配置和完整日志，运行 sing-box check，再根据导入、启动、连接或 DNS 阶段处理。重装不能自动修复 JSON 字段错误、端口占用或 TLS 参数不匹配。
sing-box 的 YAML 配置可以直接导入吗？
不要默认可以。sing-box 核心使用 JSON 配置，其他客户端的 YAML 内容不能直接当作 sing-box JSON 使用。应确认远程服务是否提供 sing-box 格式，再执行配置检查。
sing-box check 通过了，为什么还是连不上？
check 主要验证配置能否被读取和初始化，不代表远端节点在线、端口可达、TLS 参数正确或浏览器流量已经经过代理。下一步看连接日志并执行端口测试。
timeout 和 handshake failure 的处理方法一样吗？
不一样。timeout 先查地址、端口和网络可达性；handshake failure 通常已经进入握手阶段，应核对 TLS、Reality、服务器名称、认证和传输参数。
Android 或 iOS 没有命令行，怎么排查 sing-box 报错？
优先打开客户端服务日志，记录核心版本、系统版本和完整错误。Android 可查看工作目录中的 stderr.log，Apple 平台可从设置中的服务日志查看崩溃信息。
端口被占用时，应该改 sing-box 还是改系统代理？
先确认哪个进程占用了配置中的 listen_port。可以关闭重复客户端，或改用未占用端口；如果改端口，还必须同步修改系统代理、应用代理或客户端设置。