sing-box 使用教程(2026):官方客户端下载、导入订阅与设置
sing-box 使用教程:sing-box 怎么用、从哪里下载官方客户端、怎么导入机场订阅,覆盖安卓、iPhone、Mac、Windows 和 Linux。讲清远程配置导入、与 Clash 订阅格式的区别、导入后检查、sing-box 连不上的报错对照,以及和 Clash、v2rayN 哪个好。
这篇 sing-box 使用教程的要点:图形客户端只从官方文档列出的渠道获取,安卓走 Google Play、F-Droid 或 GitHub Releases,iPhone 走非大陆区 App Store,电脑端走 GitHub Releases。导入时新建一个「远程(Remote)」配置,填入你的机场后台里的 sing-box 格式订阅链接;Clash 格式的链接它读不了,机场没有提供 sing-box 格式时,换用 Clash 系客户端更省事。 导入后报错,先分清是「拿错了格式」还是「配置和客户端版本对不上」,两者的处理方法完全不同。
sing-box 怎么用:从下载到上网的五步
sing-box 的使用流程本身不复杂,难点集中在订阅格式上。把流程拆开看:
| 步骤 | 做什么 | 关键点 |
|---|---|---|
| 1 | 确认机场提供 sing-box 格式的订阅 | 后台按钮写着 sing-box,或有一键导入;没有就换 Clash 系客户端 |
| 2 | 从官方文档列出的渠道下载客户端 | 不在商店里凭名字搜索同名应用 |
| 3 | 在「配置」页新建远程配置,粘贴订阅链接 | 类型选远程,保存后确认被选中 |
| 4 | 在仪表盘启动,允许 VPN 或连接请求 | 第一次启动才会弹窗 |
| 5 | 在手动选择组里选节点,检查出口地区 | 自动测速组只能看,不能手动选 |
和其他客户端最大的区别在第 1 步:别的客户端拿到什么链接都可以先试试,sing-box 拿错格式就一定失败。所以动手前花一分钟确认格式,比装好之后反复排查省事得多。下面各节按这个顺序展开。
sing-box 是什么,适合谁用
sing-box 是 SagerNet 项目维护的开源代理内核,官方同时维护了一套图形客户端。它和 Clash 系(现在主要是 mihomo 内核)是两条并行的路线:能做的事情大体相同,都是按规则决定哪些流量直连、哪些走节点,但配置文件的写法完全不同,互相不能直接读取。
适合用 sing-box 的几种情况:
- 你的机场后台明确提供 sing-box 格式的订阅,或者有「导入到 sing-box」的按钮。
- 你想在 iPhone、安卓、电脑上用同一套客户端和同一份配置,减少学习成本。
- 你愿意读一点 JSON 配置,想自己控制 DNS、路由规则这些细节。
不太适合的情况也要说清楚:
- 机场只提供 Clash 订阅和通用订阅。这时硬上 sing-box 需要自己转换配置,出了问题很难找人帮忙。
- 你只想要「粘贴链接、点一下就能用」的体验,并且希望界面全是中文、网上教程多。这类需求用 Clash Verge Rev、FlClash 或 Shadowrocket 会顺手得多。
客户端只是工具,本身不带节点。还没弄清机场和客户端的关系,先读机场是什么。
先弄清楚:sing-box 订阅和 Clash 订阅不是一回事
很多人卡在第一步,就是把 Clash 订阅链接粘进了 sing-box。两种格式的差别如下:
| 对比项 | Clash / mihomo | sing-box |
|---|---|---|
| 文件格式 | YAML | JSON |
| 节点写在哪 | proxies |
outbounds |
| 策略组 | proxy-groups(select、url-test 等) |
outbounds 里类型为 selector、urltest 的条目 |
| 分流规则 | rules、rule-providers |
route 里的 rules、rule_set |
| DNS | dns 段 |
dns 段,但字段和写法不同 |
| 订阅的含义 | 一份完整配置,客户端可以再做覆写 | 远程配置就是一整份可直接运行的 JSON |
| 常见客户端 | Clash Verge Rev、FlClash、Stash 等 | sing-box 官方客户端 |
几个直接影响使用的结论:
- 链接不通用。sing-box 的「远程配置」拿到的必须是一份完整的 sing-box JSON。把 Clash 的 YAML 或者 Base64 通用订阅喂给它,只会得到解析错误。
- 怎么判断手里的链接是哪种。最可靠的办法是看机场后台按钮上写的名字。实在分不清,可以在自己的电脑浏览器里打开链接看一眼内容:以花括号开头、能看到
outbounds的是 sing-box 格式;能看到proxies:的是 Clash 格式;一长串没有空格的字母数字是 Base64 通用订阅。看完关掉页面,不要截图外传,订阅链接等同于账号密码。 - 机场没有 sing-box 格式怎么办。最省事的做法是换客户端,而不是换格式。所谓订阅转换,是把你的订阅交给一个转换服务重新生成配置,对方能看到你的全部节点信息,风险和原理见订阅链接与订阅转换。
- 格式会随版本变化。sing-box 的配置字段会随版本演进,旧字段先被标记为弃用,再在后续版本中移除。机场下发的配置如果是按旧版本写的,新版客户端可能直接报错。这不是你操作有误,后面的常见问题里有处理思路。
选机场时如果你确定要用 sing-box,下单前先确认对方支持这种格式。各家支持的客户端和协议在机场测评页里有整理,公开资料没写明的需要自己到官网确认。
sing-box 配置文件结构:入站、出站、路由各管什么
结论:一份 sing-box 配置可以按「流量从哪进来、按什么规则分、从哪出去」三段来读,分别对应 inbounds、route、outbounds,再加上负责域名解析的 dns。看懂这四块,报错信息指向哪一段就大致能判断问题出在哪。
| 顶层字段 | 负责什么 | 机场订阅里通常的样子 |
|---|---|---|
log |
日志级别和输出位置 | 一般设为 info 或 warn |
dns |
域名用哪个服务器解析,国内外域名分开处理 | 国内域名交给国内 DNS,其余通过代理解析 |
inbounds |
流量怎么进入 sing-box | 图形客户端常见 tun(虚拟网卡),也可能有 mixed(本地 HTTP/SOCKS 端口) |
outbounds |
流量从哪里出去 | 机场的每个节点、手动选择组(selector)、自动测速组(urltest)、直连 |
route |
分流规则和规则集,以及兜底出站 | 国内直连、广告拦截、其余走代理组 |
experimental |
实验性功能,如缓存文件、兼容 Clash 面板的接口 | 部分机场会开启,用于记住你选的节点 |
几种入站的区别值得了解:tun 会接管整台设备的流量,图形客户端默认用它,不需要再设置系统代理;mixed 只是在本机开一个端口,只有主动设置了代理的程序才会走它,适合命令行工具和服务器。在电脑上,命令行工具不走代理的问题,往往就是因为配置里只有其中一种入站,背景见终端与开发工具代理。
route 里的 final 决定所有规则都没命中的流量走哪个出站。开着 sing-box 却所有网站都直连,先看 final 指向的是不是代理组。
sing-box 下载:从官方渠道获取客户端
官方文档的客户端页面是唯一可信的入口:sing-box 官方文档 和 SagerNet/sing-box 官方仓库。官方文档里专门提醒过,第三方打着 sing-box 名义的客户端不在官方列表里,质量和安全性没有保证。
| 平台 | 官方获取方式 | 备注 |
|---|---|---|
| 安卓 | Google Play、F-Droid、GitHub Releases | 官方标注需要 Android 5.0 及以上 |
| iPhone / iPad / Apple TV | App Store | 需要非中国大陆区的 Apple 账户;官方标注 iOS 15.0、tvOS 17.0 及以上 |
| macOS | Homebrew 或 GitHub Releases 的独立版 | 官方标注 macOS 13.0 及以上 |
| Windows / Linux | GitHub Releases 里的桌面客户端 | 官方标注 Windows 10 及以上;Linux 提供 x64、arm64 等架构 |
几点说明:
- iPhone 用户需要先有一个非大陆区的 Apple 账户,注册方法见非大陆区 Apple ID 怎么注册。App Store 里的应用名称可能调整,最稳妥的做法是从官方文档 Apple 客户端页面里的 App Store 链接点进去,不要在商店里凭名字搜索后随手下载同名应用。
- macOS 独立版可以用 Homebrew 安装,官方文档给出的命令是:
brew install sfm
- 安卓用户装不了 Google Play 的,直接到 GitHub Releases 下载 APK。Releases 页面里文件很多,既有命令行内核,也有各平台的图形客户端安装包,按文件名里的系统和架构字样挑选;多数手机选 arm64 对应的包。
- TestFlight 测试版的名额官方说明只面向赞助者,普通用户用正式版即可。
sing-box 导入订阅:新建远程配置
各平台的界面结构基本一致,一般有「仪表盘(Dashboard)」「配置(Profiles)」「日志(Logs)」「设置(Settings)」几个区域。界面语言和具体文字随版本和系统语言变化,下面按功能描述。
- 打开客户端,进入「配置(Profiles)」页。
- 点新建配置的按钮(通常是加号或 New Profile)。
- 名称随便填,方便自己辨认即可。
- 类型选「远程(Remote)」。
- 在 URL 一栏粘贴你的机场后台里的 sing-box 订阅链接。
- 自动更新保持开启。按官方文档的说明,远程配置默认每 60 分钟自动更新一次,间隔可以自己改。
- 保存。回到配置列表,确认新配置处于选中状态。
配置类型一共三种,了解一下区别:
| 类型 | 配置从哪里来 | 适合什么情况 |
|---|---|---|
| 本地(Local) | 保存在设备上,可在客户端内编辑 | 自己手写或修改配置 |
| iCloud | 存在 iCloud 的 sing-box 文件夹里,仅苹果平台 | 多台苹果设备共用一份自己写的配置 |
| 远程(Remote) | 从一个链接下载,定时更新 | 机场订阅,绝大多数人用这个 |
很多机场后台有一键导入按钮,点了会直接唤起客户端并填好链接和名称,效果和手动新建一样。导入失败时,先按订阅导入与更新里的清单检查链接是否完整、套餐是否到期。
启动、选节点、切换模式
- 回到「仪表盘(Dashboard)」,点启动按钮。
- 第一次启动时,系统会弹出添加 VPN 配置或连接请求的确认框,这是客户端创建虚拟网卡所必需的,点允许。iPhone 上还需要输入锁屏密码。
- 启动成功后,仪表盘会出现几块内容:
- 状态:内存占用、连接数、上下行流量。
- 模式(Mode):只有当配置里定义了两种以上模式时才会出现,常见的是规则、全局、直连三种,名称由机场的配置决定。日常保持规则模式。
- 分组(Groups):配置里的策略组。类型是手动选择(selector)的组可以点开换节点;类型是自动测速(urltest)的组由程序按延迟自动挑选,只能查看,不能手动指定。
选节点的思路和其他客户端一样:超时的不选,同地区里延迟低一些的优先,但延迟不等于速度,判断方法见切换节点与测延迟。用 AI 工具或流媒体时该选哪个地区,可以参考 AI 网络环境与节点选择。
验证是否生效:打开浏览器访问一个平时打不开的网站。打不开时,先看「日志(Logs)」页有没有成片的报错,再按连上但打不开网页逐项排查。
导入订阅后怎么检查是否正常
远程配置保存成功、服务也启动了,再用几分钟确认配置内容完整、分流方向正确:
- 配置的更新时间:配置列表里通常会显示上次更新的时间。刚导入的配置如果显示从未更新,或者时间停在很久以前,手动更新一次再看。
- 分组和节点数量:仪表盘的分组里能看到机场定义的策略组,组内节点数量和后台大致一致。只出现一个写着流量或到期信息的条目,说明套餐有问题。
- 日志里有没有成片报错:启动后看一眼「日志」页。偶尔一两条连接失败属于正常,持续刷屏的同一种报错才需要处理,对照下一节的表格。
- 国内网站是否直连:打开几个国内网站,在日志里看它们走的是直连出站(通常叫
direct),而不是节点。 - 出口地区:用浏览器打开
https://www.cloudflare.com/cdn-cgi/trace,loc=后面的两位代码就是出口地区,应该和你在手动选择组里选的地区一致。
命令行内核也能用同样的思路检查:sing-box check -c config.json 没有输出表示配置合法,再用 curl 指定本地入站端口访问上面的地址看出口。
sing-box 连不上:常见报错和对应处理
报错原文随版本变化,下面按日志里常见的关键词归类:
| 报错关键词或现象 | 多半的原因 | 处理 |
|---|---|---|
unknown field、decode config |
配置里有当前版本不认识的字段,或者拿到的根本不是 sing-box 格式 | 确认链接是 sing-box 格式;客户端和配置版本对齐 |
| 提示某项已弃用(deprecated) | 配置按旧写法生成,暂时还能用 | 先不用管,联系机场更新配置模板 |
| 规则集(rule-set)下载失败 | 首次启动要下载远程规则集,网络不通 | 换网络重试;或请机场改用内置规则集 |
address already in use |
本地端口被别的代理软件占用 | 退出其他代理客户端后重启服务 |
大量 timeout、EOF |
节点不通、配置过旧或系统时间不准 | 更新配置;把系统时间设为自动同步 |
| 启动时提示权限不足 | 没有允许 VPN 配置,或 Linux 上没以 root 运行 TUN | 重新允许 VPN 请求;命令行用 sudo 或 systemd 服务 |
unknown field 这一类是 sing-box 最有代表性的问题。它不是你的设备坏了,而是配置和程序版本对不上。不要为了迁就旧配置去装来路不明的旧版本,正确的顺序是先把客户端更新到官方正式版,再请机场更新配置。
如果日志里没有明显报错,服务也显示已启动,但就是打不开网页,按这个顺序缩小范围:
- 确认服务真的在运行:仪表盘里状态显示的连接数和流量会随你的访问变化。数字一直为零,说明流量根本没有交给 sing-box,安卓上看是否被其他 VPN 应用顶掉,苹果设备上看系统设置里的 VPN 状态。
- 切到全局对照:配置里有模式切换的,临时切到全局,在手动选择组里换一个节点。全局能打开,问题在规则或规则集;全局也打不开,问题在节点或订阅。
- 手动更新配置并重启服务:机场调整节点后,旧配置会让所有连接超时。
- 核对套餐和系统时间:到后台确认流量和到期日,把设备时间设为自动同步。
四步做完仍然不行,带着日志里的报错原文(隐去订阅链接)联系机场客服。更通用的排查顺序见机场连不上怎么办。
sing-box 使用教程补充:按错误发生的阶段排查
结论:把问题按「导入、启动、连接、访问」四个阶段归类,每个阶段对应的原因范围很小,比对着报错逐条搜索快得多。
| 阶段 | 典型表现 | 排查重点 |
|---|---|---|
| 导入阶段 | 远程配置保存失败、更新失败、提示解析错误 | 链接是否完整、是不是 sing-box 格式、套餐是否到期、当前网络能否访问订阅域名 |
| 启动阶段 | 点启动后立即停止,日志里有配置错误或权限错误 | 客户端版本和配置是否对得上、是否允许了 VPN 请求、端口是否被其他软件占用 |
| 连接阶段 | 服务在运行,但节点全部超时 | 节点是否已被机场更换、系统时间是否准确、当前网络是否限制某些协议 |
| 访问阶段 | 部分网站能开、部分不能,或国内网站变慢 | 规则集是否下载成功、final 指向、DNS 设置、所选节点地区是否合适 |
判断自己处在哪个阶段很简单:配置列表里看不到新配置或显示更新失败,属于导入阶段;仪表盘的启动按钮按下又弹回,属于启动阶段;服务显示运行中但连接数一直为零或全是超时,属于连接阶段;能打开一部分网站,属于访问阶段。
导入阶段失败时,有一个容易被忽略的原因:订阅域名本身在直连网络下打不开。这时可以先用另一台已经能上网的设备,或者暂时用其他还能用的代理更新一次配置,拿到最新节点后再切回来。
sing-box 和 Clash、v2rayN 哪个好
| 对比项 | sing-box 官方客户端 | Clash 系(Clash Verge Rev、FlClash 等) | v2rayN |
|---|---|---|---|
| 平台 | 安卓、苹果全家、Windows、Linux | Windows、macOS、Linux、安卓 | 以 Windows 为主 |
| 订阅格式 | sing-box JSON | Clash / Mihomo YAML | 通用订阅、分享链接 |
| 机场支持面 | 较窄,要确认后台有对应格式 | 最广 | 广 |
| 界面与中文教程 | 偏简洁,教程较少 | 中文界面,教程多 | 中文界面,教程多 |
| 适合 | 多平台想用同一套客户端、愿意看文档的人 | 新手和多数人 | 习惯单节点列表的 Windows 用户 |
几条判断依据:机场后台有 sing-box 格式、并且你在 iPhone 和电脑上都想用同一款免费客户端时,sing-box 的优势最明显;只有 Clash 格式时,直接用 Clash 系;只拿到通用订阅时,Windows 上用 v2rayN 更顺手。本站整理的公开资料里,宝云、九云等几家在客户端列表里写了 sing-box,下单前仍以官网说明为准。
同一条 sing-box 订阅可以同时导入手机、平板和电脑,每台设备各自定时更新,不需要用 iCloud 类型来同步;iCloud 类型适合的是你自己手写、想在几台苹果设备间共用的本地配置。要注意的是,几台设备同时在线会各占一个机场的在线设备名额,有设备数限制的套餐要算好数量。
sing-box 安卓和 iPhone、电脑版有什么不同
官方各平台客户端用的是同一个内核、同一种配置格式,同一条订阅可以在所有平台导入。差别主要在系统层面的能力:
| 平台 | 和其他平台不同的地方 | 需要留意 |
|---|---|---|
| 安卓 | 可以按应用决定是否走代理 | 同一时间只能有一个 VPN 类应用生效 |
| iPhone / iPad | 需要非大陆区 Apple 账户获取,支持按需连接 | 关不掉代理时先看按需连接是否打开 |
| Mac | 有商店版和独立版两种来源 | 终端和命令行工具是否走代理,取决于你用的是系统代理还是虚拟网卡 |
| Windows / Linux | 也可以只装命令行内核 | 虚拟网卡模式通常需要管理员或 root 权限 |
各平台的菜单文字不完全一样,不同版本也略有差异,但「配置、仪表盘、日志、设置」这几个区域的分工是一致的。在一台设备上用熟之后,换到其他平台基本不需要重新学。如果你只在一个平台上用,并且机场同时给了 Clash 格式,各平台的常用选择可以对照 Windows 电脑怎么用机场和 iPhone 怎么用机场。
sing-box 设置:值得知道的几项
手动更新配置。节点大面积不通时,先到配置页手动更新一次远程配置,再重启服务。机场调整节点后,旧配置里的地址会失效。
安卓分应用代理。安卓客户端的设置里有按应用决定是否走代理的选项,可以让国内应用完全绕过,省电也省流量。入口在设置里和配置覆盖相关的菜单下,不同版本文字略有差异。
苹果平台的按需连接。设置里可以让 VPN 在断开后自动重连。常年开着的话比较省心,但排查网络问题时记得先把它关掉,否则你以为关了代理,其实它又连上了。
内核信息与工作目录。设置页能看到当前内核版本,还有清理工作目录的按钮。遇到规则集缓存异常、配置更新后行为不对时,清理一次再重新启动。
自己改配置。远程配置每次更新都会被覆盖,想长期保留自己的改动,需要把配置另存为本地类型再编辑,代价是之后节点变更要自己同步。改之前先读官方文档的配置章节,不要照搬网上年代不明的模板,字段可能早已弃用。
命令行内核:服务器和无界面环境
图形客户端之外,sing-box 也可以作为纯命令行程序运行,适合 Linux 服务器或软路由。官方文档给出的安装方式包括:
# macOS / Linux,使用 Homebrew
brew install sing-box
# Windows,使用 Scoop 或 winget
scoop install sing-box
winget install sing-box
# deb / rpm 系等 Linux 发行版,官方安装脚本
curl -fsSL https://sing-box.app/install.sh | sh
把从订阅链接下载到的 JSON 存为配置文件后,先检查再运行:
sing-box check -c config.json
sing-box run -c config.json
用软件包安装的 Linux 一般自带 systemd 服务,常用操作是:
sudo systemctl enable sing-box
sudo systemctl start sing-box
sudo journalctl -u sing-box --output cat -e
服务默认读取哪个目录下的配置,以官方文档和 systemctl cat sing-box 的输出为准。如果你的机场只提供 Clash 订阅,服务器上用 mihomo 内核更直接,见 Linux 上用 mihomo 的命令行教程。命令行环境里怎样让 Git、npm 这些工具走代理,见终端与开发工具代理。
不同国家和地区对代理工具的规定不同,请遵守当地法律。
常见问题
sing-box 能直接导入 Clash 订阅链接吗?
不能。sing-box 的远程配置要求链接返回的是一份完整的 sing-box JSON 配置,Clash 的 YAML 和 Base64 通用订阅都无法解析。先到机场后台找 sing-box 专用的订阅链接;没有的话,换用 Clash 系客户端是最稳妥的办法。
导入后启动报错,提示配置字段已弃用或无法识别怎么办?
这通常是配置格式和客户端版本对不上:机场下发的配置按旧版写法生成,而你装的是新版客户端,或者反过来。先把客户端更新到官方最新正式版并手动更新一次配置;仍然报错,就把报错文字(隐去订阅链接)发给机场客服,请对方更新配置模板。不要为了兼容去第三方网站下载旧版安装包。
iPhone 上搜不到 sing-box 怎么办?
官方客户端没有在中国大陆区 App Store 上架,需要用非大陆区的 Apple 账户登录 App Store 后再获取。建议从官方文档 Apple 客户端页面里的链接进入商店页面,避免装到名字相近的非官方应用。
仪表盘里为什么没有模式切换,或者有的分组不能手动选节点?
模式切换只有在配置里定义了两种以上模式时才显示,这取决于机场下发的配置。分组不能手动选,是因为那个组的类型是自动测速,由程序按延迟自动挑选节点;想手动指定,就到类型为手动选择的那个组里操作。
远程配置多久更新一次,需要手动更新吗?
按官方文档的说明,远程配置默认每 60 分钟自动更新一次,可以在配置的编辑页修改间隔。平时不用管;节点突然大面积超时、或者机场公告调整了线路时,手动更新一次再重启服务。更新失败的排查见订阅更新失败。
安卓上 sing-box 和 Clash Meta for Android 选哪个?
看机场给什么格式。后台只有 Clash 订阅,就用 Clash Meta for Android 或 FlClash,导入最省事;后台有 sing-box 格式,两者都可以,sing-box 的好处是和你在其他平台上用的是同一款客户端。不建议两个同时开着,安卓同一时间只允许一个 VPN 类应用生效。
sing-box 和 Clash 系客户端哪个更好?
没有绝对的好坏,要看机场给什么格式、你习惯什么界面。机场同时提供两种格式时,日常体验差别不大;只提供 Clash 格式时,直接用 Clash 系客户端。想比较不同机场对客户端的支持,可以看 Clash 机场推荐和新手机场推荐。
关掉 sing-box 之后断网了怎么办?
正常停止服务后,虚拟网卡会被移除,网络应自动恢复。断网时先确认服务真的已停止,苹果设备上还要检查按需连接是否把它又拉了起来;电脑上检查系统代理设置是否残留了本地端口。仍然不行,重启设备通常能恢复,系统代理残留的处理见关闭代理后断网。
sing-box 能在软路由上当透明网关吗?
内核本身支持在 Linux 上用虚拟网卡或透明代理的方式给局域网其他设备提供代理,但需要自己写配置、处理路由转发和 DNS,门槛比图形客户端高很多。只是想让家里设备都能用,路由器上装现成插件更省事,思路见 OpenClash 教程和局域网共享代理教程。
sing-box 配置里的 selector 和 urltest 有什么区别?
两者都是策略组。selector 是手动选择,你点哪个节点就用哪个,适合 AI 工具这类需要固定出口的用途;urltest 会定时测试组内节点的延迟,自动挑选较低的那个,适合日常浏览。机场配置里通常两种都有,手动选择组里常常还会把自动测速组作为一个选项。