冲上云霄网络加速 - VPNPN

sing-box 使用指南：全平台安装、订阅导入与连接排错

更新于 2026-11-02 · vpnpn.shop

简答：sing-box 新手最稳妥的顺序是：先确认平台对应的客户端，再识别订阅格式，导入后用普通模式验证，最后按日志排查 DNS、TUN、路由和端口问题。Android、Apple 平台、Windows 与 Linux 的官方客户端入口不同，版本和菜单也可能变化，本文把“安装—导入—启动—验证—回退”拆成可执行步骤。

定义：sing-box 是一个使用 JSON 配置、可通过图形客户端或命令行核心管理网络连接的平台。

先看速查卡：卡住时先做哪一步

如果你只是想先连起来，不要一开始就修改 DNS、TUN 或大量路由规则。先按“平台—格式—导入—普通模式—日志”的顺序缩小问题范围。

现象或目标先做什么成功标准失败回退
不知道下载哪个程序打开官方图形客户端列表，按系统选择入口客户端名称和平台相符停止从不明下载页安装修改版
手里有订阅 URL先确认返回内容是 sing-box JSON、其他格式还是编码文本客户端能解析并显示配置或节点向配置提供方索取明确的 sing-box 格式
手里有本地 JSON用当前核心执行 sing-box check没有字段、路径或版本错误备份原文件后按报错逐项处理
配置能启动但无法上网先关闭 TUN，用普通代理或系统代理测试基础网页和 DNS 能正常访问再检查 DNS、route、outbound 和权限
想让所有应用都接管确认 TUN、系统权限、虚拟网卡和其他 VPN 状态目标应用能访问且日志无循环或冲突先恢复普通模式，避免同时开启多个接管工具

官方客户端列表目前将 Android、iOS、macOS、Apple tvOS、Windows 和 Linux 分别对应到 Android、Apple platforms 或 Desktop 客户端；Linux 也可以使用命令行核心。具体入口和支持范围应以打开页面时的内容为准。

sing-box 是什么：客户端、核心和配置怎么分工

可以把 sing-box 分成三层理解：图形客户端负责界面、配置管理和系统权限；命令行核心负责读取配置并运行连接；配置文件负责描述入站、出站、DNS 和路由。官方文档说明 sing-box 使用 JSON 配置，并提供配置结构和 JSON Schema。

  • inbounds：定义本机如何接收应用流量，例如本地代理端口或 TUN。
  • outbounds：定义流量如何出去，例如直连、节点或选择器。
  • dns：定义域名解析方式和 DNS 请求路径。
  • route：根据域名、地址、应用等条件选择 outbound。
  • log：记录启动、DNS、路由和连接错误，排错时应优先查看。

参考官方配置说明和官方 JSON Schema 文档时，要注意配置字段会随核心版本变化。不能因为文件能被打开，就断定它一定能连接；还要确认节点、DNS、权限和路由都匹配。

订阅格式识别：JSON、YAML、Base64 怎么区分

订阅 URL 不能只看文件后缀判断格式。需要在客户端导入前，先确认提供方声明的输出类型；如果必须本地检查，尽量使用客户端或本地工具，不要把含令牌的 URL 粘贴到在线转换站。

