sing-box 配置文件格式怎么选：JSON、YAML、Base64 与订阅导入
简答：先记住结论：sing-box 原生配置文件选 JSON。远程订阅链接不等于 JSON 文件，Clash YAML 或 Base64 文本也不能直接当作 sing-box JSON 使用；先识别内容，再决定直接导入、转换或向提供方索取原生配置。
定义：sing-box 配置文件是描述 DNS、入站、出站、路由等运行参数的 JSON 文档，而远程订阅、Clash YAML、Base64 文本和节点分享链接属于不同层次的输入对象。
先看这一张表：你手里的内容该怎么选
官方文档明确写明，sing-box 使用 JSON 作为配置文件格式，配置通常由 dns、inbounds、outbounds、route 等顶层部分组成。查看官方配置说明
| 你拿到的内容 | 它通常是什么 | 在 sing-box 中怎么处理 | 直接改后缀是否可行 |
|---|---|---|---|
| 本地文件，能看到花括号和双引号 | JSON 配置 | 先备份，再用当前核心版本检查 | 可以作为候选配置，但仍需校验 |
网页返回一长段带缩进的键值内容，常见 proxies、proxy-groups | 常见于 Clash YAML | 使用兼容的本地转换方式，或向提供方索取 sing-box 原生配置 | 不可以，仅改成 .json 不会转换结构 |
| 一整行由字母、数字和符号组成的编码文本 | 可能是编码后的节点或订阅内容 | 先在本地还原，再判断还原后的内容是 JSON、YAML 还是节点列表 | 不可以，改后缀不会解码 |
| 单个分享链接或单个协议链接 | 节点分享链接 | 在客户端使用“添加节点”或由客户端生成配置 | 不可以直接当完整配置文件 |
| 一个 HTTPS 订阅地址 | 远程配置或订阅源 | 在支持远程配置的客户端中作为 URL 导入，或下载后再识别内容 | 不能仅凭 URL 判断格式 |
判断重点：文件扩展名不可靠，真正要看响应内容和第一层结构。sing-box 图形客户端把本地配置和远程配置分开管理；远程配置是以 URL 为更新来源的配置档案，不代表 URL 返回的内容天然就是可直接运行的 sing-box JSON。查看官方配置档案说明
按三步选择格式：先识别，再匹配，最后校验
- 先确认你要导入的对象。如果是完整配置文件，目标应是 sing-box JSON；如果是远程订阅地址，先记录 URL，不要急着复制内容；如果是单个节点链接，则应按节点导入流程处理。不要把“订阅地址”“配置文件”和“节点分享链接”混称为同一种格式。
- 再查看实际内容。用文本编辑器打开下载文件，确认它是否是可读 JSON。JSON 常见特征是以
{开始、使用双引号包围字段名；若看到 YAML 风格的缩进、短横线列表或 Clash 专用字段，就不能只改扩展名。若打开后只有一行编码字符，先在本地还原，避免把真实订阅内容提交给不明在线转换站。 - 最后匹配核心版本。记录客户端显示的 sing-box 核心版本，再检查配置中使用的字段是否在该版本的官方文档或生成的 Schema 中存在。官方 Schema 文档说明，可以用当前安装的二进制生成匹配本机的 Schema：
sing-box schema -o schema.json。查看官方 JSON Schema 说明
如果你只是需要一个能运行的基础配置，优先顺序建议是：提供方直接给出的 sing-box 原生 JSON，其次是本地转换并人工复核，最后才考虑第三方在线转换。转换过程中可能出现节点字段、认证参数、路由规则或 DNS 设置无法一一对应的情况，因此“转换成功”不等于“功能完整”。
下面的内容只能作为结构识别示意，不能直接复制运行：
{ "$schema": "https://sing-box.sagernet.org/schema.json", "dns": {}, "inbounds": [], "outbounds": [], "route": {} }
字段具体含义和可用范围应以当前核心版本的官方配置参考为准，不要把缺少节点、DNS 和路由细节的骨架当作完整配置。
只有 Clash YAML 或编码订阅时，怎么处理更稳妥
情况一：只有 Clash YAML
Clash YAML 与 sing-box JSON 的字段组织方式不同。即使两者都描述代理节点和路由，也不能通过重命名文件或修改扩展名完成转换。优先向订阅提供方索取 sing-box 原生订阅；如果没有，再使用本地转换工具，并在转换前保存原始文件。
转换后至少检查四项：节点数量是否大致一致、协议和认证参数是否仍存在、路由规则是否保留、DNS 与 TUN 相关字段是否符合当前核心版本。任何一项出现明显缺失，都应回到原始订阅核对，而不是继续反复修改。
情况二：只有一行编码文本
一行编码文本只能说明内容被编码或压缩过，不能直接说明它最终属于哪种配置格式。先在本地还原为文本，再根据还原结果判断：如果是 JSON，就按 sing-box 配置校验；如果是 YAML，就按转换流程处理；如果是多个节点链接，则需要客户端或转换器重新生成配置。
情况三：只有远程订阅 URL
不要只看 URL 的后缀判断格式。先确认客户端是否支持远程 sing-box 配置档案；官方图形客户端文档将 Remote Profile 定义为以 URL 为更新来源的远程配置，并说明客户端需要实现自动更新。查看 Remote Profile 说明如果导入后报格式错误，可在浏览器或命令行中查看响应头和正文，但不要公开包含个人令牌的完整地址。
导入后如何验证：check、format 与运行前复测
- 备份。复制原始 JSON、转换前文件和当前正在使用的配置，分别保存，不要直接覆盖唯一副本。
- 检查语法与字段。在配置文件所在目录运行
sing-box check，或按当前版本命令帮助指定配置路径。官方配置页将check列为配置检查命令。查看官方命令说明 - 统一格式。确认内容无误后，再使用官方文档列出的
sing-box format -w -c config.json -D config_directory进行格式化。格式化前最好保留未修改副本，因为它会改变文件排版。 - 小范围运行。先在不影响日常网络的环境中启动，观察日志是否出现未知字段、出站初始化失败、DNS 初始化失败或路由加载失败。不要仅凭客户端界面显示“已连接”就判断所有节点和规则都正常。
- 按现象分流。若提示 JSON 解析错误，检查逗号、引号和括号；若提示未知字段，核对核心版本与官方文档；若配置能启动但无法连接，继续检查节点认证、DNS、路由和 TUN 设置，而不是重新改文件格式。
- 回滚。转换失败或启动异常时，停止当前配置，恢复备份文件，再逐项替换字段。不要把多个版本的配置片段直接拼接在一起。
截至 2026-11-02，官方文档还提供了 JSON Schema 机制；如果编辑器支持 Schema，可以用它提示字段和基础结构问题，但 Schema 校验不能代替真实节点连通性、DNS 和路由复测。查看官方 Schema 文档
格式选择的快速结论
- 只想运行 sing-box：选择或索取原生 JSON。
- 拿到远程 URL：先当作远程配置来源，不要凭链接后缀猜格式。
- 拿到 Clash YAML：不能直接改扩展名，优先原生订阅，其次本地转换。
- 拿到 Base64 或其他编码文本：先本地还原，再判断实际内容。
- 拿到单个节点链接：它不是完整配置文件，需要按节点导入或生成配置。
- 任何格式转换后：都要备份、检查、匹配核心版本，再做连接复测。
本文为第三方使用指南，本站不代表 sing-box 项目或任何订阅提供方；具体客户端功能、订阅格式和字段兼容性，以对应项目及服务提供方的当前说明为准。
常见问题
sing-box 配置文件必须是 JSON 吗？
作为 sing-box 原生配置文件，官方文档明确使用 JSON。远程订阅地址、Clash YAML、编码文本和节点分享链接可以作为输入来源，但它们不等于已经符合 sing-box 配置结构的 JSON。
把 Clash YAML 改成 .json 后能导入 sing-box 吗？
不能。修改扩展名不会改变字段结构，YAML 仍然是 YAML。需要获取 sing-box 原生 JSON，或使用本地转换后检查节点、认证、路由和 DNS 是否完整。
Base64 订阅能直接放进 sing-box 吗？
通常不能直接放进本地 JSON 配置。应先在本地还原编码内容，再判断还原结果是 JSON、YAML 还是节点列表；不要把包含个人令牌的订阅地址提交给不明在线转换服务。
远程订阅链接和 JSON 配置文件有什么区别？
远程订阅链接是一个更新来源，客户端需要请求它并读取返回内容；JSON 配置文件是具体配置内容。一个 URL 不能仅凭地址判断返回的是 sing-box JSON、YAML、编码文本还是其他格式。
为什么 check 通过了，sing-box 仍然连不上？
check 主要用于发现配置结构或字段问题，不能证明节点认证、DNS、路由、TUN 或网络链路可用。启动后还要查看日志，并按节点、DNS、路由和 TUN 分项复测。