sing-box 配置生成报 unknown field？从输入格式到 JSON 导入校验

更新于 2026-10-24 · knotic.store

简答：粘贴订阅后 sing-box 报 unknown field 或无法启动，通常是输入格式、客户端配置与内核版本不匹配。先识别 URI、Base64、Clash YAML 或 JSON，再生成客户端 outbound 配置，用 sing-box check 校验后导入目标平台。

定义：sing-box 配置生成，是把节点链接或服务器参数整理成符合 sing-box JSON 结构的客户端配置，并按目标平台、内核版本和网络模式完成校验与导入。

先试这一步：按输入特征判断该怎么生成

粘贴订阅后 sing-box 报 unknown field、JSON 解析失败或无法启动，先不要继续修改字段。第一步是确认你手里的内容究竟是哪一种输入：单条 URI、Base64 订阅、Clash YAML、节点 JSON，还是服务器端参数。本文是第三方使用指南，重点放在客户端配置生成与导入，不能把服务端配置直接当作客户端配置使用。

输入特征	判断为	正确处理方式
以 `vless://`、`vmess://`、`trojan://`、`ss://` 或 `hysteria2://` 开头	单条节点 URI	提取协议、地址、端口、凭据、TLS、传输层等字段，再生成一个对应的客户端 outbound。
一长串字母、数字和符号，解码后出现多条 URI	Base64 订阅	先在本地解码，确认内容是 URI 列表还是其他格式，再逐条转换；不要把订阅地址本身当作 JSON。
出现 `proxies:`、`proxy-groups:` 或 `rules:`	Clash YAML	转换节点、策略组和规则逻辑；不能直接改文件后缀当成 sing-box JSON。
出现 `outbounds`、`inbounds`、`route` 等顶层键	可能是 sing-box 原生 JSON	先确认字段是否属于当前 sing-box 内核，再执行格式和结构校验。
只有服务器地址、端口、密码、UUID、证书或 Reality 参数	服务器参数	按协议手动填写客户端 outbound；缺少服务端给出的关键参数时，不要猜测字段。

官方配置结构使用 JSON，常见顶层部分包括 log、dns、inbounds、outbounds 和 route。可以查看 sing-box 配置结构与命令，确认生成器输出的层级是否正确。

先分清客户端配置和服务器端配置

“配置生成”可能指两件不同的事：客户端配置用于连接已有服务器，重点是 outbound、DNS、入站监听和路由；服务器端配置用于在服务器上接收连接，重点是 inbound、监听地址、证书、认证和防火墙。本文要生成的是前者。

例如，你有一条 VLESS URI，通常需要把它转换成客户端的 vless outbound，并配合 direct outbound、mixed 入站和 route.final。服务器端的 VLESS inbound 不能直接复制到手机或电脑客户端，否则即使 JSON 语法正确，也可能出现字段位置错误、监听方向相反或协议角色不匹配。

同理，Hysteria2、TUIC、Shadowsocks、Trojan 和 WireGuard 都应按照各自的 outbound 文档填写。协议字段不能跨类型混用；Hysteria2 的客户端参数应以 Hysteria2 outbound 为准，VLESS 则参考 VLESS outbound。

可直接改写的最小客户端 JSON 骨架

下面示例只展示客户端配置的结构，不包含真实节点，也不能直接连接。把尖括号中的占位内容替换成服务端提供的值；如果节点不是 VLESS，应改用对应协议的 outbound 结构。示例使用 mixed 入站，适合先让支持 HTTP 或 SOCKS 代理的应用进行验证。

{
  "log": {
    "level": "info"
  },
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      }
    ]
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": <本地端口>
    }
  ],
  "outbounds": [
    {
      "type": "vless",
      "tag": "proxy",
      "server": "<服务器地址>",
      "server_port": <服务器端口>,
      "uuid": "<UUID>",
      "tls": {
        "enabled": true,
        "server_name": "<SNI>"
      }
    },
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "auto_detect_interface": true,
    "final": "proxy"
  }
}

mixed-in 是本地代理入口，实际端口由你自行设置，不能假定为某个客户端默认值。
proxy 是客户端连接远端节点的出口，必须与 route.final 中的标签完全一致。
direct 用于直连出口；如果路由规则没有引用它，可以先保留，后续再添加分流。
tls.server_name 只应填写服务端提供的 SNI。Reality、ALPN、证书校验和传输层参数要按实际节点补齐，不能用示例值代替。