可能格式常见内容特征能否直接当作 sing-box 配置不能导入时应确认什么
sing-box JSON通常以 { 开头，包含 inbounds、outbounds、route 等结构在客户端和核心支持时可以尝试确认 JSON Schema、核心版本和是否包含可用 outbound
Clash YAML常见为带缩进的键值结构，使用冒号和列表，不是 JSON 花括号结构不要默认可以直接导入向提供方索取 sing-box 原生输出，或确认客户端是否明确支持该格式
Base64 或其他编码文本内容看起来像连续的字母、数字、加号、斜线和等号，通常不能直接阅读不能仅凭外观判断确认编码规则、解码后格式及其授权范围
网页或错误响应返回登录页、HTML、JSON 错误对象或权限提示不能作为配置导入检查 URL 是否过期、账户权限、请求限制和服务方说明

响应头中的 Content-Type 可以作为线索，但不能单独作为兼容性证明。最可靠的判断是：提供方明确说明格式，客户端成功解析，且当前核心通过配置校验。

五个平台怎么用：安装来源、导入、权限与验证

下面的步骤故意不绑定某个具体版本的菜单名称。客户端更新后，按钮可能从“配置”“Profiles”“远程配置”改成其他名称；如果页面名称不同，应按功能含义寻找，不要为了对照教程强行修改配置。

Android

  1. 从官方 Android 客户端页面确认下载入口；官方页面列出 Play Store、GitHub Releases 和 F-Droid 等入口，并给出系统要求。
  2. 打开客户端的配置管理区域，选择远程 URL 或本地 JSON 文件导入。
  3. 首次启用时允许系统 VPN 权限；如果需要全设备或按应用接管，再确认 TUN 和应用包含、排除设置。
  4. 先选择配置中的节点或 outbound，关闭不必要的覆写，启动后测试网页和 DNS。
  5. 若普通连接正常而 TUN 失败，检查 Android VPN 权限、电池限制、其他 VPN 应用和应用分流。

官方 Android 功能说明指出，图形客户端在需要 TUN 时可通过 Android VpnService 运行，并提供按应用代理或绕过的能力；具体可用字段仍应以当前客户端和核心为准。

iOS 与 macOS

  1. 从官方 Apple 平台页面确认 App Store、TestFlight 或 macOS standalone 入口。
  2. iOS 导入远程或本地配置后，按系统提示允许 VPN 配置；macOS 需要区分商店版本和 standalone 版本，下载前先核对当前说明。
  3. 启动前先关闭其他 VPN 或网络接管工具，避免系统扩展、端口和路由互相影响。
  4. 先用基础模式验证配置，再根据需要启用 TUN 或系统代理相关能力。
  5. 如果商店状态、账号要求或版本能力与旧教程不同，以官方页面打开时的实际内容为准。

官方 Apple 页面列出了系统要求、下载渠道以及 standalone 版本信息；部分下载和商店使用条件可能随地区或账号状态变化，因此不要把旧文章中的商店名称当成永久结论。

Windows

  1. 从官方 Desktop 文档或官方发布页核对 Windows 对应的安装资产。
  2. 安装后先打开配置管理区域，导入远程配置或本地 JSON。
  3. 普通模式验证成功后，再按客户端提示授予 TUN 或系统代理权限。
  4. 检查 Windows 系统代理是否与其他客户端重复设置，并确认本地监听端口没有被占用。
  5. 验证网页、DNS 和目标应用；若只有部分应用失败，记录应用名称和日志，不要立即更换全部节点。

Linux

  1. 桌面用户先核对 Desktop 版本；服务器或自动化环境可按官方安装与包管理说明选择发行版包、Homebrew 或其他官方列出的方式。
  2. 把配置放入单独目录，备份原文件，并确认核心实际版本：sing-box version。
  3. 先校验配置，再运行；需要长期运行时，再考虑 systemd 服务和日志管理。
  4. 启用 TUN 前确认权限、路由、nftables 或其他防火墙规则，避免与 Docker、虚拟机和其他网络工具冲突。
  5. 用网页、DNS、应用访问和日志四项结果确认是否真正生效。

最小 JSON 配置示例：用于理解结构，不是现成节点配置

下面是一个结构示例，用于帮助新手理解 log、inbounds、outbounds 和 route 的关系。它只有本地混合代理入口和直连出口，不包含任何远程节点，因此不能代替服务方提供的节点配置；字段是否适用于你的核心，仍应以当前 Schema 和 check 结果为准。

{
  "$schema": "https://sing-box.sagernet.org/schema.json",
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "final": "direct"
  }
}
  • log：控制日志级别，排错时建议保留足够信息。
  • inbounds：这里创建本机监听的 mixed 入口，供支持 HTTP 或 SOCKS 代理的应用使用。
  • outbounds：这里只放 direct，表示直接连接；真实节点需要由配置提供方给出对应结构。
  • route.final：没有命中更具体规则时，使用哪个出口。

如果你把示例保存为 config.json，先执行当前版本支持的校验命令，不要直接启动：

sing-box check -c config.json

若输出字段错误、未知类型或版本不兼容，先运行 sing-box help，再查看当前官方配置文档。示例中的命令、字段和菜单不能视为所有版本、平台和客户端完全一致。

命令行闭环：校验、格式化、运行和日志

命令行用户建议采用“版本确认—备份—校验—运行—看日志”的顺序。官方配置文档给出了 check、format 等命令，但具体参数应以当前二进制的帮助输出为准。

  1. 确认核心：sing-box version，记录版本和系统架构。
  2. 校验配置：sing-box check -c config.json，先处理字段、路径、证书和引用文件错误。
  3. 格式化前备份：cp config.json config.json.bak，再按当前帮助确认是否使用 format。
  4. 运行：sing-box run -c config.json，观察启动日志和监听端口。
  5. 长期服务：Linux systemd 的启停和日志命令参考官方安装说明，不要把服务管理命令直接套到没有 systemd 的环境。

如果配置依赖相对路径资源、证书或规则集，要确认工作目录和配置目录一致。需要生成与当前二进制匹配的 JSON Schema 时，官方页面给出了 sing-box schema -o schema.json；该命令也应先用 sing-box help核对。

连接排错决策树：按第一处失败的位置处理

  1. 第一步：配置校验失败。重点查 JSON 括号、字段拼写、字段是否属于当前核心、证书和规则集路径是否存在。不要直接删除看不懂的字段；先备份并查当前官方文档。
  2. 第二步：配置能启动，但普通模式也无法连接。确认 outbound 是否存在、节点凭据是否完整、远程配置是否过期，再查看日志中的连接和 TLS 错误。不要先把所有 DNS 和路由改一遍。
  3. 第三步：普通模式可用，TUN 无法使用。检查系统 VPN 或网络扩展权限、虚拟网卡、管理员权限、其他 VPN、端口和路由冲突。Linux 还要检查防火墙规则及 TUN 所需权限；官方 TUN 文档列出了不同平台和版本的字段变化。
  4. 第四步：IP 可访问，域名打不开。重点检查 dns、DNS 路由、DNS 劫持模式和 IPv4/IPv6 结果。先记录一个失败域名和日志时间，再做单项修改。
  5. 第五步：只有部分应用或网站失败。检查 route 规则、应用分流、目标 outbound、IPv6 和应用自身代理设置。部分失败不能直接证明线路不可用。
  6. 第六步：启动时报端口占用。查看是否已有 sing-box、其他客户端、开发服务或系统代理监听相同端口；停止重复进程或更换端口后重新执行校验。

