sing-box macOS 配置文件：从导入到启动的完整指南
简答：sing-box macOS 配置文件必须是完整的 JSON 配置，不能直接把 Clash YAML、单条节点链接或普通节点列表当作配置文件导入。新手建议先使用 SFM 图形客户端导入本地 JSON 或远程配置；需要命令行运行时，再用 sing-box check 校验配置，并按“编辑—保存—校验—重新载入—查看日志—验证业务”的顺序排查。
定义：sing-box macOS 配置文件，是由 sing-box 使用的 JSON 文件，包含日志、DNS、入站、出站和路由等配置段。
先判断：你手里的文件能不能直接导入
本文是第三方使用指南，不代表 sing-box 项目或任何服务商的官方页面。sing-box 官方配置结构使用 JSON，常见顶层字段包括 log、dns、inbounds、outbounds 和 route。因此，文件扩展名叫 .json 只是外观，真正能否运行还要看字段结构是否符合当前版本文档。
| 你手里的内容 | 能否直接作为 sing-box 配置 | 正确处理方式 |
|---|---|---|
| 完整 sing-box JSON | 可以，先校验 | 导入 SFM 本地配置，或使用命令行检查 |
| Clash YAML | 不可以直接使用 | 使用支持 sing-box 的转换工具生成完整 JSON，再人工核对 |
| 单条节点链接 | 不可以直接使用 | 根据协议字段写入对应 outbound |
| 订阅链接 | 通常不是配置文件本体 | 作为远程 Profile 导入，或先生成 sing-box JSON |
| 只有服务器、端口、UUID 的节点列表 | 通常不完整 | 补齐协议、TLS、传输层和路由字段 |
官方图形客户端将配置分为 Local、iCloud 和 Remote Profile。Remote Profile 以 URL 作为更新来源，客户端可以按配置更新周期重新获取内容；本地文件则需要你自己保存、备份和替换。可参考 sing-box 通用客户端文档。
macOS 客户端怎么选：SFM 还是命令行内核
如果你需要菜单栏开关、配置分组、TUN 权限和运行状态展示，优先选择 sing-box for macOS 的独立版图形客户端，简称 SFM。官方 Apple 平台页面列出的 macOS 要求为 macOS 13.0 或更高版本，并提供 Homebrew Cask 和 GitHub Releases 入口。需要注意的是，图形客户端和命令行内核不是同一个使用方式：前者适合日常导入和切换配置，后者适合脚本、服务器式运行和终端日志查看。详情见 sing-box for Apple platforms。
| 场景 | 建议选择 | 注意事项 |
|---|---|---|
| 第一次使用 macOS 客户端 | SFM 图形客户端 | 需要允许网络扩展或 VPN 相关权限 |
| 想导入本地或远程配置 | SFM | 配置内容必须是完整 JSON 或可识别的远程 Profile |
| 需要终端自动化 | Darwin 命令行内核 | 自行管理配置路径、进程和日志 |
| Apple Silicon Mac | Apple/arm64 安装包 | 适用于 Apple 芯片设备 |
| Intel Mac | Intel/x86_64 安装包 | 适用于 Intel 处理器设备 |
| 不确定设备架构 | Universal 通用包 | 文件通常更大，但兼容两类 Mac |
可以在 macOS“关于本机”中查看芯片信息：显示 Apple 芯片时选择 Apple 版本，显示 Intel 处理器时选择 Intel 版本。无法确认时使用 Universal 包，或先打开终端执行 uname -m：返回 arm64 通常对应 Apple Silicon，返回 x86_64 对应 Intel。
先用这份最小 JSON 配置测试文件是否可运行
下面的模板只包含日志、DNS、混合代理入站、TUN 入站、直连出站和基础路由，适合先验证配置文件格式、客户端权限和本机网络。它不会凭空生成远程节点；如果要连接某个远程服务，必须把服务商提供的完整 outbound 按官方字段补入，不能把示例地址当成真实节点。
带说明版结构：
{
"$schema": "https://sing-box.sagernet.org/schema.json",
"log": {
"level": "info",
"timestamp": true
},
"dns": {
"servers": [
{
"tag": "local",
"address": "local"
}
],
"final": "local",
"strategy": "prefer_ipv4"
},
"inbounds": [
{
"type": "mixed",
"tag": "mixed-in",
"listen": "127.0.0.1",
"listen_port": 2080
},
{
"type": "tun",
"tag": "tun-in",
"address": ["172.18.0.1/30"],
"auto_route": true,
"strict_route": true,
"dns_mode": "hijack"
}
],
"outbounds": [
{
"type": "direct",
"tag": "direct"
},
{
"type": "block",
"tag": "block"
}
],
"route": {
"auto_detect_interface": true,
"final": "direct"
}
}复制时不要把说明文字、Markdown 代码围栏或中文注释放进 JSON。这个模板中的 mixed 入站同时提供 SOCKS 和 HTTP 服务；官方文档说明，未设置用户认证时不会要求用户名和密码。TUN 的 auto_route 用于将默认路由指向 TUN，strict_route 会收紧路由处理；相关字段应结合当前版本文档使用，见 TUN 入站文档。
macOS 导入本地或远程配置：按这 6 步操作
- 备份原文件。把现有 JSON 复制一份，例如保存为
config.backup.json。订阅 URL、UUID、密码、Reality 私钥或 API secret 不要发布到论坛、截图或公开仓库。 - 准备配置。本地配置保存为 UTF-8 编码的
.json文件；远程配置则确认 URL 返回的是完整 sing-box JSON，而不是网页、登录页、Clash YAML 或单条节点文本。 - 导入 Profile。在 SFM 中添加 Local Profile 选择本地文件；需要远程更新时选择 Remote Profile 并填入配置 URL。官方通用客户端文档也定义了远程 Profile 的 URL Scheme，但菜单名称可能随客户端版本变化。
- 保存后校验。如果使用命令行内核，在配置文件所在目录执行
sing-box check -c config.json。官方配置文档将sing-box check列为配置检查命令；校验无错误后再启动，不要跳过这一步。参考 sing-box 配置结构与命令文档。 - 重新载入并授权。在 SFM 中停止后重新启动 Profile；首次启用 TUN 时，按 macOS 弹窗允许网络扩展、VPN 或辅助服务权限。若权限被拒绝，先到“系统设置—隐私与安全性”检查相关提示，再重新启动客户端。
- 查看日志并验证业务。先看服务是否启动、DNS 是否有响应、出站是否被选中，再测试浏览器或终端访问。只看到 TUN 已建立，不代表远程出站一定可用。
订阅、节点和分组应该放在哪里
一个可运行的 sing-box 配置通常至少要解决三件事：入站接收本机流量，outbound 定义直连或远程连接，route 决定流量最终交给哪个 outbound。只有节点地址而没有完整 outbound 字段时，配置仍可能无法启动或无法建立连接。
- 只有一个远程出口：将远程 outbound 加入
outbounds，再把route.final改为对应的 tag。 - 需要手动切换：使用
selector，其候选项必须引用已经存在的 outbound tag。 - 需要自动测试：使用
urltest，并填写候选 outbound、测试 URL、间隔和容忍延迟。官方文档说明，urltest的outbounds为必填字段，空测试 URL 时会使用默认地址。参考 URLTest 出站文档。 - 需要按域名或地址分流：在
route.rules中匹配域名、IP、入站或规则集，再通过规则动作指定 outbound。规则顺序很重要，越具体的规则通常应放在更前面。
不要直接把 Clash 的 proxy-groups、rules 或 YAML 顶层字段粘贴进 sing-box JSON；两套配置格式和字段命名不同，必须经过转换并逐项检查。
TUN 与 DNS：macOS 上最容易混淆的字段
dns_mode 属于 TUN 入站字段，不等同于 DNS 配置段中的 strategy、servers 或 DNS 规则。官方文档说明，TUN 的 dns_mode 可为 disabled、native 或 hijack；启用 auto_route 时默认使用 hijack。因此，不要把 dns_mode 随意放到 dns 段，也不要把它当成 fake-ip 或 redir-host 开关。
| 检查项 | 建议观察结果 | 异常时下一步 |
|---|---|---|
| TUN 状态 | 接口建立，服务没有立即退出 | 检查权限、地址格式和版本字段 |
| DNS 日志 | 查询被处理且有响应 | 检查 DNS server、hijack 设置和路由顺序 |
| IPv4/IPv6 | 至少一种地址族能稳定访问 | 临时设置 prefer_ipv4 对比 IPv6 影响 |
| 规则命中 | 日志显示预期 outbound tag | 检查规则顺序、域名匹配和最终出口 |
| 代理模式 | 浏览器或终端请求能完成 | 先用 mixed 入站测试，再启用 TUN |
如果 TUN 能启动但网页打不开，先关闭 TUN，只保留本地 mixed 入站，用支持代理的应用测试 127.0.0.1:2080。若 mixed 可用而 TUN 不可用，问题通常集中在网络扩展权限、DNS 劫持、默认路由或 IPv6；若 mixed 也不可用，则先检查出站字段和远程服务连通性。
升级后配置失效或丢失，怎么处理
sing-box 1.14 的 macOS 独立版涉及 Apple 开发者账号迁移，官方迁移文档明确提醒：新的独立版应用不会自动继承旧应用的 Profile 和设置。升级前应导出或复制配置，升级后重新添加 Local 或 Remote Profile。具体迁移命令应严格按官方迁移页执行，不要直接删除旧目录。
sing-box 1.15 还调整了 TUN stack 行为：官方迁移文档要求移除旧配置中的 stack 字段，因为自 1.15 起 sing-tun 使用自己的 TCP/IP stack，旧字段已被弃用。换句话说，不能继续照抄含有 "stack": "system" 的旧模板；先备份，删除该字段，再执行 sing-box check。可核对 sing-box Migration 文档。
常见错误与排查顺序
- JSON 解析错误：检查最后一个字段后是否多了逗号、字符串是否使用英文双引号、数组和对象括号是否成对，再运行
sing-box check -c config.json。 - 导入后没有分组：确认配置中确实存在
selector或urltest类型的 outbound，并且其引用的 tag 都已定义；只有一个 direct 出站时不会出现节点切换组。 - 服务启动后没有流量：先检查
route.final是否指向可用 outbound，再查看远程出站的服务器地址、端口、认证和 TLS 字段。 - TUN 开关自动关闭：查看 macOS 权限提示、客户端日志和配置校验结果；必要时先用 mixed 入站验证配置，再重新申请网络扩展权限。
- 升级后突然不能用：先确认客户端版本，再对照 Migration 文档检查 Profile 是否迁移、旧的
stack是否仍存在，以及配置是否使用了已废弃字段。
结论：一份合格的 macOS 配置文件应满足什么条件
合格的 sing-box macOS 配置文件至少应满足：文件是完整 JSON；inbounds、outbounds 和 route 的引用关系完整；DNS 字段放在正确配置段；TUN 字段符合当前版本；敏感信息没有公开；导入后经过配置校验、重新载入、日志检查和实际联网验证。
如果你只是想先确认客户端能否运行，可以从本文最小模板开始；如果你已经有远程订阅，则优先判断它返回的是完整 sing-box JSON 还是其他格式，再决定直接导入、转换或手动补齐。版本更新后不要继续沿用未经核对的旧模板，尤其要检查 TUN 和 Profile 迁移变化。
常见问题
sing-box macOS 配置文件应该是什么格式？
应当是符合当前 sing-box 配置结构的完整 JSON，通常包含 log、dns、inbounds、outbounds 和 route 等字段。Clash YAML、单条节点链接和普通节点列表不能直接当作完整配置使用。
macOS 上 sing-box 配置文件放在哪里？
使用 SFM 图形客户端时，可以作为 Local Profile 导入，也可以添加为 Remote Profile；命令行运行时则由启动命令通过 -c 指定文件路径。不要只依赖固定目录，因为不同客户端和安装方式可能使用不同工作目录。
为什么 JSON 配置导入后没有节点或分组？
检查 outbounds 中是否真的有远程 outbound，以及是否存在 selector 或 urltest 分组。只有 direct 出站时，客户端不会凭空生成节点列表；订阅内容也必须是完整 sing-box JSON。
sing-box macOS 开启 TUN 后无法联网怎么办？
先停止 TUN，使用 mixed 入站测试本地代理是否可用；再检查网络扩展权限、dns_mode、auto_route、route.final、DNS 日志和 IPv6。若配置含有旧版 stack 字段，还应按照 Migration 文档核对版本兼容性。
升级 sing-box 后原来的配置不见了怎么办？
先不要删除旧应用数据，检查是否从旧版 macOS 独立客户端迁移到新版应用。官方 Migration 文档说明 1.14 独立版的 Profile 和设置不会自动继承，升级前应备份，升级后重新添加本地或远程 Profile。
相关阅读
- 先学会在 macOS 中显示配置文件和资源库目录
- 如果你还在比较其他 macOS TUN 客户端，可看这篇开关与权限排查
- 需要处理另一种 macOS 订阅导入流程时，可参考这份排查指南
- 返回站内指南，继续查看客户端与网络连接问题