sing-box 新手入门：核心、客户端、JSON 配置与排障路径

更新于 2026-10-28 · deardeernetworks.buzz

简答：sing-box 是一个以配置文件驱动的通用网络代理平台，核心负责实际运行，图形客户端负责管理配置和系统权限。新手最稳妥的顺序是：确认来源与版本，分清配置格式，备份后导入，完成配置检查，再依次验证启动、节点、DNS、路由和实际应用。很多导入失败并不是节点本身有问题，而是把客户端、核心、订阅链接和 JSON 配置混成了同一种东西。

定义：sing-box 是一个可运行于多种系统、通过配置文件管理入站、出站、DNS 和路由的通用网络代理平台。

30 秒速查：先分清核心、客户端和配置文件

本文是独立的第三方使用指南，不代表 sing-box 项目、配置提供方或任何网络服务的官方页面。刚接触 sing-box 时，最容易混淆的是“核心”“图形客户端”“配置文件”和“订阅链接”。先把这几类对象分开，后面的安装与排障会简单很多。

sing-box 新手对象对照表

对象	它负责什么	导入前要确认什么
sing-box 核心	读取配置并处理实际连接	系统架构、核心版本、配置路径和运行权限
图形客户端	管理本地或远程配置、启动核心、查看日志和申请系统网络权限	当前客户端是否内置核心，是否支持 TUN 或远程配置
本地 JSON	设备上保存的 sing-box 配置文件	是否为 sing-box JSON，而不是其他客户端格式
远程配置	通过 URL 获取的配置内容	链接是否可访问、是否需要认证、返回内容是否为可识别格式
订阅链接	由服务或工具提供的一组节点或配置入口	当前客户端能否识别，是否需要转换或补全
单节点分享链接	描述一个节点的分享信息	通常不能直接等同于完整配置，具体以客户端支持为准

sing-box 的配置文档以 JSON 配置结构为基础，配置通常会涉及 DNS、入站、出站和路由等部分。Clash YAML、单节点链接、远程订阅和完整 sing-box JSON 并不是同一种格式，不能因为文件能打开或链接能复制，就判断它已经可以运行。可先查看sing-box 配置文档。

版本怎么选：首次使用优先稳定版

版本会持续变化。以2026年10月28日检索到的项目页面当前显示值为准，官方容器版本页显示稳定标签为 1.14.4，测试标签为 1.15.0-alpha.13；这只是本次核验时页面显示的状态，后续应重新查看官方版本页和官方 Releases 页面。

稳定版与测试版选择建议

使用场景	建议	操作重点
第一次安装	优先稳定版	减少字段变化和客户端行为变化带来的排查成本
日常办公或长期运行	继续使用已验证的稳定版本	备份配置并记录核心、客户端和系统版本
测试新功能或复现特定问题	单独目录尝试测试版	不要覆盖正在使用的核心和配置
升级后无法启动	先查看日志，再考虑回退	不要同时修改版本、DNS、路由和节点参数

“能下载”不等于“与现有配置兼容”。升级前至少保存原配置、记录当前版本，并保留回退文件。特别是包含 TUN、DNS、路由或实验性字段的配置，应按当前版本文档逐项核对。不要把旧教程中的字段直接复制到新版本。

按平台选择安装路径

不同平台的 sing-box 使用方式并不完全相同。命令行核心适合希望自行管理进程、配置路径和日志的用户；图形客户端则把配置切换、系统权限和 TUN 接管集中到界面中。若你只是第一次使用，优先选择当前系统对应的图形客户端，并确认它实际使用的核心版本。

Windows 或 Linux：可先查看sing-box Desktop 文档。该页面当前列出 Windows 10 及以上版本，以及 Linux 的 x64、arm64 和 armv7l 要求。下载前核对系统架构，不要把其他架构的文件强行运行。
Android：查看Android 客户端文档。页面当前列出 Android 5.0 及以上要求，并提供应用商店、GitHub Releases 和 F-Droid 等入口。安装后仍需按客户端界面导入配置并申请 VPN 权限。
iOS、macOS 或 Apple TV：查看Apple 平台文档。页面当前列出 iOS 15.0、macOS 13.0 和 Apple tvOS 17.0 及以上要求；macOS 另有独立版本入口。具体可用版本和商店状态应以页面当前显示为准。
命令行核心：需要自行管理进程时，再查看安装与包管理器文档。安装完成后先确认核心可以运行，再导入复杂配置。

安装前建议记录系统版本、CPU 架构、客户端版本和核心版本。涉及 TUN、虚拟网卡、网络扩展或系统 VPN 权限时，按系统提示授权；如果权限失败，先保存日志，不要立刻反复改配置。

配置导入：先判断格式，再检查和启动

导入前不要直接覆盖唯一配置。先复制一份原文件，并在文件名或备注中记录来源、获取时间和对应核心版本。然后按下面顺序处理：

识别内容：确认手上是完整 sing-box JSON、远程 JSON、订阅链接、Clash YAML，还是单节点分享链接。
选择导入方式：完整 JSON 通常可以作为本地配置使用；远程配置需要客户端能够访问 URL；订阅或单节点链接是否能直接导入，取决于当前客户端的解析能力，必要时可能需要转换或补全。
备份后导入：在客户端中选择本地文件或远程配置入口。若当前版本没有旧教程中的菜单名称，应以当前界面为准，不要照搬旧路径。
执行配置检查：命令行环境可使用当前版本支持的配置检查命令。官方配置文档提供了配置结构和命令入口，具体参数以当前版本帮助信息为准。
启动并观察日志：先判断核心是否启动，再查看 DNS 初始化、路由加载、出站连接和 TUN 创建是否报错。

