← 返回 WUXX Network Acceleration - 无限制畅享全球网络加速，获取与全球数百内容供应商互联的网 首页

sing-box 配置报错怎么排查？先定位错误类型再修改配置

更新于 2026-10-30 · wuxx.online

简答：sing-box 配置报错，最快的处理顺序是：先备份配置，确认实际内核版本，再执行 sing-box check，最后根据错误原文检查 JSON、订阅格式、字段版本和出站标签。不要一看到启动失败就删掉整份配置或直接升级；不同版本对 TUN、DNS、特殊出站和规则集字段的要求可能不同。本文是技术博客型使用指南，WUXX 不是 sing-box 官方站点，版本和字段应以当前官方文档及本机日志为准。

定义：sing-box 配置报错，是 sing-box 在读取、校验或运行 JSON 配置时发现语法、字段、引用关系或运行环境不符合当前内核要求。

先试这一步：备份、确认版本、执行 check

如果 sing-box 刚修改配置后无法启动，先停止当前实例并复制一份原文件，例如保存为 config.backup.json。这是回滚用备份，不要覆盖原文件。然后在同一终端执行 sing-box version，记录实际内核版本；图形客户端、系统服务、容器和命令行可能使用不同的二进制文件，不能只看下载文件名判断版本。

  1. 入口：打开运行 sing-box 的终端、服务脚本或客户端日志页面。
  2. 输入：确认配置文件路径，例如 config.json，并确认该路径确实是当前实例使用的文件。
  3. 预期结果：执行 sing-box check -c config.json 后，配置通过校验，或输出带有字段路径、行号、列号的错误。
  4. 失败后的下一步：如果终端提示参数不存在，先执行 sing-box --help 和 sing-box check --help，以当前发行版显示的参数为准。不同封装客户端可能没有暴露完整 CLI 命令。

官方配置文档提供了 sing-box check、sing-box format -w -c config.json -D config_directory 和 sing-box merge 等命令。format -w 会写回文件，使用前必须保留备份；第一次排错建议先只执行 check，不要让格式化命令直接改写原文件。参见 sing-box 配置文档。

报错原文速查：先判断是哪一层出问题

日志关键词或现象优先检查处理动作
invalid character、row 1, column 1文件是否真的是 JSON；是否误导入网页、Clash YAML 或 Base64 文本用文本编辑器打开文件，确认首字符是 JSON 对象或数组的合法内容；不要把其他客户端订阅原文直接改名为 .json
unknown field字段拼写、字段层级和实际内核版本对照当前版本文档；如果来自旧配置，查看官方 Deprecated 和 Migration 页面，不要盲目删除整个父级对象
missing tags、出站列表为空出站对象是否有 tag，selector 或 urltest 的引用列表是否为空检查完整的 outbounds 结构和过滤条件；不能仅凭这句错误断定一定是正则没有匹配节点
outbound not foundroute 规则、final、DNS 或其他字段引用的 tag逐个核对引用值与出站对象的 tag，大小写和标点也要一致
TUN 字段报错是否仍使用 inet4_address、inet6_address 或旧的 stack先确认版本，再按官方迁移表合并地址字段或移除已废弃选项
配置能启动但无法访问DNS、路由 final、TUN 权限、出站连接和系统网络一次只改一个变量，先关闭 TUN 验证普通出站，再查看运行日志

这张表只能帮助确定第一检查点，不代表每条日志只有一种原因。尤其是 missing tags，必须结合完整错误路径、出站类型和过滤条件确认。

JSON 语法错误：先修括号、逗号和文件类型

如果错误包含 invalid character、unexpected end of JSON input 或行列号，优先按 JSON 语法处理，而不是先怀疑节点不可用。常见原因包括多写一个逗号、少写一个右括号、字符串没有使用双引号、把注释写进不支持注释的文件，或者下载到 HTML 错误页。

  1. 在编辑器中打开配置并跳转到报错行、列；如果行号是 1、列号是 1，先检查文件开头是否为网页提示、订阅说明或 Base64 文本。
  2. 确认键名和字符串使用双引号，例如 "log"，不要使用单引号。
  3. 检查最近一次修改附近的逗号、{} 和 [] 是否成对。
  4. 保存为 UTF-8 文本后重新执行 check；如果错误位置改变，说明语法层已前进，再处理下一条逻辑错误。

