sing-box 入门：客户端、配置导入与连接验证

先分清内核、客户端与配置

sing-box 既能作为本机代理程序，也能用于服务端。内核读取配置并处理网络连接；图形客户端负责保存配置、启停服务、显示状态和申请系统权限。安装内核压缩包，不等于安装了带订阅管理界面的应用。

本文走的是本机客户端路线。开始前要有一个自己有权使用的配置来源；客户端本身不提供节点、账户或远程服务器。如果你还不知道订阅和节点的区别，先读机场代理基础。

按设备选择官方图形客户端

官方客户端目录目前分别列出 Android、Apple 平台、Windows 与 Linux 的客户端入口：

设备	官方入口	安装前检查
Android	sing-box for Android（SFA）	从官方页进入应用商店或 Releases，确认系统和架构要求
iPhone / iPad	sing-box for Apple platforms	由官方页跳转 App Store，核对开发者、系统要求与商店可用性
macOS	Apple 平台页面中的 macOS 独立版	区分 Apple 芯片与 Intel 包，按该版本安装说明处理系统扩展
Windows / Linux	sing-box for Desktop	选择对应系统、CPU 架构和安装格式，避免误下载命令行核心包

不要仅凭应用名里有 sing-box 判断是否官方。第三方客户端可能也使用相同内核，但其配置导入、更新和备份行为应以自己的文档为准。Android、iOS 和 macOS 的逐平台安装与授权流程见手机与 Apple 设备教程。

先确认拿到的内容能否使用

官方客户端的配置对象是完整的 sing-box JSON 文件。远程配置只是把文件放在 URL 上，由客户端下载更新；它不等于任意一种“订阅链接”。

手上的内容	下一步
提供方明确标注 sing-box 的远程配置 URL	核对适用核心版本，再作为远程配置添加
.json 文件	确认包含入站、出站与路由等必要内容，再作为本地配置导入
Clash / mihomo YAML	向提供方获取 sing-box 版本；更改文件扩展名不能转换格式
vless://、trojan:// 等分享链接合集	先确认当前应用有无节点解析功能；官方配置导入不能被假定等同于分享链接导入
服务商登录页、订购页或返回 HTML 的 URL	重新复制用户面板里的配置地址

完整格式判断、远程更新与换机流程见订阅导入指南。不确定时，让提供方说明“适用哪个客户端、最低哪个核心版本、是否含 TUN 和 DNS”，比反复尝试不同入口更有效。

从导入到运行的完整流程

界面文案会随平台、语言和版本变化。以下按功能描述，不把某个版本的按钮位置当作所有设备的标准。

1. 记录版本与原始网络状态。 在客户端关于或核心信息中记下应用和核心版本；暂时停止其他代理或 VPN，确认设备原本能正常访问日常网站。
2. 新增配置。 有 URL 就选择远程配置，有文件就选择本地配置。填一个便于识别的名称，粘贴完整地址或选择文件，保存并等待首次下载完成。官方通用文档区分本地、iCloud 与远程配置，不同来源的更新方式不同。
3. 确认已下载，再设为当前配置。 检查配置内容或更新时间，避免只创建了一个空条目。远程 URL 能保存，不代表内容已经下载、解析成功。
4. 启动服务并授权。 手机首次会出现 VPN 连接授权，macOS 独立版可能要求允许网络扩展，桌面 TUN 可能需要系统权限。确认请求来自刚安装的应用后，按该版本官方说明处理。
5. 检查运行状态。 状态应保持运行，日志中不应反复出现配置解析错误或权限错误。若有 selector 策略组，选择一个实际代理出站；若组内选中 direct，业务仍可能直连。
6. 发起真实请求。 用自己需要的浏览器或应用访问一个预期经代理的 HTTPS 站点，检查客户端连接或日志中该请求的出站，再验证一个应直连的网站。
7. 停止后复查。 用应用内停止功能断开，确认系统 VPN 状态或本地代理状态恢复，日常网页仍能访问。首次配置要把退出恢复也验证一次。

这里的成功标准是“配置能加载、服务持续运行、目标请求走预期出站、停止后恢复网络”四项同时成立。VPN 标志和流量计数只说明服务在工作，不能单独证明某个网站已经通过指定节点。

看懂 JSON 配置的四个部分

字段	回答的问题	常见内容
inbounds	流量从哪里进入核心？	mixed 本地代理端口、tun 虚拟网卡
outbounds	流量从哪里离开核心？	远程代理、direct、selector、urltest
route	每条连接选哪个出站？	匹配规则、规则集、默认出站
dns	域名交给谁解析？	DNS 服务器与解析规则

配置字段、平台支持和默认行为会变化，应对照与安装版本相符的配置文档。不要把其他核心的 JSON 当作 sing-box JSON：同为 JSON 只是文件语法相同，字段体系仍不同。

下面给出桌面本地端口模式的结构示例。IP 使用文档专用地址，证书域名和密码也是占位符，不能直接连接；没有 TUN、分流规则或移动端 VPN 配置，不适合直接导入手机启动。