配置检查通过，只能说明当前核心能够解析配置结构或字段，不能证明节点可用、远端认证成功、DNS 正常或所有应用都会经过代理。完整验证应拆成多个层次：核心启动、节点连接、DNS 解析、路由命中、目标应用访问。

如果你使用的是配置模板或转换工具，模板中的占位节点不能直接连接，凭据也不要粘贴到不明网页。无法确认字段是否适配当前核心时，应降低判断为“需要按当前版本核验”，而不是把配置骨架当成可运行成品。

TUN、mixed、FakeIP、RealIP、Selector 和 URLTest 怎么理解

TUN 是虚拟网络接口，适合接管不支持手动填写 HTTP 或 SOCKS 代理的应用，但会涉及系统路由、虚拟网卡、DNS 和权限。官方 TUN 文档还标注了不同版本的字段变化，因此旧配置中的 stack、auto_route、auto_redirect、DNS 劫持或路由字段，不能脱离当前版本直接复制。

mixed 通常用于同时提供 HTTP 和 SOCKS 接入，适合先让单个应用通过代理设置进行验证。它不等于 TUN，也不会自动接管所有系统流量。FakeIP 与 RealIP 涉及 DNS 和地址处理方式，实际行为取决于配置、核心和客户端支持；不能只凭名称判断哪一种一定更快。

Selector 用于手动选择出站，URLTest 用于根据测试结果选择出站。测试结果只代表特定时间、目标和网络条件，不能作为长期稳定性或所有网站可用性的证明。相关字段应以当前 TUN 配置文档和客户端界面为准。

连接失败时按“启动—节点—DNS—路由—应用”分层排查

核心是否启动：如果程序立即退出，先检查 JSON、字段、文件路径、版本和权限。
出站是否完整：检查服务器地址、端口、认证信息以及必要的 TLS 或传输参数。占位符不能作为实际节点使用。
节点是否建立连接：查看日志中的域名解析失败、连接超时、握手失败或认证失败。界面显示“已启动”不代表远端节点已连通。
DNS 是否单独正常：先用简单配置缩小范围，再逐步恢复 DNS 规则。DNS 成功不代表节点、路由和目标应用都正常。
路由是否命中：确认流量进入的是 TUN、mixed 还是直连，并检查是否被直连规则、私有地址规则或系统代理绕过。
处理 TUN 冲突：暂时关闭其他 VPN、虚拟网卡或重复的网络接管工具，再重启客户端进行对照测试。
验证实际应用：分别测试浏览器、终端或办公软件。一个应用可以访问，不代表其他应用使用了相同的代理路径。

如果 TUN 无法启动，可以先关闭 TUN，仅使用 mixed 或系统代理验证核心与节点。验证完成后恢复原设置，并记录临时修改的范围；不要把临时直连状态当成最终配置。若仍然失败，可继续查看sing-box TUN 模式无法启动时的排查指南。

启动即退出：优先查配置结构、版本字段和权限。
启动成功但无网络：优先查出站、认证、DNS 和路由。
浏览器可用但办公软件不可用：优先查应用是否支持系统代理，必要时再检查 TUN。
升级后出现字段错误：保留旧版本和原配置，按迁移说明逐项核对，不要一次改多个部分。

新手完成一次可复现安装的检查清单

下载入口来自项目文档或项目发布页面，并已核对平台和系统架构。
已记录核心版本、图形客户端版本、操作系统版本和配置来源。
已区分完整 JSON、远程配置、订阅链接、Clash YAML 和单节点分享链接。
已备份原配置，没有覆盖唯一副本。
已完成当前版本支持的配置检查，并保存错误日志。
已分别验证核心启动、节点连接、DNS、路由和实际应用。
启用 TUN 前已准备关闭其他 VPN 或虚拟网卡进行对照测试。
每次只修改一个变量，并保留修改前后的配置和日志。

本文只作为 sing-box 总览入口，具体平台安装、配置转换和 TUN 故障适合拆成独立页面阅读。版本、菜单、权限和字段会随项目更新，以当前项目文档和客户端界面为准。

常见问题

sing-box 是软件、协议还是订阅格式？

sing-box 是一个通用网络代理平台和核心程序，不是单一协议，也不是一种订阅格式。它使用配置文件组织 DNS、入站、出站和路由，具体支持的协议与字段应以当前项目文档为准。

sing-box 核心和图形客户端有什么区别？

核心负责读取配置并处理连接，图形客户端负责配置管理、启动控制、日志查看以及系统网络权限申请。有些客户端内置核心，有些需要单独管理，不能只凭应用名称判断两者关系。

Clash YAML 可以直接导入 sing-box 吗？

通常不能把 Clash YAML 直接当作 sing-box JSON 使用。两者结构不同，是否能通过当前客户端转换或导入，要看客户端支持。转换成功也不等于节点、DNS 和路由一定可用，导入后仍需检查和分层验证。

为什么配置检查通过，启动后仍然无法联网？

配置检查主要验证结构和字段能否被当前核心解析，不能证明远端节点、认证、DNS、路由或目标应用都正常。应查看日志，再按节点、DNS、路由和实际应用顺序排查。

新手应该先用 TUN 还是 mixed？

如果只是验证少数支持代理设置的应用，通常可以先用 mixed，范围更容易控制；如果需要处理不使用系统代理的应用，再考虑 TUN。TUN 涉及虚拟网卡、路由和权限，出现冲突时应先保留回退方案。

如何判断下载的是正确版本？

先确认系统平台和 CPU 架构，再从项目文档或发布页面核对版本、文件名和校验信息。稳定版与测试版应分开看，以版本页面当前显示为准，不要把第三方重新打包文件当成项目原始发布物。