如果你拿到的是 Clash YAML、纯节点列表、Base64 订阅或客户端专用链接，它们并不因为文件扩展名改成 .json 就变成 sing-box JSON。应使用提供方明确支持的 sing-box 格式，或通过可信转换工具生成配置后再检查；无法确认格式时，不要把原文直接粘贴进 outbounds。

版本升级后的字段报错：按已移除和计划移除区分

sing-box 官方废弃列表明确区分“某版本开始废弃”和“后续版本移除”。这意味着同一份旧配置在不同内核上可能表现为警告、unknown field 或启动失败。以下边界可作为检查顺序：

迁移起点配置变化移除或行为边界
1.10.0TUN 的 inet4_address、inet6_address 合并为 address；路由地址和排除地址也合并旧字段在 1.12.0 移除
1.11.0旧的 block/dns 特殊出站、部分旧入站字段等进入迁移范围旧特殊出站及相关旧字段在 1.13.0 移除
1.12.0DNS 服务器格式重构；旧 outbound DNS 规则项进入迁移范围旧 DNS 服务器格式在 1.14.0 移除
1.14.0远程 rule-set 的 download_detour、隐式默认 HTTP client 等进入废弃范围download_detour 和相关旧行为计划在 1.16.0 移除
1.15.0TUN 的 stack 选项废弃，官方说明建议使用 sing-tun 自有 TCP/IP 栈stack 计划在 1.17.0 移除

以上版本边界来自官方 Deprecated Feature List。迁移时不要把“计划移除”写成“已经移除”，也不要只按文章发布日期判断当前行为。

高频 TUN 报错：旧地址字段如何对照替换

如果日志指向 inet4_address、inet6_address、inet4_route_address 或 inet6_route_exclude_address，可以将旧字段对照迁移到合并后的数组字段。下面只是对照替换片段，不是可独立运行的完整配置；仍需放回原来的 inbounds 数组，并保留你实际需要的其他字段。

旧字段新字段
inet4_address、inet6_addressaddress
inet4_route_address、inet6_route_addressroute_address
inet4_route_exclude_address、inet6_route_exclude_addressroute_exclude_address

官方迁移页给出的新结构使用 address、route_address 和 route_exclude_address 数组；迁移前后应先备份，再只修改这一组字段，随后执行 check。参见 sing-box Migration。

{
  "inbounds": [
    {
      "type": "tun",
      "address": ["172.19.0.1/30", "fdfe:dcba:9876::1/126"],
      "route_address": ["0.0.0.0/1", "128.0.0.0/1", "::/1", "8000::/1"],
      "route_exclude_address": ["192.168.0.0/16", "fc00::/7"]
    }
  ]
}

这是官方迁移结构的最小对照示例，不代表所有平台都能直接启用。TUN 还可能涉及系统权限、自动路由、DNS 劫持和客户端封装；如果 check 通过但启动后断网，应回到运行日志和平台权限层排查。

出站、路由和订阅错误：不要只删一行解决

出现 outbound not found 时，先查 route 规则中的目标值、route.final、DNS 相关引用是否对应某个出站 tag。如果出现 parse outbound: missing tags，检查每个出站是否有非空 tag，再检查 selector 或 urltest 的候选列表；若列表由正则或订阅过滤生成，还要确认过滤条件实际匹配到了节点。此处只能给出确认方法，不能把所有 missing tags 都归因于某一种出站。

如果错误发生在导入订阅阶段，先区分“下载失败”和“格式不匹配”：下载失败应检查链接响应、登录状态和网络；格式不匹配则检查返回内容是否为 sing-box 支持的 JSON 配置。网页能打开不等于返回内容就是配置文件，浏览器拿到的登录页、错误页或 HTML 页面都可能导致第一行解析失败。

