TAG官网 - TAG VPN套餐价格 | Bronze、Silver、Gold计划 - TAG Pro网络加速返回首页

sing-box 教程：导入后连不上？从安装到生效验证的完整步骤

更新于 2026-10-24 · tagss11.buzz

简答：sing-box 导入后连不上，先确认拿到的是合法 JSON，再按“加载配置→选择出站→开启系统代理或 TUN”启动。最后查看连接日志、规则命中和出口 IP，不能只看客户端显示运行。

定义：sing-box 是以 JSON 配置为基础的代理核心与跨平台图形客户端体系，核心程序、官方客户端和第三方 GUI 负责的功能并不相同。

30 秒速查：先判断你手里的内容能不能直接导入

如果你遇到“导入成功但连不上”，先不要修改 DNS、MTU 或规则。第一步确认输入格式，第二步确认配置能被解析，第三步才检查出站和系统接管。sing-box 的原生配置以 JSON 为基础，官方配置文档同时提供配置结构、检查和格式化说明，可先查看 sing-box Configuration Introduction。

sing-box 输入格式 30 秒速查
你拿到的内容能否直接作为原生配置下一步怎么做
远程 sing-box JSON可以，前提是 URL 返回合法 JSON在客户端新建远程配置，下载后查看解析结果
完整本地 JSON可以先复制备份，再用 sing-box check -c config.json 检查
Clash YAML不能直接当作 sing-box JSON使用客户端明确支持的转换功能，或向配置提供方索取 sing-box JSON
Base64 节点集合不是完整配置官方客户端是否支持这类导入，以客户端说明为准；不支持时索取 sing-box JSON
单节点分享链接不是完整配置官方客户端是否支持，以客户端说明为准；不支持时索取完整配置
登录页、错误页或普通网页不能使用先确认响应内容不是 HTML、403、404 或网关错误

不要把 YAML 文件改名为 .json，扩展名变化不会改变文件内容。Base64、单节点链接和远程网页也不能因为“看起来像订阅”就直接当成完整 JSON。订阅 URL 往往包含访问凭据，不建议粘贴到来源不明的在线转换站；不确定格式时，优先向提供方索取 sing-box 原生配置。

先选客户端，再按系统完成安装

本站是第三方使用指南站，不是 sing-box 官方站。sing-box 核心负责运行配置，图形客户端负责配置管理、系统代理、VPN 或 TUN 等平台功能。官方客户端总览列出的维护项目包括 Android 的 sing-box for Android、iOS/macOS/Apple tvOS 的 sing-box for Apple platforms，以及 Windows 和 Linux 使用的 sing-box for Desktop，详情见 Graphical Clients。

各系统的选择与首次检查点
系统优先路径首次启动重点
Windowssing-box for Desktop；需要命令行时再使用核心程序Windows 防火墙提示、TUN 服务模式、系统代理开关
macOSsing-box for Apple platforms；也可按官方说明选择独立版本“隐私与安全性”中的系统扩展或网络扩展放行
Linuxsing-box for Desktop 或命令行核心配置文件权限、专用用户、systemd 服务和 TUN 权限
Androidsing-box for AndroidVPN 授权、电池优化、TUN 和应用分流
iOS/iPadOSsing-box for Apple platforms“设置—VPN”中的配置状态和按需连接开关

Windows

图形客户端安装后，先确认配置已经加载，再按需要开启系统代理或 TUN。若使用 TUN，按系统提示允许服务、驱动或网络访问。需要命令行安装时，Windows 可使用官方发布资产或包管理器；不要把 Linux 的安装命令直接套用到 Windows。

macOS

首次使用独立版本时，如果系统阻止扩展或网络组件，打开“系统设置—隐私与安全性”查看放行提示。官方变更记录曾记录特定版本的 macOS 独立客户端需要额外权限才能启动，因此遇到“点击后无反应”时，应结合具体版本查看 sing-box Change Log，不要只重复安装。

Linux

Linux 可按官方安装文档选择 APT、DNF、手动安装或 Homebrew；Homebrew 适用于 macOS 和 Linux，Scoop 与 winget 则属于 Windows 生态，不要放到 Linux 命令中。使用 systemd 时，建议使用专用用户读取配置，并限制包含订阅凭据的文件权限。安装和服务管理方式见 Package Manager。

Android 与 iOS/iPadOS

Android 首次启动需要接受系统 VPN 授权，后台运行异常时检查电池优化。iOS/iPadOS 使用系统 VPN 配置授权，连接后查看“设置—VPN”的状态；如果按需连接未生效，先关闭按需开关进行手动连接对比。没有对应图形客户端的平台，不要把桌面核心程序直接当成移动端应用安装。

