CreamData

sing-box 怎么用?从配置判断到启动排错的完整教程

更新于 2026-10-24 · creamdata.site

简答:sing-box 的用法是先判断配置格式,再按设备选择客户端或核心,导入并启用配置,最后通过日志、命中策略和出口 IP 验证是否生效。Clash YAML 不能默认直接导入。

定义:sing-box 是使用 JSON 配置的网络代理平台,核心程序负责运行配置,图形客户端负责配置管理、平台权限与 TUN 等功能。

先照这张速查卡操作:5 步完成 sing-box 基础使用

下载了核心程序却无法双击打开,或把 Clash YAML 导入后提示格式错误,通常不是节点本身的问题,而是核心、客户端和配置格式没有分清。本站是第三方使用指南站,以下步骤只整理公开文档中的通用操作。

sing-box 新手五步速查
步骤要做什么判断标准
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 权限。核心程序不是通常意义上的桌面应用,直接双击后没有图形界面属于正常情况。

设备优先选择使用方式权限或兼容提醒
Windowssing-box for Desktop管理本地或远程配置,按客户端界面启用代理或 TUN。支持 Windows 10 及以上,架构包括 x64、x86 和 arm64。
Linuxsing-box for Desktop 或命令行核心桌面设备可用图形客户端;服务器适合核心加 systemd。TUN、路由和监听权限按配置与系统服务权限处理。
Androidsing-box for Android导入配置后通过 Android VPN 授权运行。系统弹出 VPN 授权时需要允许;不要同时运行多个 VPN 类应用。
iOSsing-box for Apple platforms导入本地或远程配置,再授权 VPN 配置。不能按 Linux 核心的方式直接双击运行。
macOSsing-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 配置介绍。

导入配置、启动代理并验证是否真的生效

  1. 安装客户端或核心:根据设备和架构选择官方发布资产;Linux 服务器优先使用官方包管理方式。
  2. 添加配置:在客户端的配置、Profiles 或订阅页面粘贴远程 URL,或选择本地 config.json。
  3. 确认配置内容:导入后检查配置名称、出站节点、DNS、路由和 TUN 选项是否符合预期。
  4. 设为活动配置:导入成功不等于已经运行,需要在配置列表中选中它。
  5. 先做低风险测试:优先启用客户端提供的系统代理或基础代理模式,确认浏览器和日志正常后,再测试 TUN。
  6. 验证实际流量:打开连接日志,确认目标域名出现并命中了预期出站策略;再对比启用前后的出口 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、节点负载和实际命中的出站策略,并一次只更换一个变量。

相关阅读

参考资料

  1. Graphical Clients - sing-box 官方图形客户端列表
  2. sing-box for Desktop 官方文档
  3. sing-box for Apple platforms 官方文档
  4. sing-box 官方配置介绍
  5. sing-box 官方 Package Manager 文档
  6. sing-box 官方 Change Log
  7. sing-box 官方 Migration 文档
  8. sing-box 官方客户端代理模式说明
  9. sing-box 官方 Tun 配置文档
  10. SagerNet/sing-box 官方 GitHub Releases
  11. sing-box.sagernet.org
  12. sing-box.sagernet.org