CnRocket

sing-box 订阅导入失败？先确认格式、Remote 和 VPN 启动

更新于 2026-10-24 · cn-rocket.site

简答：先确认服务商提供的是 sing-box 远程配置 URL 或原生 JSON，再添加 Remote 配置并启动 VPN；Clash YAML、Base64 和普通节点链接不能默认直接当作 sing-box 配置使用。

定义：sing-box 订阅通常是服务商提供的远程配置 URL，客户端按 URL 下载并更新 JSON 配置，而不是把任意节点链接直接当作原生配置。

30 秒判断卡：你拿到的内容能不能直接导入

先看内容类型，再决定导入方式。sing-box 官方文档明确说明，配置文件使用 JSON 格式；图形客户端的 Remote Profile 则以 URL 作为远程配置更新来源。可参考sing-box 配置文件引言和图形客户端通用功能说明。

订阅格式与处理方式速查
你手里的内容能否直接作为原生配置正确做法正常判定
服务商明确标注的 sing-box 远程配置 URL通常可以尝试客户端新增 Remote Profile，粘贴 URL 后更新能下载配置，显示更新时间或配置内容
本地 sing-box JSON 文件可以尝试选择 Local Profile 导入文件检查命令成功，且配置包含有效节点或出站
Clash 或 Mihomo YAML不能默认直接使用向服务商索取 sing-box 格式，或仅使用其明确支持的转换方式客户端能解析，而不是只有文件能下载
Base64 文本或普通节点链接不能默认直接使用回到服务商页面选择 sing-box 订阅类型以服务商适配说明和客户端实际更新结果为准
  1. 在你购买服务的服务商用户中心、订阅页面或客服提供的页面获取链接，入口以服务商官方说明为准。
  2. 优先复制明确标注为 sing-box 的订阅链接，不要只根据文件后缀或网页能否打开来判断。
  3. 把完整订阅 URL 当作账号凭据，不要发到群聊、截图、Issue 或公共文档中。
  4. 不要把完整 URL 直接写进命令参数，因为它可能进入 Shell 或 PowerShell 历史记录。

本文与 sing-box 项目及其开发者无隶属关系；客户端名称、下载入口和功能以sing-box 官方图形客户端列表为准。官方列表区分 Android、Apple 平台和 Desktop，也提示部分声称使用 sing-box 的第三方项目并不在官方列表中。

手机端怎么导入：Android、iPhone 和 iPad

Android 官方客户端可以管理并运行本地或远程 sing-box 配置，也提供 TUN 透明代理功能；官方页面列出的系统要求为 Android 5.0 及以上，下载入口包括 Play Store、GitHub Releases 和 F-Droid。具体应用入口和版本以官方页面为准，参考sing-box for Android 官方说明。

  1. 从官方客户端页面进入对应下载入口，注意辨别同名第三方应用。
  2. 打开应用，进入 Profiles、配置或类似名称的配置管理页面。
  3. 选择新增 Remote Profile，填写配置名称和服务商提供的 sing-box URL。
  4. 保存后手动更新一次，确认能下载配置并显示更新时间或配置内容。
  5. 回到 Dashboard 或运行页面，选择节点或分组，启动 VPN，并完成系统授权。
  6. 确认客户端显示运行中，再测试网页、DNS 和实际业务连接。

Apple 平台官方页面说明，SFI、SFM、SFT 可管理并运行本地或远程配置，覆盖 iOS、macOS 和 Apple tvOS；页面列出的要求为 iOS 15.0+、macOS 13.0+ 和 Apple tvOS 17.0+，并要求使用中国大陆以外的 Apple 账号。下载入口和应用名称可能随版本变化，应以sing-box for Apple platforms 官方说明为准。

  1. 打开官方页面确认当前平台对应的应用名称和下载方式。
  2. 进入 Profiles 或配置管理页面，新增 Remote Profile。
  3. 粘贴订阅 URL，保存并执行更新。
  4. 选择可用节点或分组，开启连接并完成系统 VPN 授权。
  5. 如果在 App Store 或 TestFlight 找不到应用，先核对 Apple 账号地区和官方页面，不要随意安装同名第三方应用。

Windows、Linux 和 macOS：Remote 与本地 JSON 怎么选

官方 Desktop 客户端可以管理并运行本地或远程 sing-box 配置，并提供平台相关的 TUN 功能；官方页面列出的桌面系统包括 Windows 10+ 和 Linux。macOS 使用 Apple 平台客户端或其独立版本，入口以官方页面为准，参考sing-box for Desktop 官方说明和sing-box for Apple platforms 官方说明。

