缥缈墟 - 发布页

sing-box 安装教程：先分清核心还是客户端，附各平台验证与排查

更新于 2026-10-24 · piaomiaoxu.site

简答：sing-box 安装的关键不是先下载文件，而是先判断用途：Windows、Linux 桌面和手机优先选图形客户端，Linux 服务器再安装核心程序。安装后先运行 version，使用配置时再运行 check，并按系统架构、权限和端口逐项排查。

定义：sing-box 是使用 JSON 配置的网络连接核心程序，同时提供 Android、Apple 平台以及 Windows、Linux 桌面图形客户端。

先试这一步：核心程序还是图形客户端？

如果你只是想在电脑或手机上导入配置、切换连接和使用 TUN，优先选择官方图形客户端；如果需要在 Linux 服务器、路由设备或容器中长期运行，才安装命令行核心。官方客户端总览把 Android、iOS/macOS/Apple tvOS、Windows 和 Linux 分为对应客户端，核心程序则按系统包、压缩包或脚本安装。

截至2026年10月24日，Releases 标记为 Latest 的是 v1.14.3；后续安装应以官方 Releases 页面当时的 Latest 标记为准，Pre-release 或 Alpha 不应与稳定发布混用。相关信息可查看官方 Releases 页面和官方图形客户端总览。

你的用途应选择的对象安装后先做什么
Windows 或 Linux 桌面，需要界面管理配置sing-box for Desktop打开客户端，导入配置并查看连接日志
macOS 桌面，需要图形界面或 TUNsing-box for Apple platforms 的 macOS 独立版本按系统提示放行网络扩展，再加载配置
Android 手机或平板sing-box for Android导入配置并接受 Android VPN 权限
iPhone、iPad 或 Apple tvOSsing-box for Apple platforms从官方列出的应用渠道安装
Linux 服务器、自动启动或自定义路由sing-box 核心程序运行 sing-box version，再检查 JSON

三行结论：桌面或手机先选图形客户端；Linux 服务器选择核心并按需使用 systemd；安装完成后先跑 sing-box version，有配置时再跑 sing-box check。

本文是缥缈墟的第三方使用指南，不是 sing-box 官方页面；下载入口、系统要求和分发方式应以官方页面为准。

Releases 文件名速查：先看系统，再看 CPU 架构

下载资产时，不要只看文件名中的项目名称。先确认操作系统，再确认 CPU 架构；同一个系统可能同时提供多个架构文件。官方 Desktop 页面明确列出 Windows 支持 x64、x86、arm64，Linux 支持 x64、arm64、armv7l；桌面客户端下载入口指向官方 Releases。

文件形式或后缀通常适合的场景选择时注意
.zipWindows 便携式程序或压缩包解压后直接运行，适合不想写入系统安装目录的用户
.tar.gzLinux 或 macOS 命令行核心先看文件名中的系统和架构，再解压并确认执行权限
.debDebian、Ubuntu 等 Debian 系系统适合使用 APT 或 dpkg 管理的软件包
.rpmFedora、RHEL 等 RPM 系系统适合使用 DNF 或 RPM 管理的软件包
.apkAndroid 应用或特定移动环境优先使用官方应用渠道，不要从搜索结果中的不明镜像下载

这些后缀只是选择方向，完整文件名和实际资产仍以对应 Release 页面为准。Linux 常见架构可这样判断：

uname -m
  • x86_64 通常对应 amd64 或 x64。
  • aarch64 通常对应 arm64。
  • armv7l 通常对应 armv7l 或 armhf 资产。

Windows 可以在“设置”→“系统”→“系统信息”查看系统类型，也可以使用 PowerShell 查询：

[System.Environment]::Is64BitOperatingSystem
$env:PROCESSOR_ARCHITECTURE

如果 Release 页面提供 SHA-256 摘要，应对下载的原始资产进行校验：先计算本地文件摘要，再与页面显示值逐字符比较。不要把解压后的二进制文件与原始压缩包的摘要混用。

Windows、macOS、Android 和 Apple 平台安装步骤