{
  "log": { "level": "info" },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "local-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "trojan",
      "tag": "proxy",
      "server": "192.0.2.10",
      "server_port": 443,
      "password": "replace-with-your-own-password",
      "tls": {
        "enabled": true,
        "server_name": "node.example.com"
      }
    }
  ],
  "route": { "final": "proxy" }
}

local-in 接收应用发给 127.0.0.1:2080 的 HTTP 或 SOCKS 请求，route.final 把这些请求交给 tag 为 proxy 的出站。真实服务器若有额外 TLS、传输层或认证参数，必须使用提供方给出的完整配置。Mixed 入站与Trojan 出站各自有独立字段说明。

要替换的值	从哪里取得	不应混淆的含义
server / server_port	自建服务端或提供方节点参数	这是节点的连接地址与端口，不是订阅面板地址
password	该 Trojan 节点的认证信息	不一定等于账户登录密码
tls.server_name	该节点要求的证书名称 / SNI	与 IP 地址是两项参数，不能把 IP 一并填进证书名称
listen_port	自己选定且未被占用的本地端口	修改后，测试命令与应用代理端口也要同步

示例用 IP 连接节点，避免把节点域名的解析配置藏在最小示例里。若真实 server 是域名，须同时满足当前版本的解析器要求：官方拨号字段文档说明新版通过 domain_resolver 或 route.default_domain_resolver 指定节点域名的解析器，只有一个 DNS 服务器时存在省略条件。不要仅把 IP 换成域名就假定跨版本可用，也不要把处理目标域名的 DNS 规则误当作节点域名已正确解析。

有命令行核心的读者可以在运行前执行 sing-box check -c config.json 检查配置；它只检查本地配置能否被核心接受，不检查服务器是否可达。图形客户端内置核心与终端核心也可能不是同一个版本。

已取得真实参数、使用上面本地端口路线时，将完整 JSON 保存为 UTF-8 的 config.json。在该文件所在目录依次运行：

sing-box version
sing-box check -c config.json
sing-box run -c config.json

这些命令要求核心已能从终端找到。Windows 便携目录中把开头的 sing-box 改成 .\sing-box.exe；macOS/Linux 未加入 PATH 时使用实际可执行文件路径。检查报错就先修配置，不继续启动；检查通过后 run 会占用当前终端，另开一个终端执行下一节的 curl。测试结束回到运行窗口按 Ctrl+C，并还原此前手动设置的应用或系统代理。不要同时启动图形客户端的同端口服务；这一套只运行本地代理，不会自动修改系统代理或建立手机 VPN。

如何验证本地端口与实际出站

桌面使用 mixed 入站时，应用必须主动连接本地端口，或由系统代理把流量送入该端口。仅启动核心不会自动让所有程序经过它。

下面的命令是读者在自己的配置启动后执行的检查示例，2080 要改为真实监听端口。Windows 使用 curl.exe，macOS/Linux 使用 curl：

curl --proxy http://127.0.0.1:2080 --noproxy "" --max-time 15 -I https://example.com

收到目标站点的 HTTP 响应，说明这次经本地端口的请求得到了响应；具体是否出代理节点，要结合路由与日志确认。若规则选中 direct，即使命令成功也可能直连。连接被拒绝优先检查服务和端口，域名解析错误优先检查 DNS，TLS 错误则核对系统时间、节点参数与证书。

移动端使用 VPN/TUN 时以应用实际访问和连接日志验证。系统代理、TUN 和路由的区别可继续读代理模式详解，解析和分流的配合见DNS 与路由。

更新、备份与升级恢复

远程配置更新会重新获取来源内容，本地改动可能丢失。先确认客户端里哪一份是远程配置、哪一份是自己的本地副本；不要在唯一的远程原文中长期维护手工规则。

升级或大改之前，保存当前可用配置、来源地址、客户端与核心版本、策略组选项和额外规则。备份可能含服务器密码和订阅令牌，应存入受保护的位置。换设备时先在新设备上导入、启动和验证，再清理旧设备。

升级后失败时，先停止服务并保留出错原文，对照官方迁移文档检查字段变化；让提供方生成适配版本通常更稳妥。需要自行迁移时在副本中修改，每次只处理一类字段并重新校验。macOS 更换独立版或不同分发包时，也要核对官方迁移说明，不能默认配置目录相同。

出错时从哪一层查

现象	优先检查	下一步
下载远程配置失败	URL、令牌、网络、服务端响应	订阅更新失败
启动立即停止，出现 unknown field	格式与核心版本、废弃字段	读迁移文档或联系配置提供方
VPN 正常但网页不通	实际出站、节点、DNS、规则集下载	代理连接失败排查
桌面核心在运行但应用没流量	本地端口、系统代理或应用代理	系统代理不生效
停止后无法上网	VPN 按需连接、其他 VPN、代理设置残留	先停止自动重连，再恢复系统网络设置

已经能连接后，下一站是订阅导入、更新与备份；需要给手机或 Mac 配置同一账户，接着读手机与 Apple 设备教程。