sing-box 新手配置教程：从安装到第一个节点（VLESS Reality + Hysteria2）| 冲浪笔记

你下载了 sing-box 但打开了终端不知道怎么往下走。sing-box 和 Clash Verge Rev、v2rayNG 不一样——它没有图形界面，一切靠一个 JSON 配置文件驱动。这篇文章给你一条明确路径：下载 → 写第一份配置 → 跑起来 → 验证连通 → 再加第二个协议。

全文基于 sing-box v1.12.5（2026 年 5 月 Release），macOS 14.5 / Windows 11 / Debian 12 三端平台适用，操作路径一致。你手里应该已经有服务商给的节点参数——没有的话先拿到再往下看。

开始前先确认三样东西

不是走流程。缺一个后面的步骤就进行不下去。

第一，你有节点参数，而不仅仅是一个订阅链接。 sing-box 的 JSON 配置里每个出站节点是逐字段填写的。你至少需要：服务器 IP、端口、传输协议类型（VLESS/Hysteria2/Trojan）、UUID 或密码。如果你手里只有一个 vless:// 分享链接，把它粘贴到记事本，? 后面的部分就是参数——&pbk= 是 publicKey，&sid= 是 shortId，&sni= 是 serverName，&fp= 是 fingerprint。

第二，你确定自己的操作系统和 CPU 架构。 下载错架构的二进制文件是新手最高频错误。macOS 用户：左上角苹果菜单 → 关于本机 → 芯片那一行写「Apple M1/M2/M3/M4」就下 arm64，写「Intel」就下 amd64。Windows 用户：设置 → 系统 → 关于 → 系统类型显示「64 位操作系统」下 amd64。Linux 用户：终端跑 uname -m，x86_64=amd64，aarch64=arm64。

第三，你愿意用终端。 sing-box 没有图形界面，启动、看日志、关停都在终端里完成。如果你看到终端就头疼，这篇文章不适合你——去用 NekoBox 或 Hiddify，它们把 sing-box 内核包了一层图形壳。如果你愿意学终端，下面每一步都会把完整的命令写出来，直接复制粘贴就能跑。

sing-box 去哪下载？怎么装？

sing-box 没有安装包（没有 .dmg、.msi、.deb），只有一个可执行文件。去 GitHub Release 页面下载对应平台的压缩包，解压后把二进制文件放到固定目录。

下载

打开 https://github.com/SagerNet/sing-box/releases ，找到最新版本号。2026 年 5 月最新稳定版是 v1.12.5。往下翻到 Assets 区域，找到你平台的文件：

平台	文件名示例	备注
macOS Intel	sing-box-1.12.5-darwin-amd64.tar.gz	2019 年及之前的 MacBook Pro/Air
macOS Apple Silicon	sing-box-1.12.5-darwin-arm64.tar.gz	M1/M2/M3/M4 芯片
Windows 64 位	sing-box-1.12.5-windows-amd64.zip	绝大多数 Windows 电脑
Linux amd64	sing-box-1.12.5-linux-amd64.tar.gz	大多数 VPS、桌面 Linux

下载后解压：

# macOS / Linux
mkdir -p ~/sing-box
cd ~/sing-box
# 假设下载的文件在 Downloads 目录
tar -xzf ~/Downloads/sing-box-1.12.5-darwin-arm64.tar.gz
# 解压后 sing-box 二进制文件在当前目录

Windows 用户用资源管理器右键 zip 文件 → 全部解压 → 解压到 C:\Users\<你的用户名>\sing-box\。

验证下载的文件没损坏

# macOS / Linux
cd ~/sing-box
./sing-box version

# 输出示例：
# sing-box version 1.12.5
# 
# Environment: go1.24.3 darwin/arm64
# Commit: a1b2c3d4

如果能输出版本号和 commit hash，说明文件完整、架构正确。如果有 permission denied，先跑 chmod +x sing-box。Windows 用户打开 PowerShell，cd 到 sing-box 目录，运行 .\sing-box.exe version。

把 sing-box 加到 PATH（可选，但建议做）

