sing-box 下载与配置入门：安装内核、校验 JSON 和验证本地代理

区分命令行内核与图形客户端安装包

从 sing-box 官方 Releases 下载稳定版本。资产较多，先找到以 sing-box- 开头的命令行压缩包，再匹配系统与 CPU 架构。SFA、SFM、SFW 等是对应图形客户端的资产，不能把它们与本篇的命令行包混用。

希望用界面导入配置的读者，可以从 Karing 或 Hiddify 开始。这里重点解释内核和本地入口的实际工作方式。

解压后先确认二进制能运行

把下载包解压到自己的测试目录，将配置文件放在同一目录。Linux、macOS 如需执行权限，可对当前目录的二进制执行 chmod +x ./sing-box。不要把首次实验混进已有系统服务的配置目录。

在终端中进入解压目录，运行 ./sing-box version 确认版本；Windows PowerShell 使用 .\sing-box.exe version。下面的命令假设二进制已在 PATH 中，因此写作 sing-box；未加入 PATH 时替换成上述相对路径即可。

Linux 长期运行可以采用官方软件仓库或包管理器方式，但那会涉及系统安装和服务管理。本地入门先使用压缩包，普通用户即可验证本篇的 mixed 入口，无需创建虚拟网卡、安装服务或修改系统代理。命令无法启动时，先排查架构、执行权限和文件路径。

可直接保存的本机 mixed 与 direct 配置

新建 config.json，完整复制下面内容，使用 UTF-8 保存。不要添加注释或保留模板中的占位符。

{
  "log": {
    "level": "info",
    "timestamp": true
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "local-mixed",
      "listen": "127.0.0.1",
      "listen_port": 2080,
      "set_system_proxy": false
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "final": "direct"
  }
}

mixed 在同一个端口接受 HTTP 和 SOCKS 请求；listen 限制为本机回环地址；set_system_proxy: false 明确不改系统代理；direct 则直接连接请求目标。端口 2080 只是本例选择，若被占用可改为其他空闲端口，并同步修改验证命令。

这是本地入口与直连出站的验证配置。它能证明内核接收并转发了请求，不能证明远端节点可用，也不会使原本无法直连的网站自动可访问。不要把监听地址改成 0.0.0.0 来解决本机连接问题，那会扩大无认证入口的可访问范围。

先 check 校验，再 run 启动

sing-box check -c config.json
sing-box run -c config.json

先执行第一条；检查成功通常没有额外输出，终端退出状态应为成功。报错时根据文件名、字段路径和提示修改，再重新检查。校验通过后执行第二条，保持该终端运行，查看日志是否出现 127.0.0.1:2080 的监听信息。

配置校验判断的是结构及核心能否建立配置对象，不能替你验证远端密码、网络连通性和业务网站。run 是前台运行，测试结束在该终端按 Ctrl+C 停止；不要关闭窗口后又误以为入口仍在服务。Windows 命令同样替换为 .\sing-box.exe，并确认当前目录含 config.json。

HTTP 与 SOCKS 各发一个实际请求

若电脑已有 Python 3，可在另一个空目录、另一个终端启动只绑定本机的临时网页服务：

python3 -m http.server 18080 --bind 127.0.0.1

Windows 上可使用已安装 Python 的 py -3 代替 python3。保持 sing-box 和临时服务都在运行，再从第三个终端分别执行：

curl --noproxy example.invalid --proxy http://127.0.0.1:2080 --max-time 15 http://127.0.0.1:18080/
curl --noproxy example.invalid --proxy socks5h://127.0.0.1:2080 --max-time 15 http://127.0.0.1:18080/

Windows PowerShell 使用 curl.exe 调用实际 curl 程序。看到临时网页内容，同时 sing-box 日志记录入站和 outbound/direct，说明两种本地入口完成了转发。--noproxy example.invalid 把绕过列表设为不会匹配本次本机目标的域名，避免已有排除代理设置绕过测试，也避免旧版 PowerShell 丢失空字符串参数。

上述 JSON 已用官方 1.14.2 Linux amd64 二进制完成校验，并通过本机 HTTP 与 SOCKS 请求验证；其他系统仍需自己按步骤确认。完成后在两个服务终端按 Ctrl+C 停止。该测试只验证本机处理流程，不涉及节点速度或远端服务。

从本地验证迁移到真实远端配置

本地测试通过后，保留这份配置作为入口恢复点。真实代理至少还需要一个正确的协议出站、对应服务器地址与认证信息，以及让需要代理的请求选中该出站的路由。

根据当前版本的官方协议文档填写配置，切勿把 Clash YAML 的字段直接拼进 sing-box JSON。应用里显示相同协议名称，也不代表导出的字段结构相同。订阅可能包含完整配置，也可能只有分享链接，需先确定输入形式再转换或导入。

迁移时一次只增加一个出站，先校验，再向一个明确目标发起请求。日志必须能证明该请求命中了远端出站，而不是仍由 direct 完成。确认基础链路后，再加入 DNS、规则集或 TUN；复杂旧配置要结合版本迁移说明，避免用已废弃字段重建整份模板。

按监听、语法、DNS 和出站顺序排查

• connection refused：确认 run 仍在运行，并核对 curl 与配置中的端口一致。程序刚退出时，检查退出前的日志。
• address already in use：已有进程占用端口。选择另一个空闲端口并同步修改命令，不要直接终止不认识的进程。
• 配置解析错误：检查引号、逗号、括号与字段类型；先让最小示例通过，再加其他模块。
• 本机 IP 请求正常，域名请求失败：沿 DNS 和域名解析配置检查，不能仅凭本地端口开放就排除解析问题。
• 远端请求失败：检查命中的出站、认证参数、设备时间和服务端日志。direct 示例通过不能排除远端协议错误。

遇到系统代理或应用差异时，可接着使用 本站分层故障排查。本例没有设置全局代理，因此其他应用是否使用它取决于应用自己的代理配置。

备份配置与版本，升级后先做兼容检查

备份 config.json、本地规则文件、原二进制版本和启动方式；有凭据的配置保存在受保护目录，不要直接公开。升级前阅读 官方 Migration 说明，确认哪些字段已弃用或替换。

把新二进制放进独立目录，用新版本先执行 check。配置兼容后，再停旧实例、启动新实例，重做本地请求与真实业务验证。保留可恢复的旧配置副本，不要把格式化成功当成升级兼容成功。

本地入门阶段无需开机启动；持续运行时再根据实际系统选择官方服务管理方式。网页教程只描述已核对的版本行为，若未来新版本报字段兼容错误，以对应版本的官方文档和迁移提示为准。

常见问题

官方来源与核对

本文依据以下官方项目与文档整理，资料核对日期为 2026.10.02。安装包、界面和配置字段会随版本变化，可通过原始资料确认当前要求。

• sing-box 官方发布与命令行安装资产
• sing-box 官方包管理安装说明
• sing-box 官方 mixed 入站文档
• sing-box 官方 direct 出站文档
• sing-box 官方 check 与 run 命令实现
• sing-box 官方版本迁移说明

相关工具

返回工具目录 · 按症状排查问题