安全回滚与验收：用最少变量确认修复有效

  1. 回滚：保留原配置和备份，不要边改边覆盖唯一文件。
  2. 语法验收：check 不再报告 JSON 解析错误。
  3. 字段验收：unknown field 消失，且没有用删除父级对象的方式掩盖错误。
  4. 启动验收：实例能启动，日志不再出现 fatal；如果客户端显示运行中，仍要检查实际日志。
  5. 连接验收：先验证一个明确的出站，再逐步恢复 TUN、规则集和 DNS，不要同时替换核心、订阅和系统网络设置。

如果格式化命令确实需要使用，先复制备份，再根据当前版本帮助执行；官方配置文档中的 format -w 会写回配置文件。若修改后问题扩大，直接恢复备份并重新记录完整 FATAL 日志，通常比继续叠加改动更容易定位。

常见问题 FAQ

sing-box 配置报错，第一步是不是重新下载配置？

不是。第一步应保存备份、确认实际内核版本和配置路径，再执行 check。重新下载可能把原本的 JSON 语法问题、版本字段问题或订阅格式问题混在一起。

为什么把订阅文件改成 .json 仍然提示 row 1, column 1？

扩展名不会改变文件内容。原文件可能是 YAML、Base64、节点列表、登录页或错误页；应先查看文件开头和实际响应格式，再使用明确支持 sing-box 的配置来源或转换流程。

unknown field 是不是直接删掉字段就可以？

不建议直接删除。先确认字段属于拼写错误、层级错误、已废弃字段还是当前构建不包含的功能，再对照官方 Deprecated 和 Migration 页面进行替换或移除，并在每次修改后重新 check。

sing-box 1.15.0 报 TUN 的 stack 错误怎么办？

官方 Deprecated 页面显示，TUN stack 在 1.15.0 进入废弃范围，计划在 1.17.0 移除；官方迁移示例建议移除该选项以使用新的实现。实际修改前仍需确认客户端是否自行生成该字段，并先备份配置。

check 通过后为什么仍然打不开网页？

check 主要验证配置读取和结构，不能证明节点、DNS、TUN 权限或上游网络一定可用。此时按出站连接、DNS、路由 final、系统权限和网络环境分层排查，一次只改一个变量。

参考资料与站点说明

本文仅根据 sing-box 官方配置、迁移、废弃功能列表和官方仓库发布页整理。sing-box 的版本行为可能随实际内核、构建标签和客户端封装变化，请以当前官方文档、本机 --help 输出及完整日志为准。

WUXX 是第三方使用指南站，不是 sing-box 官方站点，也不冒充官方。关于客户端安装包、内核版本和配置字段，请优先核验发布来源。

常见问题

sing-box 配置报错时最先执行什么？

先备份配置并确认实际内核版本，然后执行 sing-box check；如果参数不兼容，先用 sing-box --help 和 sing-box check --help 查看当前发行版支持的写法。

为什么订阅改成 JSON 扩展名后仍然解析失败？

扩展名不会改变内容。订阅可能是 Clash YAML、Base64、节点列表或 HTML 错误页，需要确认实际返回格式并使用支持 sing-box 的配置。

unknown field 能不能直接删除？

不要直接删除。先确认字段是拼写错误、层级错误、已废弃字段还是构建差异，再按官方迁移文档替换或移除。

check 通过后仍然无法连接怎么办？

check 只说明配置读取和结构校验通过，仍需按出站、DNS、路由、TUN 权限和系统网络逐层排查，一次只修改一个变量。

相关阅读

参考资料

  1. sing-box 官方配置文档
  2. sing-box 官方 Deprecated Feature List
  3. sing-box 官方 Migration 文档
  4. sing-box 官方 JSON Schema 文档
  5. SagerNet/sing-box 官方 Releases