每次都要 cd 到 ~/sing-box/ 跑 ./sing-box 很烦。把二进制文件所在目录加到系统 PATH：

# macOS / Linux: 编辑 ~/.zshrc 或 ~/.bashrc，末尾加一行
export PATH="$HOME/sing-box:$PATH"
# 保存后运行 source ~/.zshrc 生效

Windows：Win+R 打开 sysdm.cpl → 高级 → 环境变量 → 在用户变量里找到 Path → 编辑 → 新建 → 填入 C:\Users\<你的用户名>\sing-box。

第一个配置文件：VLESS Reality 出站

不跟你讲理论。下面是第一份可以直接用的配置文件。把里面的尖括号占位符全部换成你自己的参数后保存，就能跑起来。

{
  "log": {
    "level": "info",
    "timestamp": true
  },
  "dns": {
    "servers": [
      {
        "tag": "google-dns",
        "address": "tls://8.8.8.8",
        "detour": "vless-reality-out"
      },
      {
        "tag": "local-dns",
        "address": "https://223.5.5.5",
        "detour": "direct"
      }
    ],
    "rules": [
      {
        "domain_suffix": [
          "google.com",
          "youtube.com",
          "github.com",
          "twitter.com",
          "facebook.com",
          "instagram.com",
          "openai.com",
          "reddit.com"
        ],
        "server": "google-dns"
      }
    ],
    "final": "local-dns"
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "vless",
      "tag": "vless-reality-out",
      "server": "<服务器IP>",
      "server_port": 443,
      "uuid": "<你的UUID>",
      "flow": "xtls-rprx-vision",
      "tls": {
        "enabled": true,
        "server_name": "<伪装域名，如 www.google.com>",
        "utls": {
          "enabled": true,
          "fingerprint": "chrome"
        },
        "reality": {
          "enabled": true,
          "public_key": "<服务端公钥，Base64格式约44字符>",
          "short_id": "<16位十六进制shortId>"
        }
      },
      "packet_encoding": "xudp"
    },
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "domain_suffix": [
          "google.com",
          "youtube.com",
          "github.com",
          "twitter.com",
          "facebook.com",
          "instagram.com",
          "openai.com",
          "reddit.com"
        ],
        "outbound": "vless-reality-out"
      },
      {
        "domain_suffix": [
          "cn",
          "baidu.com",
          "bilibili.com",
          "qq.com",
          "taobao.com",
          "jd.com",
          "weixin.qq.com"
        ],
        "outbound": "direct"
      },
      {
        "geoip": "cn",
        "outbound": "direct"
      }
    ],
    "final": "vless-reality-out"
  }
}

逐字段解释——只讲你会用到的

不讲协议原理，只讲「这个字段填错的表现是什么」。

log.level：设 info 即可。想看更详细的 TLS 握手过程改成 debug，但日志会非常多。排查问题的时候临时开 debug，平时用 info。

dns.servers[0]：tls://8.8.8.8 是 Google 的 DNS-over-TLS 服务。detour: "vless-reality-out" 的意思是这条 DNS 查询通过 VLESS Reality 隧道发出，Google DNS 看到的请求 IP 是节点的出口 IP。这个机制保证了 DNS 查询不会泄漏你的真实 IP。

dns.servers[1]：https://223.5.5.5 是阿里 DNS，detour: "direct" 表示直连。国内域名的 DNS 查询走这条，不经过代理。

inbounds[0]：type: "mixed" 同时开启 HTTP 代理和 SOCKS5 代理，监听在 127.0.0.1:2080。这是你系统代理设置里要填的地址和端口。mixed 类型是 sing-box 1.10+ 才加入的简化写法，之前要分别写 http 和 socks 两个 inbound。

outbounds[0] — VLESS Reality 出站：

