11号登机口GATE 11 · 机场推荐与选购笔记
使用教程 · 全平台

sing-box 使用教程(2026):官方客户端下载、导入订阅与设置

sing-box 使用教程:sing-box 怎么用、从哪里下载官方客户端、怎么导入机场订阅,覆盖安卓、iPhone、Mac、Windows 和 Linux。讲清远程配置导入、与 Clash 订阅格式的区别、导入后检查、sing-box 连不上的报错对照,以及和 Clash、v2rayN 哪个好。

更新于 约 6325 字 · 14 分钟读完11号登机口编辑
快速结论

这篇 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 官方客户端

几个直接影响使用的结论:

  1. 链接不通用。sing-box 的「远程配置」拿到的必须是一份完整的 sing-box JSON。把 Clash 的 YAML 或者 Base64 通用订阅喂给它,只会得到解析错误。
  2. 怎么判断手里的链接是哪种。最可靠的办法是看机场后台按钮上写的名字。实在分不清,可以在自己的电脑浏览器里打开链接看一眼内容:以花括号开头、能看到 outbounds 的是 sing-box 格式;能看到 proxies: 的是 Clash 格式;一长串没有空格的字母数字是 Base64 通用订阅。看完关掉页面,不要截图外传,订阅链接等同于账号密码。
  3. 机场没有 sing-box 格式怎么办。最省事的做法是换客户端,而不是换格式。所谓订阅转换,是把你的订阅交给一个转换服务重新生成配置,对方能看到你的全部节点信息,风险和原理见订阅链接与订阅转换。
  4. 格式会随版本变化。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)」几个区域。界面语言和具体文字随版本和系统语言变化,下面按功能描述。

  1. 打开客户端,进入「配置(Profiles)」页。
  2. 点新建配置的按钮(通常是加号或 New Profile)。
  3. 名称随便填,方便自己辨认即可。
  4. 类型选「远程(Remote)」。
  5. 在 URL 一栏粘贴你的机场后台里的 sing-box 订阅链接。
  6. 自动更新保持开启。按官方文档的说明,远程配置默认每 60 分钟自动更新一次,间隔可以自己改。
  7. 保存。回到配置列表,确认新配置处于选中状态。

配置类型一共三种,了解一下区别:

类型 配置从哪里来 适合什么情况
本地(Local) 保存在设备上,可在客户端内编辑 自己手写或修改配置
iCloud 存在 iCloud 的 sing-box 文件夹里,仅苹果平台 多台苹果设备共用一份自己写的配置
远程(Remote) 从一个链接下载,定时更新 机场订阅,绝大多数人用这个

很多机场后台有一键导入按钮,点了会直接唤起客户端并填好链接和名称,效果和手动新建一样。导入失败时,先按订阅导入与更新里的清单检查链接是否完整、套餐是否到期。

启动、选节点、切换模式

  1. 回到「仪表盘(Dashboard)」,点启动按钮。
  2. 第一次启动时,系统会弹出添加 VPN 配置或连接请求的确认框,这是客户端创建虚拟网卡所必需的,点允许。iPhone 上还需要输入锁屏密码。
  3. 启动成功后,仪表盘会出现几块内容:
  • 状态:内存占用、连接数、上下行流量。
  • 模式(Mode):只有当配置里定义了两种以上模式时才会出现,常见的是规则、全局、直连三种,名称由机场的配置决定。日常保持规则模式。
  • 分组(Groups):配置里的策略组。类型是手动选择(selector)的组可以点开换节点;类型是自动测速(urltest)的组由程序按延迟自动挑选,只能查看,不能手动指定。

选节点的思路和其他客户端一样:超时的不选,同地区里延迟低一些的优先,但延迟不等于速度,判断方法见切换节点与测延迟。用 AI 工具或流媒体时该选哪个地区,可以参考 AI 网络环境与节点选择。

验证是否生效:打开浏览器访问一个平时打不开的网站。打不开时,先看「日志(Logs)」页有没有成片的报错,再按连上但打不开网页逐项排查。

导入订阅后怎么检查是否正常

远程配置保存成功、服务也启动了,再用几分钟确认配置内容完整、分流方向正确:

  1. 配置的更新时间:配置列表里通常会显示上次更新的时间。刚导入的配置如果显示从未更新,或者时间停在很久以前,手动更新一次再看。
  2. 分组和节点数量:仪表盘的分组里能看到机场定义的策略组,组内节点数量和后台大致一致。只出现一个写着流量或到期信息的条目,说明套餐有问题。
  3. 日志里有没有成片报错:启动后看一眼「日志」页。偶尔一两条连接失败属于正常,持续刷屏的同一种报错才需要处理,对照下一节的表格。
  4. 国内网站是否直连:打开几个国内网站,在日志里看它们走的是直连出站(通常叫 direct),而不是节点。
  5. 出口地区:用浏览器打开 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 最有代表性的问题。它不是你的设备坏了,而是配置和程序版本对不上。不要为了迁就旧配置去装来路不明的旧版本,正确的顺序是先把客户端更新到官方正式版,再请机场更新配置。

如果日志里没有明显报错,服务也显示已启动,但就是打不开网页,按这个顺序缩小范围:

  1. 确认服务真的在运行:仪表盘里状态显示的连接数和流量会随你的访问变化。数字一直为零,说明流量根本没有交给 sing-box,安卓上看是否被其他 VPN 应用顶掉,苹果设备上看系统设置里的 VPN 状态。
  2. 切到全局对照:配置里有模式切换的,临时切到全局,在手动选择组里换一个节点。全局能打开,问题在规则或规则集;全局也打不开,问题在节点或订阅。
  3. 手动更新配置并重启服务:机场调整节点后,旧配置会让所有连接超时。
  4. 核对套餐和系统时间:到后台确认流量和到期日,把设备时间设为自动同步。

四步做完仍然不行,带着日志里的报错原文(隐去订阅链接)联系机场客服。更通用的排查顺序见机场连不上怎么办。

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 会定时测试组内节点的延迟,自动挑选较低的那个,适合日常浏览。机场配置里通常两种都有,手动选择组里常常还会把自动测速组作为一个选项。