Freecat 🐾自由猫 - 全球网络加速服务商

sing-box教程：从安装导入到 TUN、DNS 与连接排查

更新于 2026-10-24 · ziyoumao.online

简答：sing-box 教程的核心流程是：选对客户端，确认订阅格式，导入 JSON 配置后先校验，再按需启用系统代理或 TUN。遇到无网络时，优先检查配置结构、DNS、路由和权限。

定义：sing-box 是一个使用 JSON 配置、负责网络入站、出站、DNS 与路由处理的开源网络工具，图形客户端负责界面、权限和平台适配。

先做这一步：确认客户端、订阅格式和工作模式

sing-box 本身更接近网络内核与命令行程序，图形客户端负责配置管理、系统代理、TUN 和平台权限。官方客户端页面列出了 Android、Apple 平台、Windows 和 Linux 对应的客户端；Windows 与 Linux 使用 sing-box for Desktop，Apple 平台包含 iOS、macOS 和 Apple tvOS。下载入口应优先查看官方图形客户端说明，不要仅凭“支持 sing-box”字样判断第三方软件是否可靠。

如果你手里的是一条订阅链接，先不要直接改后缀或粘贴到任意转换页面。打开后可按内容初步判断：

看到的内容通常代表处理方式
以 { 开头，包含 inbounds、outbounds、routesing-box JSON 配置导入 sing-box 客户端或保存为 JSON 文件后校验
包含 proxies、proxy-groups、rules 等字段Clash 类 YAML 配置不能直接当作 sing-box JSON 使用，应使用客户端支持的导入方式或可靠转换流程
一长串字母数字，解码后才出现节点信息Base64 或其他订阅封装先确认服务提供方标注的客户端格式，再决定导入位置
只有一个节点 URI单节点链接确认客户端支持的协议类型，再通过添加节点或配置编辑器导入

最稳妥的判断标准是：sing-box 配置文件使用 JSON，顶层常见结构包括 log、dns、inbounds、outbounds、route 等，详见官方配置结构文档。订阅是否提供 sing-box 格式、是否需要转换以及更新地址，以订阅服务提供方官方说明为准。

按设备完成首次联网

Windows

  1. 从sing-box for Desktop 官方页面进入发布资产，选择与系统架构匹配的安装包。
  2. 首次打开客户端后，进入配置或 Profiles 页面，选择添加本地配置或远程配置；远程配置粘贴订阅地址，本地配置选择 JSON 文件。
  3. 先保存配置并执行客户端提供的校验或启动操作。确认配置列表中出现有效配置后，再打开系统代理或 TUN。
  4. 启用 TUN 时按 Windows 弹出的服务或网络权限提示操作。若启动失败，先关闭其他占用虚拟网卡、系统代理或 VPN 的程序，再重试。
  5. 访问一个普通网页，观察连接日志中是否出现命中的出站或策略；不要只看客户端显示“运行中”。

macOS

  1. 从官方客户端页面进入 Apple 平台或桌面客户端入口，选择适配 macOS 的版本。
  2. 首次启动时，如果系统在“隐私与安全性”中拦截应用，确认下载来源和文件签名后，在系统设置中允许打开，并按提示解除隔离。
  3. 添加本地 JSON 或远程配置，保存后先校验，再启动。
  4. 只需要浏览器或少数应用使用时，可先使用系统代理；需要接管更多应用流量时，再按客户端提示开启 TUN。
  5. 确认菜单栏状态、连接日志和出口 IP 均发生预期变化。

Linux

  1. 桌面用户可使用官方 Desktop 页面；命令行用户可按官方包管理器文档安装。Debian 或 Ubuntu 可执行：
sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://sing-box.app/gpg.key -o /etc/apt/keyrings/sagernet.asc
sudo chmod a+r /etc/apt/keyrings/sagernet.asc
printf '%s\n' 'Types: deb' 'URIs: https://deb.sagernet.org/' 'Suites: *' 'Components: *' 'Enabled: yes' 'Signed-By: /etc/apt/keyrings/sagernet.asc' | sudo tee /etc/apt/sources.list.d/sagernet.sources
sudo apt-get update
sudo apt-get install sing-box
  1. 将配置文件放入专用目录，例如 /etc/sing-box/，并限制配置文件权限，避免订阅凭据被普通用户读取。
  2. 使用专用服务用户运行更安全；服务由 systemd 管理时，可执行：
sudo systemctl enable sing-box
sudo systemctl start sing-box
sudo journalctl -u sing-box --output cat -e
  1. 若使用 TUN，检查当前用户或服务是否具备创建虚拟接口和调整路由的权限。Linux 上官方文档建议在 TUN 配合默认路由时考虑 auto_redirect，但它依赖系统网络栈和防火墙条件，不应在不了解现有 nftables 规则时直接复制复杂模板。

Android

  1. 从官方客户端页面进入 Android 客户端入口，安装对应应用。
  2. 添加本地 JSON 或远程配置，确认配置被保存后启动服务。
  3. Android 的 TUN 通常由系统 VPN 服务提供，首次启用会出现 VPN 授权提示；确认授权后再测试连接。
  4. 若只想让部分应用走代理，使用客户端提供的应用选择功能；若全部流量都需要接管，再选择全局 TUN 方式。

iOS

  1. 从官方 Apple 平台页面确认当前可用的分发渠道和客户端名称，安装后添加本地或远程配置。
  2. 首次启用 TUN 或 VPN 时，按系统提示添加 VPN 配置并输入设备密码确认。
  3. 启动后用 Safari 打开网页，同时查看客户端日志或连接状态。若系统没有弹出授权窗口，进入系统设置中的 VPN 或相关网络配置页面检查是否已有旧配置冲突。

不同平台的按钮名称可能随客户端版本变化，但“添加配置—保存—校验—启动—观察日志—确认出口”这一顺序相对稳定。

理解配置：inbounds、outbounds、route 和 DNS

inbounds 是流量进入 sing-box 的方式，常见有 mixed 和 tun。mixed 同时提供 SOCKS 与 HTTP 服务，适合只让支持代理的应用连接；tun 创建虚拟接口，适合接管系统流量。mixed 官方文档说明它支持 SOCKS4、SOCKS4a、SOCKS5 和 HTTP。

mixed 入站的端口由配置中的 listen_port 决定，没有适用于所有配置的通用默认值。排查端口时直接查看对应 inbound；如果客户端有设置页，也以设置页显示为准。不要把 Clash 客户端常见端口写成 sing-box 的固定端口。

outbounds 是流量离开的方式，例如直连、代理节点、选择器或 URLTest。route.rules 按顺序匹配域名、IP、协议或入站，route.final 指定没有命中规则时使用的出站；官方文档明确说明，final 为空时会使用第一个出站。Route 官方文档可核对字段含义。

URLTest 不是“测速保证”，而是客户端按配置的测试地址和周期在候选出站中进行选择。候选标签必须真实存在，否则校验或运行时会失败。URLTest 官方文档说明了候选出站、测试地址、间隔和容差字段。

DNS 建议先保持简单：确认系统能解析配置中使用的域名，再逐步加入分流。若 TUN 开启后出现网页打不开、只有 IP 能访问或本地域名失效，优先检查 DNS 服务器、DNS 规则和 TUN 的 DNS 模式。TUN 的 dns_mode 可影响系统 DNS 设置及 53 端口处理，详见TUN 官方文档。

命令行校验、启动与端口排查

命令行用户不要直接运行来源不明或结构不完整的示例。先准备一个包含至少一个可用出站的完整 JSON 文件，再按以下顺序执行：

sing-box format -w -c config.json -D config_directory
sing-box check -c config.json -D config_directory
sing-box run -c config.json -D config_directory

format 用于整理配置，check 用于检查结构和字段，run 才会真正启动。官方配置文档给出了 check、format 和 merge 的命令形式。示例中的 config_directory 应替换为实际目录；如果配置使用相对路径的规则集、证书或缓存文件，目录必须正确。

下载资产后，哈希校验对象是下载到本机的原始压缩包或安装包，不是解压后的二进制文件。GitHub Releases 的资产页面若提供 SHA256 摘要，可使用：

certutil -hashfile <下载文件> SHA256
shasum -a 256 <下载文件>
sha256sum <下载文件>

第一条适用于 Windows，第二条适用于 macOS，第三条适用于 Linux。将输出与发布页面给出的摘要逐字符比较；不一致时不要继续安装。

端口被占用时，先从配置中找出 listen 与 listen_port，再查询占用者：

sudo ss -lntup | grep ':<端口>'
lsof -nP -iTCP:<端口> -sTCP:LISTEN

Linux 使用带 sudo 的 ss，macOS 使用 lsof。如果占用者是旧的 sing-box 进程，先停止旧服务；如果是其他应用，改用未占用端口并同步修改客户端设置。

TUN、系统代理和 mixed：怎么选才不容易冲突

模式适用场景常见限制
系统代理浏览器、办公软件等明确支持 HTTP 或 SOCKS 的应用不支持代理的应用可能不生效；部分应用可能绕过系统代理
mixed 入站为其他应用提供一个本地 SOCKS/HTTP 代理入口需要手动填写地址和端口；端口以配置中的 listen_port 为准
TUN希望由虚拟网卡接管更多系统流量需要平台权限；可能与其他 VPN、虚拟网卡、防火墙规则冲突

Windows、macOS 和 Linux 的 TUN 支持方式不同。Linux 通常还涉及路由表、nftables 和服务权限；Windows 可能需要服务模式或管理员确认；macOS 需要系统网络扩展授权；Android 和 iOS 依赖系统 VPN 授权。遇到 TUN 无法启动时，先关闭其他 VPN，确认系统没有残留同类网络扩展，再检查日志。

Linux 上启用 auto_route 后，官方文档建议设置 route.auto_detect_interface 或指定默认接口，以避免 TUN 下出现路由环路。不要同时复制多个教程中的路由、DNS 和防火墙片段；每增加一个字段，都应重新执行 check 并记录变化。

升级、备份与回滚：先保留能工作的配置

  1. 升级前停止客户端或 systemd 服务。
  2. 备份配置目录，而不是只备份一个订阅链接。至少保留主 JSON、规则集、证书、远程配置缓存和客户端自定义设置。
  3. 复制一份当前可用配置，例如将 config.json 保存为带日期的备份文件；订阅地址属于敏感凭据，不要公开发布。
  4. 安装新版本后，先对备份配置执行 format 和 check，确认通过后再启动，不要直接覆盖唯一可用版本。
  5. 若启动失败，查看客户端日志或 Linux 的 journalctl -u sing-box，根据报错定位字段、权限、端口或规则集问题。
  6. 无法快速修复时，停止新版本，恢复原配置和上一份可用程序，再确认服务恢复后单独测试新配置。

官方发布页会区分稳定发布和预发布渠道。预发布版本可能包含配置字段变化，生产环境或跨境办公设备应优先选择稳定发布，并在升级前阅读对应发布说明。官方稳定版发布页可用于核对资产和发布说明；截至2026-10-24，Releases 标记为 Latest 的是 v1.14.3。

从症状排查 sing-box 连接问题

症状优先检查判定方法
导入成功但没有节点订阅格式、远程内容、客户端支持范围查看原始内容是否为 JSON；检查日志是否提示解析失败
配置解析失败JSON 括号、逗号、字段名、文件路径执行 sing-box check，按第一条报错修复
启动后完全无网络TUN 权限、route.final、默认出站和 DNS先关闭 TUN 测试 mixed 或系统代理，再查看连接日志
只有部分网站打不开DNS 分流、规则顺序、IPv6、MTU分别测试域名解析、IPv4/IPv6 和命中的路由策略
TUN 无法启动其他 VPN、虚拟网卡、系统权限停止冲突软件，重新授权，再查看平台日志
能连接但速度慢节点延迟、丢包、MTU、DNS 等待时间对比不同出站的日志和延迟，不把单次测试当作长期保证

判断流量是否真的经过预期路径，应看连接日志中命中的策略或出站，也可以在同一网络下对比出口 IP。仅看到客户端图标变绿，不能证明每个应用都使用了代理。

订阅链接和转换服务都可能包含访问凭据。不要把带令牌的完整链接粘贴到公开 Issue、截图或群聊；使用第三方转换服务前，先确认其是否会读取、保存或转发订阅内容。

常见问题

sing-box 是不是 Clash 或 Mihomo？

不是。它们是不同的项目和配置体系。sing-box 官方配置使用 JSON，Clash 类配置通常使用 YAML；客户端能否导入某种格式，要看客户端本身是否支持。遇到导入失败时，先识别格式，不要只修改文件扩展名。

sing-box 收费吗？

sing-box 是开源项目，软件本身与订阅服务不是同一件事。节点、订阅或网络服务的价格、状态和入口以相关服务商官方为准。

sing-box 的端口是不是固定值？

不是。mixed 入站的端口由配置中的 listen_port 决定；图形客户端可能提供设置页，但最终仍应以当前配置和设置页为准。端口冲突时使用系统命令确认实际占用者。

为什么配置通过 check，启动后仍然无法联网？

check 主要验证配置结构和字段，不能替代真实连接测试。启动后还要检查节点可达性、DNS、route 规则、TUN 权限、端口冲突和出口日志。

iPhone 能不能使用 sing-box？

官方客户端页面将 iOS 列在 Apple 平台范围内。安装渠道和可用版本会变化，应从官方 Apple 平台说明进入；首次启用通常还需要系统 VPN 配置授权。

订阅导入后要不要马上打开 TUN？

不建议。先用系统代理或 mixed 方式确认配置、节点和 DNS 工作正常，再开启 TUN。这样出现问题时，能更快区分是节点问题还是系统路由与权限问题。

常见问题

sing-box 是不是 Clash 或 Mihomo？

不是。sing-box 使用 JSON 配置，Clash 类配置通常是 YAML；能否互导取决于客户端和转换工具，不能只修改文件扩展名。

sing-box 收费吗？

sing-box 是开源项目，软件本身与订阅服务分开。订阅服务的价格、状态和入口以官方为准。

sing-box 的端口是不是固定值？

不是。mixed 入站端口由配置中的 listen_port 决定，实际端口以当前配置或客户端设置页为准。

为什么 check 通过后仍然无法联网？

check 主要验证结构和字段，不能替代真实连接测试。还需检查节点可达性、DNS、路由、TUN 权限、端口和连接日志。

iPhone 能不能使用 sing-box？

官方客户端页面将 iOS 列在 Apple 平台范围内。安装渠道和版本以官方 Apple 平台说明为准，首次使用还需系统 VPN 授权。

订阅导入后要不要马上打开 TUN？

不建议。先用系统代理或 mixed 验证节点、DNS 和日志，再开启 TUN，排查范围更小。

相关阅读

参考资料

  1. Graphical Clients · sing-box 官方图形客户端说明
  2. sing-box for Desktop · sing-box 官方桌面客户端说明
  3. Introduction · sing-box 官方配置结构文档
  4. Package Manager · sing-box 官方安装与 systemd 管理文档
  5. Mixed · sing-box 官方 mixed 入站文档
  6. Tun · sing-box 官方 TUN 入站文档
  7. Route · sing-box 官方路由文档
  8. URLTest · sing-box 官方 URLTest 出站文档
  9. Release 1.14.3 · SagerNet/sing-box 官方发布页
  10. sing-box versions · SagerNet 官方容器版本页