字段	作用	填错的表现
type: "vless"	指定协议类型	如果用成别的类型，日志报 unknown outbound type
server	节点 IP	必须写真实 IP 或真实可达域名。填 Cloudflare CDN 的域名会导致 TLS 握手在 CDN 层被终结，sing-box 日志报 tls handshake error
server_port	节点端口。Reality 通常 443	填错就是 connection timeout，log 里 dial tcp 连不上
uuid	VLESS 用户 ID，格式 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	填错服务端返回 invalid user，连接被拒
flow	必须是 xtls-rprx-vision	Reality 唯一支持的 flow。填别的值能启动但流量不通
tls.server_name	TLS SNI，也是 Reality 的回落伪装域名	必须填域名，不能填 IP。 填 IP 的话 sing-box 日志会报 tls: server name is an IP address
tls.utls.fingerprint	浏览器 TLS 指纹，默认 chrome	选 chrome 最稳。部分老服务端不支持 randomized
tls.reality.public_key	服务端 X25519 公钥，Base64 编码	多一个空格、多一个换行都会导致 reality verification failed。从服务面板直接复制，不要手动打
tls.reality.short_id	恰好 16 位十六进制字符	不是 8 位也不是 32 位。填错长度服务端静默丢弃连接，无报错
packet_encoding: "xudp"	UDP over TCP 的包装方式	Reality 下必须写 xudp。写 packetaddr 或留空会导致 UDP 不通——看 YouTube 直播或打语音电话会出问题

route.rules：三条规则从上往下匹配，第一条命中的生效。

1. 域名后缀匹配 → 走 vless-reality-out（代理）
2. 国内域名后缀 + GeoIP CN → 走 direct（直连）
3. final: "vless-reality-out" → 没匹配到规则的所有流量默认走代理

这条 final 规则意味着什么：不在规则列表里的域名全部走代理。保守做法，适合新手——不会出现「为什么 XX 网站打不开」的情况。如果你想要更精细的控制，把 final 改成 direct，再把所有需要走代理的域名一条一条加到规则列表里。

配置文件放哪

把上面的 JSON 保存为 config.json，放在 ~/sing-box/ 目录下，跟 sing-box 可执行文件在一起。结构：

~/sing-box/
├── sing-box          ← 可执行文件
└── config.json       ← 配置文件

Windows 对应 C:\Users\<用户名>\sing-box\。两个文件在同一目录下时，运行命令不需要写 config.json 的绝对路径。

启动、检查日志、验证连通

配置文件写好之后，三步验证它真的能用。

启动

cd ~/sing-box
./sing-box run -c config.json

终端会出现类似这样的日志：

INFO[0000] sing-box started
INFO[0000] inbound/mixed[mixed-in]: listening on 127.0.0.1:2080
INFO[0000] outbound/vless[vless-reality-out]: initialized

保持终端开着。关掉终端 = sing-box 进程终止 = 代理断掉。

如果出现红色 FATAL 或 error 行，按日志信息定位——它一定会告诉你哪个文件第几行的哪个字段有问题。例如：

FATAL[0000] decode config: json: line 24: did not find expected key

代表 config.json 第 24 行附近 JSON 语法有问题。打开 JSONLint 粘贴验证。

设系统代理

sing-box 的 mixed inbound 监听在 127.0.0.1:2080。去系统设置里填这个地址：

系统	设置路径
macOS	系统设置 → 网络 → Wi-Fi → 详细信息 → 代理 → HTTP 代理：127.0.0.1:2080
Windows	设置 → 网络和 Internet → 代理 → 手动设置代理 → 地址 127.0.0.1，端口 2080
Linux (GNOME)	设置 → 网络 → 代理 → 手动 → HTTP 代理：127.0.0.1:2080

验证出口 IP

系统代理打开后，浏览器访问：

https://api.ipify.org

页面上显示的 IP 应该不是你家里宽带的 IP。记下这个 IP。然后回到终端按 Ctrl+C 停止 sing-box，刷新 api.ipify.org 页面——IP 应恢复到本地宽带 IP。再重新启动 sing-box，刷新页面——IP 又切回节点出口 IP。

来回切换两次确认。如果 IP 始终不变，说明系统代理没生效——回到系统设置检查代理地址和端口。

验证 DNS 没有泄漏