mixed 入站同时提供 HTTP 和 SOCKS 代理能力，适合生成后的第一轮验证；需要接管系统流量时，再根据平台权限和兼容性考虑 TUN。相关字段可分别查看 Mixed 入站、TUN 入站和 Route 路由。

按平台生成、导入和启动

官方图形客户端列表目前按平台列出 Android、Apple 平台、Windows 和 Linux 对应客户端。Windows 与 Linux 使用 sing-box for Desktop；iOS 与 macOS 属于 sing-box for Apple platforms；Android 使用 sing-box for Android。具体下载渠道和系统要求以 Graphical Clients 及各平台页面为准。

平台	生成后操作	启动前检查
Android	把 JSON 保存到设备，再在客户端的本地配置或配置编辑入口导入；也可以使用客户端支持的远程配置方式。	首次启用 TUN 时允许 VPN 权限；只测试 mixed 时，先让目标应用显式使用本地 HTTP 或 SOCKS 端口。
iOS	将 JSON 通过文件分享、导入或客户端支持的配置方式加入本地配置列表，界面名称以客户端为准。	启动 TUN 前允许系统 VPN 配置；iOS 应用通常不能像桌面浏览器一样单独设置任意本地代理端口。
macOS	在 sing-box for Apple platforms 中打开本地配置或编辑器，导入保存的 JSON 后选择运行。	使用 TUN 时按系统提示放行网络扩展；桌面版与 App Store 版本的能力和配置迁移方式可能不同，应以平台文档为准。
Windows	在 sing-box for Desktop 中打开本地 JSON 配置，保存后运行；也可先用命令行校验。	需要 TUN 或系统级流量接管时，按客户端提示允许服务或管理员权限；只用 mixed 则先验证本地代理端口。
Linux	保存 JSON 后，用 sing-box 命令行加载，或在 sing-box for Desktop 中管理本地配置。	TUN、自动路由和 Linux 防火墙可能需要更高权限；先用 mixed 验证节点，再逐步启用 TUN 和路由规则。

官方客户端页面明确说明这些图形客户端可以管理和运行本地或远程 sing-box 配置，并提供平台相关的 TUN 功能。桌面端的系统要求和发行方式见 sing-box for Desktop，Android 见 sing-box for Android，Apple 平台见 sing-box for Apple platforms。

生成前要选对内核与配置模式

同一份 JSON 不一定适用于所有客户端，因为客户端内置内核、编译特性和支持的字段可能不同。出现 unknown field、启动后立即退出或导入后配置被改写时，优先检查客户端显示的内核版本和配置目标，而不是继续添加字段。

官方 JSON Schema 页面说明，Schema 能用于兼容编辑器的补全和校验，并可通过 sing-box schema -o schema.json 生成与当前已安装二进制及其构建特性匹配的 Schema。该命令自 sing-box 1.14.0 起提供；如果本机命令不存在，应先查看当前二进制的帮助信息和对应文档，不要照抄新版本命令。

可执行的校验流程如下：

把文件保存为 config-<版本号>.json，保留原始节点输入作为备份。
运行 sing-box check -c config-<版本号>.json，先处理 JSON 语法、字段名称和引用关系错误。
如需格式化，运行 sing-box format -w -c config-<版本号>.json；格式化不会自动补齐缺少的 TLS 或认证参数。
如果当前二进制支持 Schema，运行 sing-box schema -o schema.json，在编辑器中引用生成的本地 Schema。
启动后查看连接日志，确认命中了预期的 outbound；再用出口 IP 对比确认流量是否真的经过代理。

配置结构、check、format 和 merge 命令可参考 Introduction - sing-box；Schema 的适用范围和生成命令见 JSON Schema - sing-box。

DNS、FakeIP、RealIP、mixed 和 TUN 怎么选

mixed：适合先验证节点、TLS 和基本路由。应用需要主动使用本地 HTTP 或 SOCKS 代理，不能据此证明所有系统流量都已接管。

TUN：适合需要处理更多不读取系统代理的应用。它会涉及系统路由、VPN 或管理员权限，Windows、macOS、Linux、Android 的实现并不相同。Linux 还可能涉及自动路由和 nftables，首次排错不建议同时加入复杂分流。

FakeIP：是 sing-box DNS 服务器中的一种具体模式，会把域名映射到虚拟地址，便于规则系统按域名处理连接，但局域网服务、IP 直连和部分应用可能需要额外规则。RealIP不是 sing-box 配置中的统一正式字段，而是常见的通用说法，通常指不使用 FakeIP 地址映射、让 DNS 返回实际解析结果的配置思路。选择时应以目标客户端支持的 DNS 服务器和规则为准。