Windows：图形客户端与核心 ZIP 不是一回事

  1. 打开官方 Desktop 页面，从其 Releases 入口进入资产列表。
  2. Windows 图形客户端的官方要求是 Windows 10+，支持 x64、x86 和 arm64；下载时以页面列出的资产为准。
  3. ZIP 便携版通常是解压后运行，适合希望自行管理目录的用户；如果 Release 同时提供安装资产，安装版适合希望由系统创建快捷方式或安装目录的用户。具体是否提供某种形式，以当前 Release 页面为准。
  4. 首次运行时，只对来源明确且经过校验的程序处理 Windows 安全提示；不要为未知文件关闭系统防护。
  5. 如果只需要命令行核心，下载 Windows 核心资产，而不是把图形客户端当作服务器程序使用。进入解压目录后运行：
.\sing-box.exe version

如果提示不是内部或外部命令，先进入 sing-box.exe 所在目录，或使用上面的相对路径。需要 TUN 时，再按客户端提示启用 Windows 服务模式或相关权限；先用系统代理验证配置，再单独排查 TUN，更容易定位问题。

macOS：从 Apple platforms 页面获取图形客户端

macOS 图形客户端不应从 Desktop 页面选择。官方客户端总览将 macOS 归入 sing-box for Apple platforms；该页面同时提供 macOS 独立版本的 Homebrew Cask 和 GitHub Releases 入口。

  1. 打开官方 Apple platforms 页面。
  2. 在“关于本机”查看处理器，或运行 uname -m；Apple Silicon 通常显示 arm64，Intel 通常显示 x86_64。
  3. 如果资产提供 Universal，表示一个程序包同时面向 Apple Silicon 与 Intel；不确定架构时可优先选择 Universal，但仍以当前 Release 的文件说明为准。
  4. 首次打开独立程序时，如果 macOS 在“系统设置”→“隐私与安全性”阻止运行，只对来源明确的程序执行允许或仍要打开。
  5. 需要 TUN 或网络扩展时，按系统弹窗放行对应权限。程序能打开不代表网络接管已经生效。

官方 Apple 平台页面列出的系统要求为 iOS 15.0+、macOS 13.0+ 和 Apple tvOS 17.0+，并要求使用中国大陆以外的 Apple 账号；安装前应以该页面当前要求为准。

Android：应用渠道优先于手动 APK

  1. 打开官方 Android 页面，优先从页面列出的 Play Store、GitHub Releases 或 F-Droid 获取应用。
  2. 官方要求 Android 5.0+。
  3. 导入配置后启动连接，接受 Android 的 VPN 权限提示；拒绝该权限时，TUN 接管不会生效。
  4. 如果必须使用 APK，先确认来源和架构，不要安装改包或无法核验签名的文件。

Linux 安装：Debian、Ubuntu、Fedora、Arch 与通用脚本

Debian 或 Ubuntu 最容易漏掉软件源配置。不能只下载 GPG key；必须同时写入 /etc/apt/sources.list.d/sagernet.sources，让 APT 知道仓库地址和签名密钥位置。官方 Package Manager 文档给出的完整命令如下：

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
echo '
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

执行后可检查仓库文件：

cat /etc/apt/sources.list.d/sagernet.sources
sing-box version

Fedora 或新版 DNF 可以使用：

sudo dnf config-manager addrepo --from-repofile=https://sing-box.app/sing-box.repo
sudo dnf install sing-box

如果系统仍使用旧版 DNF 语法，应按官方 Package Manager 文档选择对应命令。Arch、NixOS、macOS、Windows 和 Android 的包管理方式也列在同一页面，但第三方包的维护状态和命令可能变化。

通用安装脚本会从官方发布资产安装适用于文档所列 Linux 场景的包。默认安装最新稳定包：

curl -fsSL https://sing-box.app/install.sh | sh

安装测试渠道或指定版本时，官方命令格式分别是：

curl -fsSL https://sing-box.app/install.sh | sh -s -- --beta
curl -fsSL https://sing-box.app/install.sh | sh -s -- --version <版本号>

如果不想直接通过管道执行远程脚本，可以先下载脚本、阅读内容，再在本地执行。固定版本时，必须把 <版本号> 替换为官方 Releases 中实际存在的标签。

安装后验证：version、check、启动和 systemd

sing-box 配置文件使用 JSON，而不是 YAML。官方配置结构包含 log、dns、inbounds、outbounds、route 等字段，具体字段应以官方 Configuration 文档为准。

  1. 确认程序可执行：运行 sing-box version。Windows 核心使用 .\sing-box.exe version。
  2. 检查配置：在配置目录运行 sing-box check -c config.json；如果当前命令版本只接受默认配置路径，则按官方命令格式运行 sing-box check。
  3. 前台试运行：运行 sing-box run -c config.json，先观察日志，不要一开始就放入后台。
  4. 检查监听端口：sing-box 核心没有统一的默认入站端口，实际端口由 JSON 的 inbounds 中 listen_port 决定。