浏览器访问 https://dnsleaktest.com ，点 Standard Test。页面会列出当前 DNS 请求实际到达的 DNS 服务器 IP。不应该出现 114.114.114.114、223.5.5.5、119.29.29.29 等国内 DNS。 如果出现了，说明 config.json 里的 dns.servers 配置没生效——去 sing-box 日志里搜索 dns 或 google-dns，看是否有相关错误。

再加一个 Hysteria2 出站

VLESS Reality 能用了，但你想多一个协议做备用——或者 Hysteria2 在高峰时段更稳定。下面在同一个配置文件里加入 Hysteria2 出站。

打开 config.json，修改两处：

1. outbounds 数组里新增 Hysteria2 出站对象和一个 selector 策略组
2. route.rules 和 dns 里把出站引用从固定写死的 tag 改成策略组 tag

完整修改后的配置文件：

{
  "log": {
    "level": "info",
    "timestamp": true
  },
  "dns": {
    "servers": [
      {
        "tag": "google-dns",
        "address": "tls://8.8.8.8",
        "detour": "proxy"
      },
      {
        "tag": "local-dns",
        "address": "https://223.5.5.5",
        "detour": "direct"
      }
    ],
    "rules": [
      {
        "domain_suffix": [
          "google.com",
          "youtube.com",
          "github.com",
          "twitter.com",
          "facebook.com",
          "instagram.com",
          "openai.com",
          "reddit.com"
        ],
        "server": "google-dns"
      }
    ],
    "final": "local-dns"
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "selector",
      "tag": "proxy",
      "outbounds": [
        "vless-reality-out",
        "hysteria2-out"
      ],
      "default": "vless-reality-out"
    },
    {
      "type": "vless",
      "tag": "vless-reality-out",
      "server": "<服务器IP>",
      "server_port": 443,
      "uuid": "<你的UUID>",
      "flow": "xtls-rprx-vision",
      "tls": {
        "enabled": true,
        "server_name": "<伪装域名>",
        "utls": {
          "enabled": true,
          "fingerprint": "chrome"
        },
        "reality": {
          "enabled": true,
          "public_key": "<公钥>",
          "short_id": "<shortId>"
        }
      },
      "packet_encoding": "xudp"
    },
    {
      "type": "hysteria2",
      "tag": "hysteria2-out",
      "server": "<Hysteria2服务器IP>",
      "server_port": 443,
      "up_mbps": 50,
      "down_mbps": 200,
      "password": "<你的Hysteria2密码>",
      "tls": {
        "enabled": true,
        "server_name": "<TLS伪装域名，如 www.bing.com>",
        "insecure": false
      }
    },
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "domain_suffix": [
          "google.com",
          "youtube.com",
          "github.com",
          "twitter.com",
          "facebook.com",
          "instagram.com",
          "openai.com",
          "reddit.com"
        ],
        "outbound": "proxy"
      },
      {
        "domain_suffix": [
          "cn",
          "baidu.com",
          "bilibili.com",
          "qq.com",
          "taobao.com",
          "jd.com",
          "weixin.qq.com"
        ],
        "outbound": "direct"
      },
      {
        "geoip": "cn",
        "outbound": "direct"
      }
    ],
    "final": "proxy"
  }
}

改了什么

selector 策略组。 type: "selector" 是 sing-box 的出站选择器——相当于 Clash 里的策略组。outbounds 数组列出了两个可选的出站 tag：vless-reality-out 和 hysteria2-out。default 指定启动时默认用 VLESS Reality。sing-box 没有图形界面不能在运行中切换，想切换需要改 default 值重启，或者用 sing-box 的 REST API（超出本文范围）。

Hysteria2 出站的关键字段：

字段	填什么	注意
type: "hysteria2"	协议标识	注意是 hysteria2，不是 hysteria（那是 v1）
server / server_port	服务器 IP 和端口	Hysteria2 默认端口也是 443，但服务商可能用其他端口
up_mbps / down_mbps	上行/下行带宽，单位 Mbps	填服务商给你的带宽上限。不要自己随便写——服务端会根据这个值做速率控制
password	认证密码	有些服务面板导出配置叫 auth，值是 base64 编码的。直接原样填入 password 字段，sing-box 会自动识别
tls.server_name	TLS SNI	不同于 Reality 的 serverName。这里填 Hysteria2 服务端 TLS 证书上的域名
tls.insecure	设为 false	不要开——true 会跳过 TLS 证书验证，能用但失去中间人防护

