sing-box 客户端怎么用？从导入配置到连接排查的完整步骤
简答：sing-box 客户端的最短使用流程是：选择对应平台客户端，准备返回 sing-box JSON 的远程配置或本地 JSON 文件，导入配置后选择出站节点并启动服务。Clash YAML 或通用 Base64 内容不能直接当作 sing-box 远程配置使用。Android、Apple、Windows 和 Linux 的菜单名称可能随版本变化，操作时以当前客户端界面和官方发布页为准。
定义：sing-box 客户端是用来管理并运行 sing-box 配置文件的图形界面程序，本身不会自动提供节点、订阅或网络服务。
先判断客户端、配置格式和平台权限
sing-box 是一个通用代理平台，客户端负责管理配置、启动服务和调用系统网络能力。官方客户端页面列出 Android、Apple 平台、Windows 和 Linux 的对应客户端；其中 Windows 和 Linux 使用 sing-box for Desktop 时，当前官方资料将其标注为实验性客户端，具体发布状态和安装包应以官方客户端页面及当前仓库说明为准。
| 你手里的内容 | 如何识别 | 能否直接作为 sing-box 配置 |
|---|---|---|
| sing-box JSON | 通常以 { 开头，可能包含 inbounds、outbounds、route 等字段 | 可以，远程链接应返回 JSON 内容，本地文件应是有效 JSON |
| Clash YAML | 常见字段包括 proxies:、proxy-groups:、rules: | 不能直接当作 sing-box JSON 导入，需要使用兼容的转换方式并先检查凭据泄露风险 |
| 通用 Base64 或节点链接集合 | 可能是一长串无明显 JSON 结构的字符，解码后出现 vmess://、ss:// 等内容 | 不能直接作为远程 sing-box JSON 使用，需要配置提供方提供 sing-box 格式，或自行整理为合法 JSON |
官方文档明确说明 sing-box 配置文件使用 JSON，并提供 sing-box check 检查配置的命令。不要把完整订阅链接、访问密钥或带身份信息的配置粘贴到公开论坛、截图或第三方转换页面。
最快检查：先用文本编辑器打开本地文件，确认不是 YAML；如果是远程链接，使用浏览器或命令行查看返回内容是否为 JSON。若链接返回登录页、错误页或一段非 JSON 文本，客户端导入失败并不一定是客户端故障。
按设备完成 sing-box 配置导入和启动
Android：导入远程 sing-box JSON 配置
- 安装官方页面列出的 sing-box for Android。官方资料显示，SFA 可管理并运行本地或远程 sing-box 配置文件，系统要求为 Android 5.0 或更高版本。
- 打开客户端的配置或 Profiles 管理区域，选择新增远程配置；不同版本的菜单名称可能不同，以当前界面为准。
- 在 URL 输入框粘贴返回 sing-box JSON 的远程配置链接，不要直接粘贴 Clash YAML、通用 Base64 或单条节点链接。
- 保存后执行更新或刷新，确认配置内容能够显示，并在出站选择器中选择一个可用节点或节点组。
- 返回主界面启动服务。首次使用 TUN 或 VPN 模式时，按 Android 系统提示允许 VPN 权限；如果只使用系统代理模式，则还要确认目标应用是否读取系统代理。
Android 客户端的官方说明见sing-box for Android 文档。如果你拿到的是其他格式，先让配置提供方提供 sing-box JSON，而不是反复修改 URL 后缀。
iOS 和 macOS：使用 Apple 平台客户端
- 从官方客户端页面进入 Apple 平台客户端资料，确认当前安装来源和平台版本。
- 在客户端的 Profiles 或配置管理区域新增 Remote Profile，填写配置名称和远程 URL；官方通用文档将 Remote Profile 定义为以 URL 作为更新来源的远程 sing-box 配置。
- 保存后手动更新一次，检查配置内容是否能够查看；如果远程链接返回的不是 JSON，先处理格式问题。
- 选择配置中的出站节点或节点组，然后启动服务。iOS、macOS 的网络扩展或 TUN 能力由系统授权管理，首次启动时按系统提示允许。
- 停止服务时，先在客户端关闭运行状态，再检查系统 VPN 或网络扩展开关是否已经回到关闭状态。
Apple 平台支持通过 NetworkExtension 运行客户端功能，官方功能说明也记录了 TUN 和服务权限的实现边界；因此某个配置字段在不同 Apple 平台上不可用时，应以客户端支持表和日志为准，而不是照搬其他平台配置。
参考：官方图形客户端通用配置说明、Apple 平台功能与 TUN 说明。
Windows 和 Linux：优先确认客户端性质和运行方式
- 先从官方客户端页面确认当前 Windows 或 Linux 的 sing-box for Desktop 发布状态。官方 GitHub 组织页面目前将 sing-box for Desktop 描述为实验性 Windows 客户端，Linux 支持也列在官方图形客户端表中。
- 安装后打开配置管理区域，选择本地配置或远程配置。远程 URL 必须返回 sing-box JSON，不能把 Clash 或 Base64 订阅直接粘贴进去。
- 更新配置，查看解析结果，再选择出站节点或节点组。
- 先使用系统代理模式验证配置是否能工作；需要接管不读取系统代理的应用时，再考虑 TUN。启动 TUN 可能需要终端管理员权限、虚拟网卡或系统网络授权。
- 如果电脑上同时运行其他 VPN、代理软件或虚拟网卡工具，先关闭不需要的服务，再启动 sing-box，避免多个 TUN 或路由同时接管流量。
官方 GitHub 组织页面可用于核对项目归属和当前仓库描述：SagerNet 官方组织页面。版本号、安装包名称和菜单文案会变化，本文不把某个未核实版本号当作固定要求。
启动后按五个阶段排查，不要直接重装
1. 导入失败：先检查链接和内容
- 检查方法：在浏览器打开远程 URL，或使用命令行查看响应头和正文；确认返回的是 JSON，而不是登录页、HTML 错误页或空内容。
- 判断：如果浏览器显示 401、403、404、过期提示或网页 HTML，问题更可能在链接权限、链接状态或服务端返回格式。
- 处理：重新复制完整 URL，避免多复制空格和标点；如果链接含密钥，不要公开粘贴，必要时重置链接后再导入。
2. 配置解析失败：看第一条错误和字段版本
- 检查方法：查看客户端日志，复制第一条具体错误；本地配置可使用
sing-box check检查。 - 判断：出现 JSON syntax、unknown field、invalid type 等提示时，通常表示 JSON 结构、字段名称、字段类型或客户端核心版本不匹配。
- 处理：先恢复到配置提供方的原始文件，不要凭记忆删除字段；对照官方配置结构和当前版本文档逐项核对。
3. 无法启动：区分权限、端口和虚拟网卡
- 检查方法：确认服务模式是否已开启；Windows 可用
netstat -ano查看端口占用，Linux 或 macOS 可用lsof -i辅助检查。 - 判断：如果提示端口已被占用，可能是旧进程或另一个代理软件占用；如果提示 TUN、网卡或权限错误，可能是系统授权不足或虚拟网卡冲突。
- 处理：先停止旧进程和其他 VPN/TUN 软件，再重新启动；需要提权时使用终端管理员运行，不要长期给来源不明的程序高权限。
4. 启动后无网络：先验证代理路径
- 检查方法：确认客户端状态为运行，检查系统代理是否指向客户端监听端口；Windows 可用
Test-NetConnection 目标地址 -Port 端口检查 TCP 连通性。 - 判断：客户端显示运行但浏览器无网络，可能是系统代理未生效、节点不可用、DNS 配置异常或 TUN 路由未建立。
- 处理：先切换到配置中的其他节点，暂时关闭 TUN 用系统代理测试；若系统代理可用而 TUN 不可用，再集中检查权限、虚拟网卡和路由。
不要只用 ping 判断代理是否可用。TUN 场景下，ICMP 结果可能不能代表 TCP 应用流量，应该结合浏览器访问和 TCP 测试。
5. 部分网站打不开：检查规则、DNS 和节点
- 检查方法：分别测试直连、代理和其他节点；使用
nslookup 域名查看 DNS 返回，并观察日志中是否出现 DNS、rule 或 timeout 错误。 - 判断：只有部分域名失败时，可能是分流规则、DNS 解析、IPv6 路由或某个节点不支持目标连接。
- 处理：先临时切换规则模式或节点验证范围，再恢复原规则；不要一次同时改 DNS、MTU、路由和节点，否则难以判断是哪一步产生影响。
配置更新、节点选择和备份怎么做
远程配置的好处是客户端可以从 URL 更新配置，但更新成功不等于节点一定可用。官方通用客户端说明中，Remote Profile 以 URL 作为更新来源，并支持自动更新；文档列出的默认自动更新间隔为 60 分钟，具体客户端是否提供开关、名称和时间选项，以当前界面为准。
- 先备份：在更新前导出或复制当前可用配置，至少保留配置文件、远程 URL 和必要的授权信息。
- 再更新：手动执行一次更新，确认更新时间和配置内容发生变化；不要只看“更新成功”提示。
- 后选节点：优先选择日志中握手成功、TCP 测试稳定且目标应用能正常访问的节点。单看延迟不能代表网页、办公软件或长连接表现。
- 最后启动：先用系统代理验证，再按需要启用 TUN。TUN 与系统代理是不同接管方式，同时开启多个网络接管工具可能造成冲突。
如果升级客户端后出现 unknown field 或启动失败，先保留旧配置和日志，确认是核心版本变化还是配置内容变化，再决定回滚。官方配置文档提供了检查和格式化命令，适合在修改 JSON 前先做语法验证。
常见问题 FAQ
sing-box 客户端本身会提供节点吗？
不会。客户端和 sing-box 核心负责读取配置、运行协议和管理网络连接；你仍需要合法、可用且格式匹配的远程配置或本地 JSON。没有配置时，客户端不会自动生成可用节点。
Clash 订阅能不能直接导入 sing-box？
不能默认认为可以。Clash YAML 与 sing-box JSON 不是同一种配置格式，通用 Base64 也不是 sing-box JSON。先检查返回内容，要求配置提供方提供返回 sing-box JSON 的远程配置链接，或使用经过审慎评估的转换方式。
为什么导入 URL 后显示解析失败？
可能原因包括 URL 返回 HTML 错误页、权限失效、内容不是 JSON、JSON 语法错误、字段已变更或客户端核心版本不匹配。先在浏览器查看返回内容，再查看客户端第一条日志，不要直接重复导入。
TUN 模式和系统代理模式有什么区别？
系统代理主要依赖应用读取系统代理设置；TUN 通过虚拟网络接口接管更广泛的流量，但通常涉及 VPN、网络扩展、虚拟网卡或管理员权限。排查时建议先用系统代理确认配置和节点，再单独测试 TUN。
Android 或 Apple 上启动后仍然无法联网怎么办？
先确认系统 VPN 或网络扩展权限已允许，配置状态为运行，并且出站节点不是 Direct 或 Block。随后切换节点、检查日志和 DNS；如果只有 TUN 失败，先关闭 TUN 改用系统代理或应用内测试，以区分节点问题和系统接管问题。
远程配置链接可以发给别人帮忙排查吗？
不建议。订阅链接可能包含身份标识、访问密钥或账户权限。排查时应打码域名路径中的凭据，只提供错误类型、客户端平台和不含敏感信息的日志片段。
常见问题
sing-box 客户端本身会提供节点吗？
不会。客户端和 sing-box 核心负责读取配置并运行连接，你需要另外准备合法、可用且格式匹配的本地 JSON 或远程配置。
Clash 订阅能不能直接导入 sing-box？
不能默认认为可以。Clash YAML、通用 Base64 和 sing-box JSON 不是同一种格式，导入前应检查远程链接实际返回的内容。
为什么远程配置 URL 导入后解析失败？
可能是返回 HTML、权限失效、内容不是 JSON、JSON 语法错误、字段变更或客户端核心版本不匹配。先查看返回内容和第一条日志。
TUN 模式和系统代理模式怎么选？
建议先用系统代理验证配置和节点，再测试 TUN。TUN 涉及更广泛的流量接管，可能需要 VPN、网络扩展、虚拟网卡或管理员权限。
远程配置链接能不能发给别人排查？
不建议。订阅链接可能包含身份标识或访问密钥，应打码处理，只分享不含敏感信息的错误日志。