sudo ss -lntup

macOS 使用：

lsof -nP -iTCP -sTCP:LISTEN

如果使用系统服务，官方包管理文档说明 systemd 系统通常会随安装提供 sing-box 服务。常用命令如下：

sudo systemctl enable sing-box
sudo systemctl start sing-box
sudo systemctl status sing-box
sudo journalctl -u sing-box --output cat -e
sudo journalctl -u sing-box --output cat -f

Linux 长期运行时，应检查服务实际使用的配置路径和用户：

systemctl cat sing-box
sudo systemctl status sing-box

配置文件若包含订阅凭据、私钥或访问令牌，不要设置为所有用户可读。使用专用系统用户时，要同时核对 User=、ExecStart=、配置文件路径和目录权限。

验证是否真正走了连接，不要只看进程是否存在：查看客户端或服务日志中的目标域名、出站策略和错误信息；也可以在相同网络环境下对比启用前后的出口 IP。普通代理模式正常而 TUN 无效时，再检查 Windows 服务权限、macOS 网络扩展放行、Linux 权限和 Android VPN 授权。

常见安装失败：按现象定位，不要反复重装

现象优先检查处理方式
command not found程序目录和 PATH进入二进制所在目录运行，确认执行权限，再决定是否加入 PATH。
APT 找不到 sing-box仓库文件、密钥路径和索引确认 sagernet.sources 存在，包含 URIs 和 Signed-By，再重新执行 sudo apt-get update。
程序启动后立即退出架构、执行权限和 JSON重新核对 uname -m，必要时执行 chmod +x，再运行 sing-box check -c config.json。
端口被占用inbounds.listen_port 和监听进程用 Linux 的 sudo ss -lntup 或 macOS 的 lsof 找到冲突进程，再调整配置或停止冲突服务。
客户端能打开但网页不通系统代理、TUN、VPN 或网络扩展权限先关闭 TUN 测试普通代理，再根据日志和系统权限逐项恢复。
systemd 启动失败服务用户、路径和日志执行 systemctl cat sing-box、sudo systemctl status sing-box 和 sudo journalctl -u sing-box --output cat -e。

远程订阅链接应视为凭据处理，不要发布到截图、Issue、公开聊天或日志中。配置能够下载，不代表其中的域名、节点、路由和权限设置一定适合当前网络；先检查配置来源，再观察客户端日志中的实际命中结果。

常见问题

sing-box 安装时应该下载核心还是客户端？

桌面和手机用户通常选择图形客户端；Linux 服务器、自动启动和自定义路由选择核心程序。macOS 图形客户端看 Apple platforms 页面，Windows 和 Linux 桌面客户端看 Desktop 页面。

Debian 或 Ubuntu 执行 apt-get install sing-box 找不到包怎么办？

检查是否已经写入 /etc/apt/sources.list.d/sagernet.sources，并确认其中包含 https://deb.sagernet.org/%E3%80%81Signed-By 字段和正确的 GPG key 路径，然后重新执行 sudo apt-get update。

sing-box 配置文件用 YAML 还是 JSON？

核心配置使用 JSON。安装后可以运行 sing-box check -c config.json 检查配置；不要把其他客户端的 YAML 文件直接当作 sing-box 配置。

Windows 安装后提示不是内部或外部命令怎么办？

先进入 sing-box.exe 所在目录，运行 .\sing-box.exe version。确认程序可以执行后，再把目录加入 PATH，或改用图形客户端完成配置导入。

为什么 sing-box 能启动，但网页流量没有经过它？

进程运行不等于流量已经接管。检查系统代理或 TUN 状态，确认 Windows、macOS、Linux 或 Android 的相关权限已授予，再看日志中的出站策略并对比出口 IP。

相关阅读

参考资料

  1. Graphical Clients - sing-box 官方图形客户端总览
  2. sing-box for Desktop 官方桌面客户端页面
  3. sing-box for Apple platforms 官方客户端页面
  4. sing-box for Android 官方客户端页面
  5. Package Manager - sing-box 官方包管理器文档
  6. Introduction - sing-box 官方配置文档
  7. SagerNet/sing-box 官方 Releases 页面
  8. Release 1.14.3 - SagerNet/sing-box 官方版本页面