dns.detour 从 vless-reality-out 改成了 proxy。 现在 DNS 请求通过策略组发出，你可以通过切换策略组的默认出站来控制 DNS 走哪条线路。

配置失败排查表

下表整理了新手最常见 6 种失败表现。按定位效率从高到低排列——先看日志里的关键词，再对照可能原因和修复动作。

表现	日志关键词	最可能的原因	先改什么
启动报错，无法运行	FATAL: decode config 或 json: cannot unmarshal	JSON 语法错误：缺少逗号、多余逗号、花括号未闭合	把 config.json 全文粘贴到 jsonlint.com 检查
启动成功但日志不停报错	reality verification failed	publicKey 有空格/换行，或 shortId 长度不对	从服务商后台重新复制 publicKey 和 shortId，直接粘贴不手动编辑；确认 shortId 正好 16 位十六进制
能启动但浏览器打不开任何网站	日志无 error，但你访问的域名不在 route.rules 里	当前用的出站不通，或 final 规则指向了不通的出站	先不试网页，用 curl -x http://127.0.0.1:2080 https://api.ipify.org 直接测试代理是否可达
curl 代理测试返回 200 但浏览器不行	日志正常	浏览器没走到系统代理	检查浏览器代理设置：Chrome 确认「使用系统代理」，Firefox 确认「使用系统代理设置」，不要把浏览器设成「直接连接」
部分网站能开，部分打不开	日志无明显 error	route.rules 覆盖不全，没匹配到的域名走了 direct	把 route.final 从 direct 改成 proxy，让所有未匹配域名默认走代理
Hysteria2 节点加了但日志显示 invalid auth	hysteria2: authentication failed	password 字段值和编码不对	确认 password 是否应该是 base64 格式；在服务商提供的原始配置里搜索 auth 或 obfs-password 字段确认正确值

排查基本原则：一次只改 config.json 里的一个字段，改了马上重启验证。不要同时改 server、port 和 password——你分不清是哪个改动生效。每个修改后跑一遍 curl -x http://127.0.0.1:2080 https://api.ipify.org 验证代理是否可达。

配置成功之后看什么

1. 出口 IP 变了。 这是第一关。
2. DNS 没有泄漏。 dnsleaktest.com 没有出现国内 DNS 服务器。
3. UDP 能通。 在 sing-box 开着代理的情况下打一个语音电话（微信语音、Telegram 通话），能接通且音质正常说明 UDP 转发了。UDP 不通的话微信语音能接通但没声音。
4. YouTube 4K 不卡。 比延迟数字更有意义——打开一个 4K 视频，看缓冲速度和实际播放是否流畅。

如果前三项都过了但 YouTube 卡，是节点出口带宽不够，跟你的 sing-box 配置无关——换节点或联系服务商。

想退回去怎么办

• 停代理：终端按 Ctrl+C 终止 sing-box。
• 清系统代理：macOS 系统设置 → 网络 → 代理 → 全部关掉；Windows 设置 → 网络和 Internet → 代理 → 关闭。
• 删除配置：把 ~/sing-box/config.json 移到别处或直接删掉。sing-box 二进制文件可以留着下次用。
• 浏览器没恢复：退出浏览器重新打开。部分浏览器会缓存代理设置，重启才能刷新。

相关阅读

• VLESS Reality 节点搭建完整教程（VPS 2026）：3X-UI + Xray-core 从零部署
• NekoBox 添加 VLESS Reality 节点完整教程（Android / Windows 2026）
• Hysteria2 服务端搭建教程：VPS 一键部署（2026）
• v2rayNG 导入 VLESS Reality 节点完整步骤（Android 2026）
• sing-box vs Mihomo：内核与规则引擎对比