连接故障故障排查
sing-box 配置无法启动怎么办？常见报错与解决方法
sing-box 启动失败、Profile 报错、decode config 错误的排查方法：订阅格式、配置字段版本差异、TUN 权限与端口冲突逐项解决。
本文目录
直接回答：sing-box 起不来九成是配置问题：① 确认用的是 sing-box 格式订阅（不是 Clash YAML）；② 客户端升级到最新版（字段随版本变化快）；③ TUN 需要系统授权；④ 端口冲突改 inbound 端口。报错信息都会写明第几行哪个字段，照着改即可。
问题现象
Profile 导入报错；点启动立即失败；日志出现 decode config error、unknown field、bind: address already in use、permission denied。
按报错处理
| 报错关键词 | 原因 | 解决 |
|---|---|---|
| decode / unknown field | 配置与内核版本不匹配 | 升级客户端；要机场对应版本订阅 |
| yaml / 解析失败 | 拿了 Clash 订阅硬导 | 换 sing-box 格式订阅 |
| address already in use | 端口被占 | 关闭其他代理软件或改端口 |
| permission denied | TUN 无权限 | 管理员运行 / 授权系统扩展 |
| fetch 失败 | 订阅拉取问题 | 见订阅更新失败排查 |
逐步排查
- 机场面板确认存在「sing-box」专用订阅入口，复制该链接重建 Profile；
- 客户端（SFI/SFA/SFM/SFW）升级到最新版本——sing-box 1.x 各小版本字段差异真实存在；
- 首次启动按系统提示完成 VPN/扩展授权；
- 报错带行号时，多为机场模板小问题：反馈给机场客服比自己改稳妥；
- 启动成功但没网 → 已是另一类问题，转节点连接不上。
什么时候是机场问题
同版本客户端、官方示例配置能跑而机场订阅必报错 → 机场模板与当前内核不兼容，找客服要更新。基础使用流程见 sing-box 入门教程。
各平台安装与官方发布渠道说明见sing-box 使用入门教程；升级后配置失效的通用处理见客户端更新后无法使用；同类问题见网络问题排查 · 客户端与系统。
排查顺序速查
| 顺序 | 检查对象 | 验证方法 |
|---|---|---|
| 1 | 本地网络 | 关闭代理，确认普通网页是否正常 |
| 2 | 订阅与节点 | 核对有效期与配置，单独测试一个节点 |
| 3 | DNS 与路由 | 查看客户端日志，每次只改变一个设置 |
常见问题
提示 decode config 或 unknown field？
配置字段与内核版本不匹配：机场的 sing-box 订阅按旧版或新版格式生成。升级客户端到最新版，或让机场提供对应版本的订阅。
导入 Clash 订阅为什么失败？
sing-box 不直接吃 Clash YAML。要用机场提供的 sing-box 格式订阅；没有就换用带转换的客户端或直接用 Clash 系客户端。
桌面端启动提示权限错误？
TUN 模式需要管理员/授权：macOS 允许系统扩展，Windows 以管理员运行，Linux 需要 root 或相应 capability。