官方 TUN 文档记录了 auto_route、auto_redirect、DNS 模式和版本变化。尤其是 TUN 字段可能随核心版本演进，排错时应以当前文档和实际 check 输出为准。

版本、来源和订阅安全：发布前必须核对的事项

  • 版本：本文核验时间为 2026-11-02。官方发布页当前可见 1.14.4 与 1.15.0-alpha.13；这只能代表页面当前显示内容，不能证明 1.15.0 正式版已经发布。安装当天请重新打开官方发布页确认稳定、预发布和下载资产。
  • 客户端下载：优先从官方客户端列表、官方文档或官方发布页进入，不要根据搜索结果中的相似名称判断归属。
  • 格式与版本：订阅生成版本、客户端版本和命令行核心版本可能不一致；导入失败时先确认格式和版本，再考虑配置迁移。
  • 令牌保护：订阅 URL、访问令牌、证书和私钥都应视为敏感信息。不要粘贴到第三方网页、在线转换站、公开工单或群聊。
  • 修改与回退：编辑前备份；删除或重置客户端配置可能影响关联设置，必须按系统提示和当前客户端说明操作。

官方发布页的页面状态会变化，本文不把预发布版本当作正式版，也不承诺某个版本长期可用。发现当前页面与本文不同，应以当前页面、客户端提示和 sing-box check 结果为准。

常见问题

sing-box 能直接导入所有订阅链接吗？

不能直接假定。订阅可能返回 sing-box JSON、其他客户端格式、编码文本或错误页面。先确认提供方声明的输出格式，再看当前客户端是否支持；无法互相印证格式、账户和来源时，不要继续导入。

Clash YAML 或 Base64 订阅能不能直接使用？

不能一概而论。YAML 和 Base64 都不等于 sing-box 原生 JSON。应向提供方索取明确的 sing-box 输出，或确认当前客户端是否明确支持该格式；不要把含令牌的链接交给不可信转换站。

为什么配置导入成功，启动后却无法上网？

导入成功只说明文件被读取，不代表节点、DNS、路由、权限和网络环境都正常。先关闭 TUN，用普通模式验证，再根据日志检查 outbound、DNS、route、端口和其他 VPN 冲突。

要不要一开始就开启 TUN？

通常不建议。先确认普通模式和基础配置可用，再根据全设备接管需求开启 TUN，并检查系统权限、虚拟网卡、路由和其他网络工具。

最小 JSON 示例能直接连接吗？

不能。本文示例只有本地入口和直连出口，用来理解配置结构和执行校验；它没有远程节点、认证信息或订阅内容，不能替代可用的节点配置。

升级后配置报错怎么办？

先保存原配置和旧核心版本，执行当前核心的 check，再根据当前官方迁移说明逐项处理。不要把旧教程中的 TUN、DNS 或路由字段直接复制到新版本。

Linux 应该用 Desktop 还是命令行核心？

桌面用户可先核对官方 Desktop 的系统要求和安装入口；服务器或自动化环境通常更适合命令行核心与系统服务。两者都要以当前系统架构、安装包和官方说明为准。

常见问题

sing-box 能直接导入所有订阅链接吗？

不能直接假定。必须先确认订阅返回格式、客户端支持范围和核心版本；无法确认时不要继续导入。

Clash YAML 或 Base64 订阅能直接使用吗？

不能一概而论。先向提供方索取 sing-box 原生格式，或确认当前客户端明确支持该格式，不要使用不可信在线转换站。

为什么导入成功却无法上网？

导入成功只代表文件被读取，还要检查 outbound、DNS、route、TUN 权限、端口和其他 VPN 冲突。

要不要一开始就开启 TUN？

不建议。先用普通模式确认配置和连接可用，再按全设备接管需求启用 TUN。

升级后配置报错怎么办？

备份原配置并记录旧核心版本，执行当前核心的 check，再按官方迁移说明逐项修正字段。

相关阅读

参考资料

  1. sing-box 官方图形客户端列表
  2. sing-box for Android 官方页面
  3. sing-box for Apple platforms 官方页面
  4. sing-box for Desktop 官方说明
  5. sing-box 官方配置结构、check 与 format 文档
  6. sing-box 官方 JSON Schema 文档
  7. sing-box 官方 TUN 配置与版本变化说明
  8. sing-box 官方安装与包管理说明
  9. sing-box 官方 GitHub 发布页