sing-box 启动失败怎么办？按日志、配置、端口和权限排查
简答：sing-box 点击启动后立即退出、状态变红或出现 FATAL 时，第一步不是换节点，而是保存第一条 ERROR/FATAL 日志并执行 sing-box check -c config.json。校验通过后，再按端口占用、外部文件、TUN 权限、内核版本和远端连接分层定位。启动成功但网页打不开，则属于启动后的本地代理、DNS、路由或节点问题，不能与启动失败混为一谈。
定义：sing-box 启动失败，是指程序在加载配置或创建入站、出站服务阶段退出，常见表现包括配置解析错误、端口绑定失败、文件找不到、权限不足和字段与内核版本不兼容。
先做这一步：保存第一条错误并校验配置
先关闭自动重试，备份当前配置文件，再记录日志中最早出现的 ERROR 或 FATAL 行。后面的报错可能只是前一个错误引起的连锁结果。
- 确认你检查的是实际启动使用的配置文件，而不是下载目录中的旧文件。
- 在配置文件所在目录打开终端，执行
sing-box check -c config.json。 - 如果配置目录中有规则集、证书或其他引用文件，按原配置的相对路径保留目录结构。
- 校验通过后，再执行
sing-box run -c config.json观察启动阶段日志；窗口不要立即关闭。
官方配置说明确认 sing-box 使用 JSON 配置，并提供 check、format 与 merge 命令。可参考 官方配置文件说明。如果你使用图形客户端，日志入口名称会随平台和版本变化，应以当前界面中的服务日志、运行日志或错误详情为准。
错误关键词对照：先判断卡在哪一层
| 日志关键词或现象 | 优先怀疑 | 下一步操作 |
|---|---|---|
invalid character、unexpected end | JSON 语法不完整或多了逗号 | 用 check 校验，检查报错行附近的引号、括号和逗号。 |
unknown field、deprecated | 字段已废弃、移除或版本不匹配 | 对照当前官方配置文档和迁移说明，删除旧字段或改为当前字段。 |
address already in use | 本地 HTTP、SOCKS 或 API 端口已被占用 | 关闭其他代理客户端，或把当前配置中的监听端口改为未占用端口后重新校验。 |
no such file、cannot open | 规则集、证书、私钥或 Geo 文件路径错误 | 检查相对路径基准、文件名大小写和文件是否真的存在；不要只复制配置文本。 |
Access is denied、permission denied | TUN、系统扩展或文件权限不足 | 先关闭 TUN 验证普通代理能否启动，再按系统授权或管理员权限重新运行。 |
| 启动成功但网页打不开 | 本地代理未接管、DNS、路由或节点握手问题 | 测试本地监听端口，再分别检查 DNS、远端连接和应用代理设置。 |
表中的关键词用于定位方向，不代表单个关键词只有一种原因；必须以同一时间点的完整日志和配置结构复核。
配置校验失败：JSON、字段和版本逐项处理
1. 先排 JSON 语法，不要先改节点
订阅内容如果实际返回的是 HTML 登录页、错误提示、Clash YAML 或被截断的 JSON，直接保存为 config.json 后一定可能无法启动。打开文件开头检查是否以 JSON 对象或数组形式开始；如果出现网页标题、登录表单或 YAML 缩进语法，应回到订阅导出或转换步骤重新获取。不要把包含订阅令牌、密码、私钥的完整文件上传到公开解析器或聊天群。
2. 再查字段是否属于当前内核
版本升级后，旧字段可能被标记为废弃，甚至已经移除。官方迁移文档列出了多个版本的字段变化，例如 TUN 的 stack 在较新版本中已标记为废弃，部分旧 DNS、规则和出站字段也有迁移要求。应以官方迁移说明和官方废弃功能列表为准，不要根据第三方模板猜测字段。
3. 最后查外部文件和相对路径
规则集可能使用本地文件路径，也可能在启动时读取远程规则集。官方文档说明本地规则集需要有效的 path，远程规则集可以配置 url，并支持 initial_path 作为启动时的初始内容。若日志提示文件不存在、无法读取或下载失败，先临时移除非必要规则集，确认基础配置能否启动，再逐项恢复。相关字段可查官方 rule-set 文档。
启动失败但配置校验通过：排查端口、内核和权限
端口占用
如果出现 address already in use，先退出其他代理软件、旧的 sing-box 进程和带 API 服务的客户端，再重试。若必须并行运行，分别修改 HTTP、SOCKS、mixed 或 Clash API 的监听端口，并同步修改浏览器或系统代理设置。不要只改一个端口后忽略配置中其他监听项。
内核文件或程序路径
如果点击图形客户端后无窗口、无状态变化或程序立即消失，先从终端直接运行内核，让错误停留在窗口中。确认程序路径没有指向已删除的文件，配置路径没有使用失效的移动磁盘或临时目录；若安全软件隔离了内核文件，应在本机安全软件记录中核对，不要下载来源不明的替代文件。
TUN 与系统权限
TUN 需要创建虚拟网络接口，权限要求取决于系统和客户端。Windows 命令行运行时，如果日志出现 configure tun interface: Access is denied，官方仓库中的问题记录显示，这类情况应优先检查管理员权限；可以先关闭 TUN，仅启动普通 HTTP、SOCKS 或 mixed 入站，以区分“配置整体失败”和“TUN 权限失败”。官方桌面客户端文档说明其提供 TUN 透明代理功能，支持的系统和权限行为应以当前客户端说明为准，见官方桌面客户端文档。
移动端与 Apple 平台
Android 图形客户端通过系统 VPN 服务提供非特权 TUN，官方说明其崩溃日志位于工作目录下的 stderr.log；Apple 平台可在设置中的服务日志入口查看崩溃或运行日志。若系统弹出 VPN、网络扩展、文件访问或本地网络授权，先完成授权，再重新启动服务。相关平台行为可参考Android 官方特性说明和Apple 平台官方特性说明。
启动成功但不能联网：不要再按“启动失败”处理
- 测本地端口：确认配置中的入站监听地址和端口确实处于运行状态；浏览器或系统代理必须填写同一个本地地址和端口。
- 测 DNS：如果日志显示域名解析失败，暂时减少 DNS 分流规则，先验证一个最小 DNS 配置是否能工作。
- 测路由：检查规则是否把目标流量送到不存在或未启动的 outbound；启用 TUN 时，先关闭 TUN 并用普通代理测试。
- 测节点握手：只有在本地端口和 DNS 正常后，才检查服务器地址、端口、TLS、认证、SNI 或传输参数。此时的
timeout、handshake failed不等于配置启动失败。 - 测应用范围：系统代理通常不能接管所有 UDP、ICMP 或不读取系统代理的应用；官方客户端说明也区分了系统代理、防火墙重定向和虚拟接口三类方式，见官方客户端工作方式说明。
最小化恢复与回滚流程
- 复制原配置为只读备份，例如
config.backup.json，不要直接覆盖原文件。 - 保留一个最小配置：一个可确认存在的入站、一个 outbound，以及必要的日志设置；暂时移除 TUN、远程规则集、复杂 DNS 分流和非必要证书引用。
- 执行
sing-box check -c config.json，通过后再运行。 - 每次只恢复一个模块：先恢复节点，再恢复 DNS，再恢复规则集，最后恢复 TUN；每一步都记录是否能启动。
- 一旦恢复某项后再次失败，回滚该项，并把对应日志关键词与配置片段单独核对。
不要用“重装客户端、换节点、改 DNS”同时处理多个变量，否则无法判断真正原因。配置能启动后，再逐项恢复原功能，才容易保留可回滚的工作版本。
常见问题 FAQ
sing-box check 通过了，为什么仍然启动失败？
check主要验证配置结构和字段，不能替代实际运行。若校验通过仍失败，继续查端口占用、文件权限、TUN 权限、系统服务和外部资源读取。
订阅链接打不开，是不是 sing-box 内核启动失败？
不一定。订阅下载失败属于获取配置阶段；配置已保存但点击启动退出，才是启动阶段问题。先确认返回内容是不是有效 JSON，再执行 check。
出现 unknown field 应该升级还是降级？
先对照当前官方迁移和废弃字段说明，确认字段是应删除、改名还是需要匹配其他版本。修改前备份；无法确认时不要盲目升级或降级。
Windows 下 TUN 启动报 Access is denied 怎么办？
先关闭 TUN 验证普通代理是否能启动，再检查客户端是否需要管理员权限、虚拟网卡和安全软件拦截。若仍不清楚，保留完整日志并按当前客户端文档处理。
启动后网页打不开，应该先换节点吗？
不应该。先确认本地代理端口、系统代理和 DNS，再检查路由与节点握手；只有本地链路正常而远端握手失败时，才进入节点参数排查。
常见问题
sing-box check 通过了，为什么仍然启动失败？
check 通过不代表端口、权限和外部文件都正常。继续检查监听端口、TUN 权限、规则集路径、证书文件和系统安全软件。
订阅链接打不开，是不是 sing-box 内核启动失败？
不一定。订阅下载失败属于获取配置阶段；配置保存后点击启动退出，才属于启动阶段。先确认保存内容是有效 JSON。
出现 unknown field 应该升级还是降级？
先对照官方迁移和废弃字段说明，确认字段应删除、改名还是匹配其他版本。修改前先备份，不要盲目升级或降级。
Windows 下 TUN 启动报 Access is denied 怎么办？
先关闭 TUN 验证普通代理能否启动，再检查管理员权限、虚拟网卡和安全软件拦截。保留完整日志后按当前客户端说明处理。
启动后网页打不开，应该先换节点吗？
不应该。先确认本地代理端口、系统代理和 DNS，再检查路由与节点握手；远端连接失败时才排查节点参数。