sing-box 怎么用?从配置判断到启动排错的完整教程
简答:sing-box 的用法是先判断配置格式,再按设备选择客户端或核心,导入并启用配置,最后通过日志、命中策略和出口 IP 验证是否生效。Clash YAML 不能默认直接导入。
定义:sing-box 是使用 JSON 配置的网络代理平台,核心程序负责运行配置,图形客户端负责配置管理、平台权限与 TUN 等功能。
先照这张速查卡操作:5 步完成 sing-box 基础使用
下载了核心程序却无法双击打开,或把 Clash YAML 导入后提示格式错误,通常不是节点本身的问题,而是核心、客户端和配置格式没有分清。本站是第三方使用指南站,以下步骤只整理公开文档中的通用操作。
| 步骤 | 要做什么 | 判断标准 |
|---|---|---|
| 1 | 判断手里的配置 | 优先确认是否为完整 sing-box JSON;不要把 Clash YAML 默认当作原生配置。 |
| 2 | 按设备选择客户端 | Windows、Linux 使用 Desktop;Android 使用 Android 客户端;iOS 和 macOS 使用 Apple 平台客户端。 |
| 3 | 导入并选中配置 | 远程 URL 或本地 JSON 导入成功后,还要把它设为当前活动配置。 |
| 4 | 启用代理方式 | 先用客户端提供的系统代理或基础模式测试,再按需启用 TUN。 |
| 5 | 验证真实流量 | 查看连接日志中的命中策略,并对比启用前后的出口 IP,不能只看“运行中”。 |
截至 2026 年 10 月 24 日,GitHub Releases 标记为 Latest 的稳定版本是 1.14.3;1.15.0-alpha.12 属于预发布版本。客户端内置核心可能与独立核心不同,实际以客户端“关于”页和对应配置文档为准,可查看官方 Releases。
核心程序和图形客户端有什么区别?不同设备怎么选
核心程序主要负责读取 JSON 配置并运行入站、出站、路由和 DNS;图形客户端则负责导入配置、切换配置、显示日志,以及调用系统代理、TUN 或 VPN 权限。核心程序不是通常意义上的桌面应用,直接双击后没有图形界面属于正常情况。
| 设备 | 优先选择 | 使用方式 | 权限或兼容提醒 |
|---|---|---|---|
| Windows | sing-box for Desktop | 管理本地或远程配置,按客户端界面启用代理或 TUN。 | 支持 Windows 10 及以上,架构包括 x64、x86 和 arm64。 |
| Linux | sing-box for Desktop 或命令行核心 | 桌面设备可用图形客户端;服务器适合核心加 systemd。 | TUN、路由和监听权限按配置与系统服务权限处理。 |
| Android | sing-box for Android | 导入配置后通过 Android VPN 授权运行。 | 系统弹出 VPN 授权时需要允许;不要同时运行多个 VPN 类应用。 |
| iOS | sing-box for Apple platforms | 导入本地或远程配置,再授权 VPN 配置。 | 不能按 Linux 核心的方式直接双击运行。 |
| macOS | sing-box for Apple platforms | 使用 Apple 平台客户端管理配置并启用对应网络功能。 | 系统版本和客户端分发方式以官方页面为准。 |
官方客户端列表明确将 Windows、Linux 归入 sing-box for Desktop,将 Android、iOS 和 macOS 归入相应平台客户端;下载入口与系统要求可查看官方图形客户端列表、Desktop 文档和Apple 平台文档。
先判断配置格式:JSON、Clash YAML、节点链接和远程订阅
sing-box 原生配置使用 JSON,官方配置结构包括 dns、inbounds、outbounds、route 等部分。配置内容以 { 开始,并能看到 outbounds 或 route,通常更接近 sing-box JSON;出现 proxies: 等 YAML 结构时,不要默认可以直接导入。
- 完整 sing-box JSON:适合直接导入,但仍需确认客户端或核心支持其中的字段。
- Clash YAML:不是 sing-box 原生 JSON。官方配置文档没有把 Clash YAML 列为原生配置格式;如果客户端没有明确的兼容导入功能,就不能直接使用。
- 单节点分享链接:通常只描述一个出站节点,不一定包含 DNS、路由、入口或 TUN 设置。
- 远程订阅 URL:客户端会从 URL 下载配置,更新时可能改变本地配置内容,应先保存副本。
- 本地 JSON:适合测试和排错,建议保存为
config.json,不要公开分享带有授权信息的文件或链接。
配置检查可在安装核心的设备上执行:
sing-box check -c config.json
sing-box format -w -c config.json
sing-box run -c config.json第一条用于检查配置,第二条按官方格式化命令写回文件,第三条以前台方式运行。官方配置文档列出了检查、格式化和合并命令,详见sing-box 配置介绍。
导入配置、启动代理并验证是否真的生效
- 安装客户端或核心:根据设备和架构选择官方发布资产;Linux 服务器优先使用官方包管理方式。
- 添加配置:在客户端的配置、Profiles 或订阅页面粘贴远程 URL,或选择本地
config.json。 - 确认配置内容:导入后检查配置名称、出站节点、DNS、路由和 TUN 选项是否符合预期。
- 设为活动配置:导入成功不等于已经运行,需要在配置列表中选中它。
- 先做低风险测试:优先启用客户端提供的系统代理或基础代理模式,确认浏览器和日志正常后,再测试 TUN。
- 验证实际流量:打开连接日志,确认目标域名出现并命中了预期出站策略;再对比启用前后的出口 IP。
系统代理、规则模式、全局模式和直连模式不是所有客户端都统一提供的原生开关,它们可能来自具体图形客户端、配置内容或 Clash API 兼容层。官方客户端中找不到“全局模式”并不代表安装失败,应以当前客户端的界面和配置文档为准。TUN 则是通过虚拟接口接收更多系统流量的方式,涉及系统权限、路由和 DNS,不能仅凭开关显示为开启判断成功。
| 现象 | 优先验证 | 下一步 |
|---|---|---|
| 浏览器能访问 | 日志是否出现目标域名和预期出站 | 再测试其他应用,不要把浏览器结果当成全系统结果。 |
| 客户端显示运行但应用直连 | 应用是否读取系统代理,规则是否命中直连 | 检查日志;必要时在确认权限后测试 TUN。 |
| TUN 开启后无法联网 | VPN、系统扩展、路由和 DNS | 先关闭 TUN 恢复测试,再逐项检查授权与路由。 |
客户端代理模式与 TUN 的适用边界可参考官方客户端代理模式说明。
配置字段怎么理解:inbounds、outbounds、route 和 dns
新手不需要一次掌握全部 JSON 字段,可以先记住四个区域:
- inbounds:定义 sing-box 接收本机流量的入口,例如 TUN、HTTP 或 SOCKS。
- outbounds:定义流量离开本机的方式,例如直连、阻断、节点协议或选择器。
- route:根据域名、IP、入口或其他规则决定使用哪个出站,也可以设置默认出站。
- dns:定义 DNS 服务器、DNS 规则、默认 DNS 和缓存等行为。
不要把其他内核或其他客户端的字段直接复制到 sing-box。结构和字段应以官方配置文档为准,路由查看Route 文档,DNS 查看DNS 文档。如果配置提示 unknown field、deprecated 或启动即退出,先执行 sing-box version 查看核心版本,再到客户端“关于”页查看内置核心版本,并对照官方 Change Log和官方 Migration。
例如旧配置使用 DNS 服务器的 address 写法时,可能需要按照迁移文档改为新的 type、server 结构;不要只修改一个字段后反复重启,应先备份配置,再用 check 验证。
按故障阶段排查:导入、启动、运行后分别看什么
导入阶段:格式错误或导入无反应
- 确认拿到的是完整 sing-box JSON,而不是 Clash YAML、HTML 错误页或单节点链接。
- 用文本编辑器检查是否存在完整的 JSON 括号、逗号和字段名。
- 远程配置无法下载时,先确认 URL 在当前网络中可访问,再保存为本地文件排查。
启动阶段:解析失败、立即退出或端口冲突
- 先执行
sing-box check -c config.json,优先处理第一条错误。 - 用
sing-box version和客户端“关于”页确认核心版本,再检查字段是否属于对应版本。 - sing-box 核心没有固定的本地 HTTP 或 SOCKS 默认端口,端口由
inbounds中的listen_port决定;以配置或客户端设置页为准。
确认具体端口后,将 <端口> 替换为实际数字。Windows 可执行:
netstat -ano | findstr :<端口>Linux 可执行:
sudo ss -lntup | grep :<端口>macOS 使用:
lsof -nP -iTCP:<端口> -sTCP:LISTEN运行后:无法联网、DNS 异常或速度慢
- 先关闭 TUN,分别测试直连和系统代理,确认问题是否由路由或权限引起。
- 查看连接日志是否出现目标域名,以及实际命中了直连、节点还是阻断策略。
- 域名打不开但 IP 可访问时,检查 DNS 服务器、DNS 规则和 TUN 的 DNS 接管方式。
- 速度慢时不要只看延迟;一次只更换一个节点、DNS 或 MTU 参数,记录丢包、连接稳定性和实际吞吐变化。
如果是 TUN 路由问题,可对照官方 Tun 文档检查自动路由、接口探测和出站绑定设置。Windows、Android、iOS、macOS 的授权入口由各自客户端和系统提供;Linux 则重点检查 TUN 设备、路由表和运行服务的用户权限。
Linux 核心:安装、前台检查和 systemd 自启动
Linux 服务器可以使用官方包管理方式安装,也可以使用官方安装脚本。Debian/Ubuntu 类系统可按官方文档添加仓库后安装;需要其他发行版时,先查看官方 Package Manager 文档,不要把不明来源的二进制直接放入系统目录。
安装后先确认核心可用:
sing-box version
sudo install -d -m 0755 /etc/sing-box
sudo cp config.json /etc/sing-box/config.json
sudo sing-box check -c /etc/sing-box/config.json
sudo sing-box run -c /etc/sing-box/config.json前台运行没有配置错误后,再使用系统服务。官方包通常会提供 sing-box 服务,可执行:
sudo systemctl enable sing-box
sudo systemctl start sing-box
sudo systemctl status sing-box
sudo journalctl -u sing-box -f如果服务启动失败,先查看 status 和 journalctl 的第一条错误;重点检查配置文件路径、专用用户是否有读取权限、监听端口是否被占用,以及 TUN 和自动路由所需的系统权限。Linux 不一定必须使用 root,但 TUN、路由和特定监听设置可能需要额外权限,具体以配置和服务文件为准。
远程订阅和在线转换:导入前先保护配置凭据
远程订阅 URL 可能包含授权访问所需的随机字符串,应按凭据处理。不要把完整 URL 放入公开聊天、截图、工单或不明在线转换服务。
- 导入前保存一份本地副本,便于比较更新前后的出站、DNS、路由和 TUN 变化。
- 远程配置更新后重新查看配置名称、节点列表、规则和 DNS,不要默认更新只增加节点。
- 只有在确认服务信任关系和数据处理方式后,才考虑把订阅内容交给在线转换工具。
- 遇到无法联网时,先用最小本地配置或已知可用的单节点验证核心,再逐步加入 DNS、路由和 TUN。
- 配置能启动但流量异常时,优先看日志命中策略和出口 IP,不要只重新下载订阅。
常见问题
sing-box 可以直接导入 Clash YAML 吗?
不能默认直接导入。sing-box 原生配置使用 JSON;如果当前客户端没有明确提供 Clash YAML 兼容导入,就应获取 sing-box JSON 或使用配置提供方支持的格式。
为什么 sing-box 显示运行,但某个应用仍然直连?
先查看连接日志是否出现该应用或目标域名,再检查是否命中直连规则、应用是否读取系统代理,以及 TUN 是否获得授权。
开启 TUN 后无法联网怎么办?
先关闭 TUN,确认直连和基础代理正常,再检查系统 VPN 或网络扩展授权、其他 VPN 冲突、路由和 DNS;Linux 还要检查 TUN 设备与服务权限。
Linux 上必须使用 root 运行 sing-box 吗?
不一定。普通代理监听可以使用专用用户,但 TUN、自动路由和部分系统服务配置可能需要额外网络权限,应结合服务文件和日志判断。
配置提示 unknown field 或 deprecated 怎么处理?
先用 <code>sing-box version</code> 查看核心版本,再查看客户端内置核心版本,对照官方 Change Log 和 Migration 文档迁移字段,最后用 <code>sing-box check</code> 验证。
为什么延迟低但实际速度仍然慢?
延迟不能单独代表吞吐量,还应检查丢包、拥塞、MTU、DNS、节点负载和实际命中的出站策略,并一次只更换一个变量。
相关阅读
参考资料
- Graphical Clients - sing-box 官方图形客户端列表
- sing-box for Desktop 官方文档
- sing-box for Apple platforms 官方文档
- sing-box 官方配置介绍
- sing-box 官方 Package Manager 文档
- sing-box 官方 Change Log
- sing-box 官方 Migration 文档
- sing-box 官方客户端代理模式说明
- sing-box 官方 Tun 配置文档
- SagerNet/sing-box 官方 GitHub Releases
- sing-box.sagernet.org
- sing-box.sagernet.org