桌面平台导入对照
平台导入方式启动前检查验收重点
Windows图形客户端新增 Remote 或 Local Profile启用 TUN、虚拟网卡或修改系统网络时，按提示以管理员身份运行；先退出其他 VPN、代理和 TUN 工具检查客户端运行状态、TUN 或系统代理状态，以及 DNS 是否正常
Linux图形客户端 Remote，或命令行运行本地 JSON涉及 TUN、路由或 DNS 接管时，可能需要更高权限；确认已安装 sing-box查看日志、路由和 DNS，确认配置确实在转发流量
macOSApple 平台客户端或官方独立版本首次启用系统网络扩展或 VPN 时按提示授权；不要同时运行多个网络接管工具确认 VPN 状态、节点可选、DNS 查询和目标业务连接

官方客户端列表使用 SFA、SFI、SFM、SFT 和 Desktop 等名称。它们并不是所有平台的同一个应用，下载前应以官方客户端列表核对平台、名称和入口，不要仅凭第三方页面的简称安装。

如果你拿到的是本地 JSON，可在配置目录中运行官方文档列出的检查和格式化命令。命令是否可用取决于已安装的 sing-box 版本，先用帮助命令确认：

  • sing-box --help：查看当前版本支持的命令和参数。
  • sing-box check：检查当前配置结构。
  • sing-box format -w -c config.json -D config_directory：按实际文件名和配置目录替换后格式化。
  • sing-box merge output.json -c config.json -D config_directory：按需合并配置文件。

上述命令来自sing-box 配置文件引言。正常标准不是“命令没有输出”，而是进程成功结束、没有 JSON 解析错误，并且配置中存在可用的出站或节点分组。

用 sing-box User-Agent 检查订阅，避免把返回格式判断错

订阅服务可能根据 User-Agent、请求头或授权状态返回不同内容，因此浏览器、curl 默认请求和客户端实际拉取的结果可能不一致。下面的命令只作辅助检查，最终以带 sing-box User-Agent 的请求或客户端实际更新结果为准；如果服务商要求额外请求头，应以服务商说明为准。

Linux 或 macOS 需要已安装 curl 和 Python 3。命令通过交互方式读取 URL，不把完整地址直接写进命令参数；输入内容仍可能出现在屏幕或终端记录中，因此不要在公共环境执行。

  • read -r -s -p "订阅 URL: " SUB_URL; echo
  • curl -A "sing-box" -fsSL "$SUB_URL" -o /tmp/sing-box-subscription.json
  • python3 -m json.tool /tmp/sing-box-subscription.json > /dev/null && echo "看起来是可解析 JSON" || echo "不是可直接解析的 JSON"
  • rm -f /tmp/sing-box-subscription.json

如果 Python 3 能解析，说明当前请求条件下返回内容具备 JSON 结构；如果失败，不要立即断定订阅失效，也可能是 YAML、Base64、登录页、错误页或需要额外请求头。检查结束后删除临时文件，因为返回内容可能包含节点凭据。

Windows PowerShell 5.1 建议使用 -UseBasicParsing。下面的输入使用安全字符串，避免直接回显 URL；它只降低屏幕显示风险，不等于订阅凭据已经安全。

  • $secure = Read-Host "订阅 URL" -AsSecureString
  • $ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
  • try { $subUrl = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr) }
  • $outFile = Join-Path $env:TEMP "sing-box-subscription.json"
  • Invoke-WebRequest -UseBasicParsing -Headers @{ "User-Agent" = "sing-box" } -Uri $subUrl -OutFile $outFile
  • try { Get-Content $outFile -Raw | ConvertFrom-Json -ErrorAction Stop | Out-Null; Write-Host "可解析 JSON" } catch { Write-Host "不是可直接解析的 JSON" }
  • Remove-Item $outFile -Force -ErrorAction SilentlyContinue

PowerShell 的 try/catch 会在 JSON 解析失败时输出明确结果，不会误报为成功。若之前把完整 URL 直接输入过命令行，可按需清理历史：PowerShell 执行 Clear-History 只清当前会话；若要删除 PSReadLine 保存的历史，可先执行 $historyPath = (Get-PSReadLineOption).HistorySavePath，再执行 Remove-Item $historyPath -Force。后一个命令会删除该历史文件，执行前确认不需要保留其他记录。

bash 中如果 URL 曾出现在某条历史命令里，先用 history 找到行号，再执行 history -d 行号，最后执行 history -w 写回历史文件；也可以用 history -c 清除当前会话历史。无论使用哪种方法，最稳妥的处理仍是回服务商页面撤销、重置或重新生成订阅凭据。