截至 2026-10-24，Releases 标记为 Latest 的是 v1.14.4；Alpha、Beta 或其他 Pre-release 渠道不作为新手默认选择。版本和发布渠道应以 sing-box Releases 页面为准。

路径一：导入远程订阅或远程 JSON

  1. 从配置提供方复制订阅 URL，先不要公开发布、截图或粘贴到在线格式化工具。URL 可能包含访问令牌，泄露后应按提供方流程更换。
  2. 在客户端中新建远程配置，粘贴 URL，设置容易识别的名称，并保存配置。
  3. 执行一次手动更新，随后查看预览或日志。重点确认返回内容是 JSON，而不是登录页、验证码页、403、404 或网关错误。
  4. 导入成功后检查出站列表、策略组和路由是否存在。看到配置被解析，只能说明文件格式基本可读，不代表节点连接已经成功。

如果浏览器打开订阅 URL 只显示网页，优先检查链接是否复制完整、是否需要登录、访问权限是否过期，以及服务端返回的内容类型。不要把网页保存后改名为 JSON。

官方客户端对 Base64 节点集合和单节点分享链接的支持情况，以各客户端说明为准；如果导入菜单没有对应选项，最稳妥的做法是向配置提供方索取 sing-box JSON，而不是把包含凭据的链接交给不明转换站。

路径二：导入本地 JSON、检查并备份

  1. 把原始文件复制到备份目录，保留一份未修改的原始配置，不要直接覆盖唯一副本。
  2. 使用核心检查配置：sing-box check -c config.json。如果系统提示找不到命令，改用核心程序所在目录执行，或先按官方安装文档配置 PATH。
  3. 需要统一缩进时，先复制文件，再使用 sing-box format -w -c config.json。格式化前保留原文件，方便回滚。
  4. 检查通过后导入图形客户端，查看日志中的字段错误、出站标签错误和路由引用错误。

如果提示 JSON 语法错误，依次检查引号、逗号、括号和文件编码。如果提示未知字段或字段类型不匹配，先确认配置要求的核心版本，再对照当前官方配置文档；不要把其他内核的字段直接复制进 sing-box。

建议保留三个副本：原始下载文件、脱敏备份文件、当前使用文件。分享前删除订阅令牌、密码、私钥、服务器地址和个人标识。示例备份名可以写成 config-backup-<版本号>.json，不要把真实凭据放入文件名、截图或日志。

启动顺序与模式：系统代理、TUN、Rule、Global、Direct

首次启动建议按“加载配置→选择出站→开启系统代理或 TUN”的顺序操作。这样可以把配置错误、节点错误和系统接管问题分开判断。系统代理只影响遵循系统 HTTP 或 SOCKS 设置的应用；TUN 通过系统 VPN 或虚拟网卡接管更多流量，但需要额外的系统权限。

  • 系统代理：适合先用浏览器等常规应用验证 HTTP 或 SOCKS 连接。
  • TUN：适合需要接管不遵循系统代理的应用；Windows 可能需要服务权限，macOS 需要网络扩展授权，Android 和 iOS/iPadOS 需要 VPN 授权，Linux 需要检查 TUN、路由和用户权限。
  • Rule：按规则把不同流量交给不同出站，前提是配置中确实声明了相应路由规则。
  • Global：把匹配到的流量统一交给指定代理出站，适合排查规则误判，但不代表节点一定可用。
  • Direct：让流量直连，适合对比本地网络、DNS 或目标服务是否本身可访问。

Rule、Global、Direct 并不是所有配置都会自动出现的通用开关。它们通常依赖配置中的 experimental.clash_api 以及路由规则对 clash_mode 的使用；没有这些配置时，客户端可能不会显示模式切换。相关前提见官方 Clash API 和 Route 文档。

Selector 适合手动固定一个出站；URLTest 适合按测试结果选择出站，但测试结果只代表指定测试地址和当时的网络条件。路由最终出口还要检查 route.final 是否指向已经声明的出站，策略组引用的标签也必须真实存在。

本地监听端口没有统一的 sing-box 默认值，应以配置文件中对应入站的 listen_port 或客户端显示为准。mixed、http、socks 等入站各自继承监听字段，具体字段说明见 Listen Fields 与 Inbound。

三阶段排错：导入失败、启动失败、运行但无法访问

第一阶段：配置导入失败

  1. 检查远程 URL 的返回内容，确认不是登录页、错误页或 HTML。
  2. 对本地文件运行 sing-box check -c config.json，先解决第一条 JSON 语法错误。
  3. 确认输入格式是否匹配。Clash YAML、Base64 和单节点链接不能直接当成完整 sing-box JSON。
  4. 检查配置版本和字段变化。未知字段、弃用字段或字段类型变化，都可能导致解析失败。