建议按“本地 DNS 或简单 DNS → mixed → 基础路由 → TUN → FakeIP 或复杂分流”的顺序增加变量。出现能打开 IP 但打不开域名时，先看 DNS 日志和 DNS 服务器；出现浏览器正常但其他应用失败时，检查应用是否使用系统代理，或 TUN 是否真正启动。DNS 服务器类型和 FakeIP 页面可查看 DNS Server - sing-box。

常见报错：先看是哪一层出问题

现象	优先检查	处理方法
`unknown field`	内核版本、字段迁移、其他内核模板	用当前二进制生成 Schema，并对照官方配置页；不要把其他内核的字段直接挂到 sing-box 配置中。
JSON 解析失败	逗号、引号、数组和对象层级	用 JSON 编辑器格式化，再运行 `sing-box check`；不要在 JSON 中保留未被支持的注释。
TLS 握手失败	SNI、ALPN、证书校验、Reality 参数和传输层	逐项与节点提供者给出的参数核对；不要为了绕过错误长期启用不安全的证书校验。
Hysteria2 连接超时	服务器端口、密码、TLS、UDP 网络	先核对 Hysteria2 outbound 所需字段，再查看本地网络是否能传输 UDP；配置能通过 JSON 校验不代表服务端参数正确。
配置能启动但应用不上网	mixed 端口、应用代理设置、TUN 权限和路由	先让浏览器显式使用 mixed 端口，再查看日志和出口 IP；需要全局接管时再排查 TUN。
域名解析异常	DNS server、DNS rule、FakeIP 和路由顺序	暂时减少 DNS 规则，先用简单配置确认解析，再逐步恢复分流。

TLS 的通用字段包括启用状态、SNI、ALPN 和证书校验等，具体应参考 TLS - sing-box。如果是旧配置迁移导致的字段错误，可继续查看 Migration - sing-box 和 Deprecated Feature List - sing-box。

生成和导入前后的安全检查

不要把带密码、UUID、私钥、Reality 私密参数或完整订阅地址的 JSON 发到公开页面。
如果使用在线转换页面，先确认页面是否明确说明输入是在浏览器本地处理、是否会上传或保存；无法确认时，优先使用本地编辑器和本机命令。
下载客户端时，从官方客户端页面列出的发行渠道获取，并核对平台、架构和文件名。
配置导入后，检查每个 tag、selector、rule-set 和 outbound 是否已声明；路由引用不存在的标签会导致启动或分流错误。
先用最小配置验证节点，再添加 TUN、DNS 分流、FakeIP、规则集和代理组，避免多个变量同时变化。
通过连接日志命中的策略和出口 IP 对比确认实际路径，不要只用 ping 或 tracert 判断普通系统代理是否生效。

需要线路方案时，了解线路方案，以官网为准。

常见问题

sing-box 配置生成器能不能直接粘贴订阅地址？

不能把订阅地址本身当成 sing-box JSON。先判断它是单条 URI、Base64、Clash YAML 还是其他格式，再转换为客户端配置；是否支持直接导入远程订阅，要以目标客户端的界面和文档为准。

为什么生成的配置出现 unknown field？

常见原因是模板与当前内核版本不一致，或者把其他内核的字段混入 sing-box。先用本机二进制生成 Schema，再对照官方配置页、迁移说明和废弃字段列表修改。

客户端配置和服务器端配置有什么区别？

客户端配置通常使用 outbound 连接远端服务器，并配合 DNS、入站监听和 route；服务器端配置通常使用 inbound 接收连接。两者协议角色和字段位置不同，不能直接互换。

mixed 和 TUN 应该选哪个？

只想先验证节点或让少数应用使用代理，优先用 mixed；需要接管更多系统流量时再考虑 TUN。TUN 需要额外的 VPN、管理员或系统网络权限，平台行为以客户端实现为准。

生成后如何确认配置真的生效？

先运行 <code>sing-box check</code>，再启动客户端查看日志是否命中预期 outbound，最后对比出口 IP。单独查看 ping 或 tracert，不能证明普通 HTTP 或 SOCKS 系统代理已经生效。

Reality 或 TLS 参数应该怎么填写？

必须按节点提供的 SNI、ALPN、Reality 公钥、short_id、证书校验和传输层参数填写。JSON 校验通过只代表结构基本可读，不能代替 TLS 握手和服务端参数核对。