导入成功后的验收与报错排查

  1. 配置验收：Remote Profile 能完成更新，更新时间发生变化，日志没有 JSON 解析、认证或下载超时错误。
  2. 节点验收：能看到服务商提供的节点或分组。如果只有 direct、列表为空或没有可选分组，先检查订阅格式和服务商适配范围。
  3. 连接验收：客户端显示运行中，手机已完成 VPN 授权；Windows 使用 TUN 或虚拟网卡时已按提示以管理员身份运行。
  4. DNS 验收：先打开普通网页，再检查目标业务是否能解析和建立连接。网页能打开但特定应用不通时，继续检查 DNS、规则和应用自身代理设置。
  5. 日志验收：JSON、parse、timeout、authentication、no such host 等关键词只能作为经验性线索，不是官方一一对应的错误分类，最终应结合完整日志和复现步骤判断。
常见现象与处理顺序
现象先检查处理方式
JSON 解析失败返回内容、User-Agent、是否拿到网页错误页重新获取 sing-box 专用链接，不要只把 YAML 或 Base64 改名为 JSON
下载失败或超时URL 是否过期、网络是否可访问、是否需要额外请求头按服务商说明更新凭据，并在客户端日志中确认失败阶段
配置导入但节点为空配置是否真正更新、服务商是否限制客户端类型确认服务商提供的是 sing-box 适配配置，而不是其他客户端格式
字段弃用或启动失败配置使用的核心版本和报错字段查看sing-box 迁移指南和官方更新日志，让服务商提供适配当前版本的配置；不要自行猜测替代字段
启动后无法联网VPN 权限、TUN 状态、其他代理、DNS 和完整日志先关闭冲突的 VPN、代理和 TUN 工具，再逐项恢复配置

官方迁移指南显示，某些旧字段会被标记为 deprecated，后续版本可能移除或要求改用新结构。例如 TUN 的 stack 在官方迁移页面中已有版本迁移说明。因此，遇到“字段不存在”“启动拒绝”或类似报错时，先核对核心版本与配置来源，再让服务商重新生成适配配置，不要凭经验混用不同版本字段。

如果使用第三方订阅转换服务，完整订阅 URL 通常会交给该服务处理，存在凭据暴露风险。除非服务商明确要求并确认可信来源，否则不要把订阅 URL 粘贴到陌生转换站；如果已经使用，应按订阅泄露处理，删除相关配置并在服务商页面撤销、重置或重新生成凭据。

常见问题

Clash YAML 可以直接导入 sing-box 吗？

不能默认直接导入。sing-box 原生配置使用 JSON，Clash YAML 需要服务商提供 sing-box 格式，或使用服务商明确支持的转换方式；不要只把扩展名改成 .json。

为什么 curl 返回的内容和客户端看到的不一样？

订阅服务可能根据 User-Agent、请求头或授权状态返回不同格式。可以使用 User-Agent 为 sing-box 的请求辅助检查，但最终应以客户端实际更新结果和完整日志为准。

PowerShell 检查订阅时为什么总是显示成功？

如果没有使用 try/catch 和 -ErrorAction Stop，ConvertFrom-Json 失败后脚本可能继续执行。应使用带异常处理的写法，并在检查结束后删除临时文件。

导入成功但节点列表为空怎么办？

先确认 Remote Profile 是否真的更新成功，再检查返回格式、订阅有效性和服务商是否限制客户端类型。必要时重新获取明确适配 sing-box 的配置。

Windows 启动 sing-box 后没有网络怎么办？

先以管理员身份运行需要 TUN 或虚拟网卡权限的客户端，关闭其他 VPN、代理和 TUN 工具，再检查 VPN 授权、DNS、系统代理和完整日志。

第三方订阅转换服务用过后需要做什么？

第三方服务可能接触完整订阅 URL，应把它按凭据泄露处理。删除相关配置，并根据服务商提供的功能撤销、重置或重新生成订阅链接。

相关阅读

参考资料

  1. 引言｜sing-box 配置文件格式、检查、格式化与合并
  2. General｜sing-box 图形客户端通用功能与 Remote Profile
  3. sing-box for Android 官方说明
  4. sing-box for Apple platforms 官方说明
  5. sing-box for Desktop 官方说明
  6. Graphical Clients｜sing-box 官方图形客户端列表
  7. Migration｜sing-box 官方迁移指南
  8. Change Log｜sing-box 官方更新日志