sing-box入门：原生JSON配置、图形客户端与版本迁移
sing-box是一套代理平台与核心实现，不只是一款有固定按钮的桌面软件。先确认你使用的是核心程序、官方图形客户端还是第三方封装，再选择对应安装和配置文档。
内容与来源核对： · 机场巡查博客编辑整理
先选运行形式，再看操作系统
官方文档分别提供包管理器安装，以及Android、Apple平台和桌面图形客户端入口。Linux服务器上的核心服务与手机上的图形客户端，权限、生命周期和配置来源都不同。应沿SagerNet项目文档进入对应渠道，不在同名下载站拼装内核和界面。
支持能力由具体版本与构建决定；VLESS、Trojan、Shadowsocks、Hysteria2、TUIC等应在当前出站配置文档中逐项核对。这里不承诺所有封装项目与官方核心同步支持全部功能。
原生配置是JSON：从四个结构读懂路径
inbounds描述流量如何进入，outbounds描述可用出口，route决定如何选择，dns则处理解析相关行为。一个出站对象不是一份完整应用配置，单节点分享链接也不必然能直接作为原生JSON文件。
| 结构 | 负责的问题 | 常见混淆 |
|---|---|---|
| inbounds | 本地流量从哪里接入 | 有远端节点却没有可用接入方式 |
| outbounds | 通过哪个出口发送 | 定义出口不等于规则已经选中它 |
| route | 连接匹配什么策略 | 沿用其他内核字段而解析失败 |
| dns | 域名怎样解析 | 把域名成功解析当作连接成功 |
安装与首次配置，先做检查再接管网络
核心程序按官方包管理器文档安装；图形客户端按其平台文档安装并导入兼容的本地或远程配置。不要把Clash YAML直接改后缀成JSON，也不要把管理后台HTML当作配置文件。
核心用户可在自己文件所在位置执行配置检查。下面命令只表达语法检查，不会证明节点在线，也不是让你对第三方服务器发起测试。
sing-box check -c config.json- 记录核心与图形客户端版本，保留当前可用文件和回退方式。
- 确认配置完整，按所用版本文档检查字段、出站与路由引用。
- 图形客户端选中活动配置并启动，按平台完成系统连接权限；核心用户按自己的入站配置接入测试应用。
- 验证实际请求命中哪个出口，再检查DNS、TLS或远端认证错误。
版本迁移先看Deprecated与Migration
配置语法与某些功能会随版本演进。复制老教程可能出现已弃用字段，也可能在新版仍能解析但行为已不同。先查迁移说明，再逐段调整，不能因为一个报错就把整份DNS或路由配置替换成陌生模板。
远程配置更新由所用客户端或管理方式决定，原生核心不会自动理解每一种机场订阅。需要转换时，应优先使用服务方明确支持的格式，并留意转换过程是否丢失路由与凭证保护。
引用关系与配置检查：语法正确仍可能选错出口
原生配置中的出口标签与路由引用应对应；复制某一段配置时，可能遗漏它依赖的其他对象。即使结构检查通过，最终规则仍可能把请求送到直连、拒绝或另一个可用出口。需要结合运行日志确认，不能把check成功等同功能验收。
迁移时把改动拆成版本支持、结构引用和实际行为三项：先解决已弃用字段，再确认对象关系，最后用一项真实请求验证。涉及服务器参数时，向配置提供方核实，别在不了解语义时随意删除认证、安全或路由字段。
- 备份当前文件并记录可用版本，不直接修改唯一副本。
- 每次迁移只处理文档明确的一类变化，保留检查结果。
- 启动后查看一条实际连接的接入与出口，必要时回退到完整匹配的版本和配置。
适合需要明确控制配置的人
希望理解连接结构、管理自己的服务与版本的人可以选择原生方案；只想快速导入并连接的人，可比较Hiddify或服务方指定客户端。Mihomo与sing-box有各自配置模型，不能仅凭都支持某协议就认为所有字段互通。
遇到导入后全失败，先保留解析错误和版本信息。协议不兼容、流量未进入内核与服务器不可达，是三类不同问题，应分开诊断。
无服务器的结构检查示例：只能验证格式与引用
下面是用于说明JSON层级的直连结构片段，非代理节点配置，不含可用的远端服务器，也不保证适用于未来所有版本。它不会创建本地代理监听；只有查看所用版本文档并补全自己的接入、路由和DNS设计后，才能用于实际需求。
{"log":{"level":"info"},"outbounds":[{"type":"direct","tag":"direct-out"}],"route":{"final":"direct-out"}}- 将示例保存在自己的测试目录，先用所安装版本的check功能检查。
- 核对当前版本是否支持这些字段和direct出站；失败时按迁移文档定位，不直接删除安全字段。
- 注意该结构没有inbounds，也没有节点；检查通过不能证明任何网络接管或代理连接。
从“语法通过”走到“行为一致”的迁移验收
sing-box迁移说明记录过DNS服务器结构、路由动作等变化。应按旧版到目标版的跨度逐项检查，不能只修改报错的一行就假定原有DNS和规则行为完全一致。图形客户端也可能自带不同版本的核心。
迁移前记录一条直连任务、一条需要特定出口的任务以及一个应被拒绝的自定义测试目标（如你确有此规则），迁移后只验证自己有权访问的目标。分别核对命中规则和错误，不通过访问未知测试站泄露配置。
常见问题
sing-box等于Hiddify吗？
不是。Hiddify是独立客户端项目；核心能力、配置转换和界面操作需要分别核对。
check命令成功，能证明服务器可用吗？
不能。语法和引用检查不等于网络连接、证书、认证与应用可用性验证。
升级前为什么要保存旧配置？
迁移可能改变字段与行为。版本和配置一起保留，才能判断差异并在必要时回退。
技术资料与验证边界
依据公开项目文档、规范或原始研究整理。操作与排查建议是编辑分析，不是节点实测或服务器封锁鉴定；版本、平台分发和实际服务状态仍需复核。未采集订阅或账号，不提供未知安装包。