第二阶段：配置能导入但启动失败

  1. 先查看客户端日志，优先处理第一条明确错误，不要只看最后的“启动失败”。
  2. 检查出站标签、策略组标签和 route.final 是否互相匹配。
  3. 检查本地监听端口是否已经被其他程序占用，并以配置中的 listen_port 或客户端设置页为准。
  4. Linux 使用 systemd 时，可执行 sudo journalctl -u sing-box --output cat -e，并确认专用用户能读取配置、缓存和证书文件。
  5. Windows 检查 TUN 服务和防火墙提示；macOS 检查系统扩展或网络扩展放行；移动端重新确认 VPN 授权。

第三阶段：显示运行但访问失败

  1. 如果配置提供了模式切换，先用 Direct 对比本地网络，再用 Global 排查规则误判，最后回到 Rule；如果没有 Clash API 和对应路由规则，就不要寻找不存在的模式按钮。
  2. 查看连接日志中是否出现目标域名、命中的规则和最终出站。客户端显示“运行中”不能证明某个应用流量已经被接管。
  3. 对比客户端关闭和开启时的出口 IP。若出口没有变化，检查应用是否遵循系统代理、TUN 是否获得权限，以及日志中是否出现该应用连接。
  4. 如果只有域名解析失败，检查 DNS 配置、路由和系统网络，先不要同时修改 DNS、MTU、TUN 和节点。
  5. 若只有某个应用失败，检查它是否使用独立代理、QUIC、应用内 DNS 或自身网络栈，再结合日志确认是否命中预期规则。

判断“连接成功”至少需要同时看到：配置无解析错误、核心已启动、连接日志出现实际出站、目标流量命中规则，以及开启前后出口 IP 或访问结果存在可解释变化。

常见问题

下面的问题集中在新手最容易误判的格式、模式、端口和平台差异。

常见问题

sing-box 能直接导入 Clash YAML 吗？

不能把 Clash YAML 直接当成 sing-box 原生 JSON 使用。应使用客户端明确提供的转换功能，或向配置提供方索取 sing-box JSON；转换后仍要检查出站、策略组和路由标签。

sing-box 的本地代理端口默认是多少？

sing-box 没有统一的本地代理端口默认值，端口由配置中 mixed、http 或 socks 入站的 listen_port 决定，也可能由客户端界面生成。请以配置文件或客户端显示为准，不要照搬其他客户端端口。

为什么客户端显示运行，浏览器却仍然直连？

先确认系统代理已开启，并查看配置中对应入站的 listen_port；随后检查连接日志中是否出现浏览器请求，再对比客户端关闭和开启时的出口 IP。若日志没有请求，继续检查浏览器自身代理、QUIC 或 TUN 权限。

Rule、Global、Direct 模式为什么找不到？

这些模式不是所有配置都会自动提供，通常需要 experimental.clash_api 以及路由规则中的 clash_mode 配合。没有相关配置时，客户端不显示模式切换是正常现象，应直接检查 route 规则和最终出站。

TUN 开启后没有网络，应该先改 MTU 吗？

不应先改 MTU。先检查系统 VPN 或 TUN 权限、默认路由、DNS、日志中的出站和是否存在路由环路，确认基础链路正常后再一次只修改一个 MTU 参数。

Selector 和 URLTest 应该怎么选？

需要手动固定节点时使用 Selector；希望按测试结果自动选择时使用 URLTest。URLTest 只反映测试地址和测试条件，仍需结合目标应用的连接日志和实际访问结果判断。

Windows、macOS、Linux、Android 和 iOS 的配置文件能通用吗？

完整 JSON 在字段和出站兼容时可以复用，但各平台的 TUN、系统代理、VPN 权限和网络扩展实现不同。导入后应按平台重新检查权限、路由、DNS 和日志。

相关阅读

参考资料

  1. Graphical Clients — sing-box 官方图形客户端总览
  2. sing-box for Desktop — Windows 与 Linux 官方桌面客户端
  3. sing-box for Android — Android 官方客户端
  4. Configuration Introduction — sing-box 配置结构与检查格式化
  5. Package Manager — sing-box 官方安装与服务管理
  6. SagerNet/sing-box Releases — 稳定版与预发布版本
  7. Change Log — sing-box 官方变更记录
  8. Clash API — sing-box 官方模式与 API 配置说明
  9. Route — sing-box 官方路由配置说明
  10. Listen Fields — sing-box 官方监听地址与端口字段
  11. Inbound — sing-box 官方入站配置说明