sing-box 如何设置？从订阅导入到代理启动的五步流程
简答：sing-box 设置可以按五步完成：选择对应平台客户端，确认订阅返回格式，导入 Remote 或本地 JSON，授予 VPN/TUN 或网络扩展权限，最后用网页、DNS 和日志验证代理是否生效。没有配置时先准备兼容的 JSON；已有订阅时不要直接改后缀，先查看实际返回内容。
定义：sing-box 是一个以 JSON 配置为基础的网络连接核心，并提供 Android、Apple 平台以及 Windows、Linux 桌面客户端。
先照着做：sing-box 设置五步速查卡
本文定位为 sing-box 的首次设置指南，不把某个第三方应用当作统一入口。项目官方客户端列表显示，Android 使用 sing-box for Android，iOS、macOS 和 Apple tvOS 使用 sing-box for Apple platforms，Windows 与 Linux 使用 sing-box for Desktop；具体应用名称和菜单可能随版本变化，应以当前客户端页面为准。查看官方客户端列表。
| 步骤 | 要做什么 | 完成标志 |
|---|---|---|
| 1. 选客户端 | 按 Android、iOS、macOS、Windows 或 Linux 选择图形客户端或命令行核心 | 能打开配置/Profile 页面，或终端可以运行 sing-box |
| 2. 看格式 | 检查订阅实际返回的是 JSON、YAML、编码文本还是 HTML | 确认格式与导入入口匹配 |
| 3. 导入配置 | 添加 Remote URL，或导入本地 JSON 文件 | 配置能保存、更新并显示出站或节点 |
| 4. 启动代理 | 启动服务，按系统提示授予 VPN、网络扩展或 TUN 权限 | 客户端状态显示运行，且没有立即报错 |
| 5. 做最小验证 | 先访问普通网页，再检查 DNS、节点连接和目标业务 | 记录网页、解析、连接三项结果 |
第一次设置时建议只运行一个代理客户端。不要同时开启多个 VPN、TUN、系统代理或 DNS 工具，否则即使网页打不开，也很难判断是配置、权限还是端口冲突。
按设备选择客户端和配置入口
| 设备 | 官方客户端方向 | 首次设置重点 | 需要注意 |
|---|---|---|---|
| Android | sing-box for Android | 在配置或 Profile 页面添加远程配置，启动时允许 VPN 权限 | VPN 和 TUN 行为由 Android 客户端实现，不等于所有 sing-box 核心选项都可用 |
| iOS | sing-box for Apple platforms | 添加远程或本地配置，按系统提示允许 VPN 配置 | 网络扩展、系统 VPN 和后台行为属于客户端及系统边界 |
| macOS | sing-box for Apple platforms 或命令行核心 | 先使用系统代理完成验证，需要接管更多流量时再考虑 TUN | 网络扩展权限和系统代理状态应分别检查 |
| Windows | sing-box for Desktop | 先导入配置并检查系统代理；启用 TUN 时留意权限提示 | 管理员权限、虚拟网卡和其他安全软件可能影响 TUN |
| Linux | sing-box for Desktop 或命令行核心 | 先执行 check，再用 run 启动，最后查看终端或 systemd 日志 | 配置文件、规则集和证书路径必须对运行用户可读 |
官方桌面客户端支持管理本地或远程 sing-box 配置，并提供包括 TUN 透明代理在内的平台功能；其页面列出的桌面系统要求包括 Windows 10 及以上，以及多种 Linux 架构。查看官方桌面客户端说明。
如果客户端中找不到完全相同的“Remote”“Profile”或“配置”按钮，不要据此判断配置不兼容。优先寻找新增远程配置、导入本地文件、更新配置或启动服务等同类入口，因为菜单名称属于图形客户端界面，不是 sing-box 核心统一规定。
先判断订阅格式：JSON 不等于一定可用
sing-box 官方配置格式使用 JSON，顶层可以包含 dns、inbounds、outbounds、route 和 experimental 等字段。看到花括号只能说明内容外观像 JSON，不能证明它符合当前版本的配置结构；最终应通过 JSON 解析和 sing-box 自己的配置检查。查看官方配置结构、检查与格式化说明。
- 返回 JSON：打开订阅链接后，如果内容以
{开头并能看到outbounds等字段，可以先保存为本地文件，再运行配置检查。 - 返回 YAML：如果内容依靠缩进和冒号表达结构，不要直接按 sing-box JSON 导入。除非当前客户端明确支持该格式，否则需要先使用可信的本地转换方式。
- 返回编码文本：一段不可读文本可能是通用订阅编码，也可能是错误响应。不要仅凭长度或后缀判断，先查看 HTTP 响应和提供方声明的格式。
- 返回 HTML：如果看到登录页、错误页、过期提示或网页源码，说明当前链接没有返回配置，先核对链接、权限、重定向和订阅状态。
Linux 或 macOS 命令行可以先执行：
sing-box check -c config.json
如果当前构建的帮助显示参数不同，以 sing-box help 的输出为准。检查通过只代表配置结构能够被当前程序接受，不代表节点一定可连接、DNS 一定正常或所有应用都会被代理。
订阅 URL 应当按敏感凭据处理。不要把完整链接粘贴到公开聊天、在线转换器或不明格式化网站；如果链接已经暴露，优先在订阅提供方处重新生成或撤销。
图形客户端怎么导入 Remote 配置并启动
- 打开当前平台的 sing-box 图形客户端，进入配置、Profile、订阅或远程配置页面。
- 选择新增远程配置，填写便于识别的名称，例如“办公配置”。名称只用于本机区分。
- 类型选择 Remote 或远程 URL，粘贴完整订阅链接。不要把说明文字、空格、换行和引号一起粘贴。
- 保存后手动更新或拉取配置。若显示 JSON 解析错误，先查看链接实际返回内容，不要直接修改节点字段。
- 配置载入后，选择一个出站、节点或选择器项目。如果配置包含选择器，确认当前选择器不是空值。
- 启动服务。Android、iOS 以及部分桌面 TUN 模式会要求 VPN、网络扩展或相关系统权限；拒绝权限时，应用可能显示配置已加载，但系统流量并没有被接管。
- 启动后先打开普通网页，再测试域名解析、节点连接和目标业务，并记录设备、配置名称、节点、时间和错误原文。
系统代理和 TUN 不是同一个开关。官方客户端说明将系统代理、Firewall Redirection 和 Virtual Interface 分为不同接管方式；系统代理主要依赖应用主动遵循代理设置，部分非 HTTP 流量、UDP 或 ICMP 可能不会经过系统代理。查看官方代理模式说明。
- 先用系统代理：适合浏览器和明确支持代理的办公软件，改动小，也容易关闭回滚。
- 再考虑 TUN：当目标应用不读取系统代理，或需要更完整接管系统流量时使用。
- 开启 TUN 后：检查是否有其他 VPN、虚拟网卡、安全软件或旧代理进程同时运行。
Rule、Global、Direct 不一定是所有客户端都有的按钮
“Rule、Global、Direct”更多是部分图形客户端提供的操作界面概念，不是所有平台都会显示完全相同的三个按钮。sing-box 核心实际通过 route 规则、outbounds、选择器和默认出站来决定连接路径，因此没有看到这些按钮，并不代表核心缺少对应能力。
| 界面概念 | 适合做什么 | 异常时怎么用 |
|---|---|---|
| Rule | 按域名、IP、规则集等条件分流 | 正常使用优先；失败时检查规则集和默认出站 |
| Global | 临时固定一个出站进行对照 | 如果 Global 成功而 Rule 失败，优先查路由规则 |
| Direct | 临时直连，用来对比本地网络 | 用于排查，不要把它当成修复方案 |
官方路由文档说明，final 可指定默认出站；如果配置没有有效的默认路径，连接可能无法按预期转发。使用 TUN 时还要关注 auto_detect_interface 等避免路由环路的设置。查看官方路由配置说明。
规则集下载失败也可能让 Rule 模式表现异常。官方文档说明，远程 rule-set 可配置缓存、初始文件和更新间隔；因此应区分“主配置没有载入”和“主配置已载入但规则集更新失败”。查看官方 rule-set 说明。
Linux 命令行：一条完整的本地运行流程
下面是本地 JSON 配置的最小流程。代码中的文件名是占位符，不包含可直接使用的节点、账号或服务器参数；执行前请先备份原配置，并用当前构建的帮助核对参数。
- 进入配置目录并备份：
cp config.json config.json.bak - 检查配置：
sing-box check -c config.json - 需要整理格式时，先确认目标路径，再参考：
sing-box format -w -c config.json -D config_directory - 前台启动：
sing-box run -c config.json - 看到错误时保留完整终端输出；按
invalid character、unknown field、permission denied、address already in use等关键词分流。
run -c config.json 是本地配置文件运行示例；如果配置包含 TUN，Windows、Linux 或 macOS 可能还需要管理员权限、网络扩展或其他系统授权，具体以当前系统提示为准。执行前先运行 sing-box help，避免把其他版本的参数直接套用到当前构建。
如果使用 Linux systemd，官方文档列出的常用管理命令包括：
sudo systemctl start sing-boxsudo systemctl restart sing-boxsudo systemctl status sing-boxsudo journalctl -u sing-box --output cat -e
服务重启后如果马上退出，先检查配置文件、规则集、证书和工作目录是否能被服务运行用户读取，再看日志中的第一条错误，而不是只关注最后一条“启动失败”。查看官方安装与 systemd 服务管理说明。
设置后不能上网：按现象分流，不要一次改很多项
| 现象 | 优先检查 | 下一步 |
|---|---|---|
| 导入时报 JSON 解析错误 | 订阅实际响应、HTML 登录页、编码格式和不可见字符 | 保存响应内容，再运行 check |
| 配置加载成功但启动失败 | 权限、TUN/网络扩展、端口占用和其他 VPN | 关闭其他接管工具，改用系统代理做对照 |
| 启动后所有网页都打不开 | 系统代理是否生效、DNS 是否能解析、默认出站是否有效 | 切换 Direct 或固定单个出站比较 |
| Global 能用，Rule 不能用 | 路由规则、规则集下载、选择器和默认出站 | 查看规则集缓存和日志，不要先重写整份配置 |
| 只有某个应用不能用 | 该应用是否遵循系统代理，是否需要 TUN | 先确认 TUN 权限，再排查应用自身网络设置 |
| 更新后出现 unknown field | 当前版本、字段迁移和弃用说明 | 备份配置后对照官方变更记录逐项迁移 |
sing-box 的配置字段会随版本发生迁移，官方变更记录列出了新功能、弃用字段和格式变化。当前文档还显示，部分旧 DNS 格式已被移除，旧配置不能因为“以前能用”就直接推断在当前版本仍然兼容。查看官方变更记录与官方弃用说明。
最小回滚顺序是：先关闭 TUN，再关闭系统代理，恢复备份配置，确保只有一个客户端运行，然后每次只改一个变量。记录配置文件、客户端、系统、节点、时间和日志原文，后续才能判断是格式、权限、DNS、路由还是连接本身的问题。
本文的适用边界
本文适合已经拥有订阅链接或本地 JSON 配置、希望完成 sing-box 基础设置的读者。它不提供任何真实节点、账号、密码、证书私钥或可直接使用的服务器地址，也不对具体订阅服务的价格、速度、稳定性和长期可用性作判断。
截至 2026-11-01，本文仅依据本次检索到的 sing-box 官方文档、官方客户端页面和官方项目资料整理。客户端名称、商店状态、配置字段和命令参数可能随版本变化，使用前应以当前页面和本机帮助输出为准。
常见问题
sing-box 可以直接导入所有订阅链接吗？
不能保证。先查看链接实际返回内容。符合当前 sing-box 配置结构的 JSON 才适合直接导入；YAML、编码文本、HTML 登录页或错误页不能直接按 JSON 使用。格式不明时先保存响应并运行配置检查。
sing-box 导入成功但启动后没有网络怎么办？
先确认系统代理或 TUN 是否真的生效，再检查 DNS 解析、默认出站和节点连接。关闭其他 VPN 与代理程序后，用单个出站或 Direct 做对照；如果 Global 能用而 Rule 不能用，重点检查规则和规则集。
Rule、Global、Direct 是 sing-box 必须有的三个模式吗？
不是。它们通常是部分图形客户端提供的界面概念，核心实际通过 route 规则、outbounds、选择器和默认出站工作。不同平台的按钮名称和可用功能可能不同。
什么时候应该使用 TUN？
当目标应用不遵循系统代理，或需要更完整接管系统流量时再考虑 TUN。首次设置建议先用系统代理完成验证，因为更容易确认效果，也更容易关闭回滚。
为什么配置检查提示 unknown field？
先备份配置并确认当前 sing-box 版本，再对照官方变更记录和弃用说明。unknown field 可能代表字段已迁移、被移除或层级写错，不建议不看上下文就直接删除。
Linux 上 sing-box 怎么启动本地配置？
先执行 sing-box check -c config.json，检查通过后使用 sing-box run -c config.json 前台运行。若使用 systemd，则查看服务状态和 journalctl 日志；命令参数应以当前构建的 sing-box help 为准。