sing-box Windows 配置教程：安装、导入 JSON、TUN 与启动排错
简答：sing-box Windows 配置建议按三步完成：先确认 Windows 架构并区分 Desktop 图形客户端与 CLI 核心，再导入 JSON 或远程配置，最后分别验证“配置可解析、核心已启动、实际访问成功”。遇到失败时，优先执行 sing-box check，再查看启动日志、端口占用和 TUN 权限，不要把 Clash YAML 或 Base64 内容直接当作 sing-box JSON。
定义：sing-box Windows 配置，是在 Windows 上安装 sing-box Desktop 或 CLI，准备兼容的 JSON 配置，并通过系统代理、混合端口或 TUN 让应用使用该配置的过程。
先做选择：Desktop 还是 CLI？x64、x86、ARM64 怎么确认
本文是站在第三方使用指南角度整理的操作说明，不代表任何品牌的官网或官方下载站。sing-box for Desktop 是用于管理和运行本地或远程配置的图形客户端，并提供包括 TUN 在内的平台功能；官方文档列出的 Windows 要求为 Windows 10 及以上，支持 x64、x86 和 arm64。官方 Desktop 文档
| 使用目标 | 建议路线 | 适合什么情况 |
|---|---|---|
| 不想手动敲命令 | sing-box for Desktop | 需要添加本地或远程配置、查看运行状态、使用图形界面管理 TUN。 |
| 需要脚本、服务或日志控制 | sing-box CLI | 能够使用 PowerShell，想用 check、run 或自动化启动。 |
| 不确定下载哪个文件 | 先查系统架构 | 普通 Intel/AMD 电脑通常先核对 x64；Windows on ARM 设备应核对 arm64，不能仅凭模拟运行状态判断。 |
确认架构：打开“设置 → 系统 → 关于”，查看“系统类型”。也可以打开 PowerShell，执行：
$env:PROCESSOR_ARCHITECTURE
如果设备使用模拟层，还可以继续执行：
$env:PROCESSOR_ARCHITEW6432
以实际显示结果和下载页面的资产名称为准。官方发布页当前同时列出正式版本与预发布版本；截至 2026-11-12，页面可见 v1.14.4 和 v1.15.0-alpha.13，预发布版本不应在未确认兼容性前作为默认选择。sing-box 官方 Releases
Windows 安装：图形客户端与 CLI 分开处理
路线一：安装 sing-box for Desktop
- 打开官方 Desktop 文档中的 GitHub Releases 入口，不要根据搜索结果中的文件名猜测来源。
- 在发布资产中按系统架构选择 Windows 安装包，x64、x86、arm64 必须与系统类型对应；如果资产名称或安装方式不清楚，以当前发布页为准。
- 安装后首次启动，如果 Windows 弹出用户账户控制提示，只有在你确认文件来源和发布页一致时才继续。
- 在客户端中寻找添加本地配置或远程配置的入口。图形界面菜单名称可能随版本变化，遇到名称不同应以当前版本界面为准。
官方说明确认 Desktop 可以管理本地或远程 sing-box 配置，但没有在该页面固定所有界面菜单名称，因此本文不虚构具体按钮路径。sing-box for Desktop 官方说明
路线二：使用 CLI 压缩包
- 从官方 Releases 页面下载与 Windows 架构对应的 CLI ZIP 文件。
- 将 ZIP 解压到不含中文或空格的目录，例如
C:\sing-box，并确认目录中存在sing-box.exe。 - 把配置文件复制到同一目录，命名为
config.json；如果使用其他文件名，后续命令要同步修改。 - 在资源管理器中进入该目录，在空白处右键，选择“在终端中打开”，或在 PowerShell 执行：
cd C:\sing-box
CLI 的配置文件必须是 JSON。官方配置文档列出的顶层结构包括 log、dns、inbounds、outbounds 和 route 等字段；只有结构和字段都符合当前核心版本，文件才可能启动。官方配置结构与命令说明
导入配置：JSON、远程 URL、Clash YAML 和 Base64 不要混用
本地 JSON：适合已经拿到 sing-box 格式配置文件的情况。Desktop 中选择本地配置入口，CLI 则把文件放到工作目录后执行校验。
远程配置：先在浏览器中打开 URL，检查返回内容是否直接呈现 JSON。若出现登录页、HTML 错误页、过期提示或空白内容，说明拿到的不是可直接使用的 sing-box 配置；这时应回到配置提供方后台核对链接，而不是把网页内容保存成 JSON。
Clash YAML：以 proxies:、proxy-groups: 等 YAML 结构开头的内容不是 sing-box 原生 JSON，不能直接改后缀名使用，需要取得 sing-box 格式配置或使用可信的转换流程。
Base64：如果订阅返回一长串编码文本，而不是以 { 开头的 JSON，通常不能直接作为 sing-box 配置文件。先确认服务端是否提供 sing-box 专用订阅，避免把其他客户端订阅误导入。
安全检查：完整订阅 URL、节点密码、UUID、私钥和令牌都属于敏感信息。提交日志或截图前，至少遮盖域名路径中的令牌、认证参数、私钥和服务器地址。
CLI 验证流程：先 check，再 run，最后测试实际访问
“文件能导入”“核心能启动”“应用能访问”是三个不同阶段，建议严格按以下顺序操作。
第一阶段：检查 JSON 和字段
在配置文件所在目录执行：
sing-box.exe check -c config.json
如果当前版本不接受该参数形式，可以先执行：
sing-box.exe help check
再按本机输出调整命令。官方配置文档明确提供 sing-box check 用于配置检查，也提供 format 和 merge 命令。官方 Configuration 文档
第二阶段：启动核心并保留日志
校验通过后执行：
sing-box.exe run -c config.json
不要立即关闭终端。观察是否出现配置解析错误、端口监听错误、TLS 握手失败或节点连接超时。需要停止时，在当前窗口按 Ctrl+C。
第三阶段：确认接管方式
| 方式 | 作用 | 验证方法 |
|---|---|---|
| 系统代理 | 让遵循 Windows 代理设置的应用使用 HTTP 或 SOCKS 代理。 | 检查 Windows“设置 → 网络和 Internet → 代理”中的手动代理地址与端口是否和配置一致。 |
| 混合端口 | 在同一监听入口提供配置支持的代理协议，具体协议以配置中的 inbound 为准。 | 检查日志是否成功监听该端口，再用本机应用的代理设置指向对应地址和端口。 |
| TUN | 通过虚拟网络接口接管更广泛的系统流量。 | 启动后打开“设置 → 网络和 Internet → 高级网络设置”，查看是否出现新的虚拟适配器；名称以当前系统和客户端显示为准。 |
TUN 通常涉及路由、DNS 和系统权限。官方文档说明，Windows 下 dns_mode 可以使用 native 或 hijack 等模式；strict_route 还能减少 Windows 多网卡 DNS 解析造成的泄漏，但可能影响某些虚拟化软件。官方 TUN 配置文档
常见启动失败：按现象定位，不要直接重装
| 现象 | 检查 | 判断与处理 | 回滚 |
|---|---|---|---|
decode config、JSON parse error | 用文本编辑器检查逗号、引号、括号；确认文件不是 HTML、YAML 或 Base64。 | 属于格式或内容类型错误。重新取得 JSON，或恢复到上一次可用配置。 | 保留原文件副本，不要覆盖唯一配置。 |
unknown field | 记录报错字段和当前核心版本，对照官方配置文档搜索字段。 | 可能是版本不兼容、字段拼写错误或字段已变更。删除未知字段前先备份。 | 换回与配置生成方匹配的核心版本，具体版本兼容性需核实。 |
| 端口已被占用 | PowerShell 执行 Get-NetTCPConnection -LocalPort 端口号，再用 Get-Process -Id 进程ID 查看进程。 | 确认是否已有其他客户端监听同一端口；关闭冲突程序或修改配置中的监听端口。 | 恢复原端口，并确保旧进程已退出。 |
| TUN 启动失败、虚拟网卡不出现 | 确认以管理员权限启动；检查 Windows 安全软件、虚拟网卡列表和是否已有其他 TUN 客户端运行。 | 常见方向是权限冲突、驱动或虚拟网卡冲突。先关闭其他接管网络的程序，再单独测试。 | 关闭 TUN，改用系统代理或混合端口验证核心是否本身可用。 |
| 核心启动但节点超时 | 先确认日志中是否完成监听，再检查节点域名、端口、TLS 参数、系统时间和 DNS。 | 如果本地监听正常而远端连接超时，问题更接近节点或网络路径，不等于配置文件解析失败。 | 切换到另一份已核实配置，或联系配置提供方核对节点信息。 |
| 浏览器仍无法访问 | 检查浏览器是否遵循系统代理；确认代理地址、端口、协议与 sing-box inbound 一致。 | 系统代理未接管和 TUN 未启动是两类问题。先用命令行或支持代理设置的应用做对比测试。 | 关闭系统代理，停止核心，再恢复 Windows 原代理设置。 |
如果 CLI 能运行但 Desktop 不能运行，优先比较两者实际使用的配置文件、核心版本、权限和监听端口；如果 Desktop 导入成功但 CLI 的 check 失败，说明两条路线使用的文件或版本可能不同。
Windows 配置完成后的自查清单
- 架构正确：安装包与 Windows 系统类型一致。
- 来源可核对：下载文件能在官方发布页找到对应资产；截至 2026-11-12，正式版与预发布版应分开判断。
- 格式正确：本地文件是 JSON，不是 HTML、Clash YAML 或 Base64。
- 校验通过：
sing-box.exe check -c config.json没有返回错误。 - 核心启动：
run后日志没有持续出现配置解析或端口监听错误。 - 接管方式明确：明确自己使用的是系统代理、混合端口还是 TUN，不要同时开启多个客户端的接管功能。
- 实际访问：使用一个明确支持代理设置的应用测试，再测试浏览器或目标应用。
- 信息脱敏：日志、配置截图和远程链接没有暴露令牌、密码、UUID 或私钥。
若前六项都通过、实际访问仍失败，下一步应查看 DNS、系统代理端口、Windows 防火墙、虚拟网卡和远端节点日志，而不是反复改 JSON 格式。
常见问题
sing-box Windows 应该下载 Desktop 还是 CLI？
不想使用命令行时优先看 sing-box for Desktop；需要脚本、配置校验、前台日志或服务化运行时选择 CLI。两者都要先核对 Windows 的 x64、x86 或 arm64 架构。
Clash 订阅能直接导入 sing-box 吗？
不能把 Clash YAML 或 Base64 文本直接当作 sing-box JSON 使用。先确认配置提供方是否有 sing-box 专用格式；如果远程地址返回 HTML、登录页或错误提示，也不能直接导入。
sing-box 执行 check 通过，但启动后还是不能联网，问题在哪里？
check 只说明配置能够通过语法和字段检查，不代表节点可达或应用已经被接管。继续检查 run 日志、监听端口、系统代理或 TUN 状态，再分别测试本地代理和远端连接。
TUN 一定要管理员权限吗？
TUN 涉及虚拟网络接口、路由和 DNS 接管，实际权限要求取决于当前客户端、配置和 Windows 环境。遇到 TUN 失败时，先尝试以管理员权限启动，并检查虚拟网卡冲突；如果只是验证节点，可先用系统代理或混合端口。
出现 unknown field 应该立刻升级 sing-box 吗？
不建议直接升级或降级。先记录未知字段、当前核心版本和配置来源，对照官方配置文档判断是否存在版本差异；升级前保留原配置，并准备可回滚的核心文件。