sing-box配置文件怎么编辑？从备份到启动验证的完整步骤

更新于 2026-10-20 · transocks.cyou

简答：sing-box 配置文件通常是 JSON。最快做法是：先确认当前内核版本和实际加载路径，备份原文件，使用支持 JSON 的编辑器修改，然后运行 format 和 check，最后重启客户端或 systemd 服务并查看日志。Remote Profile 不要当成本地文件长期手改，先另存为 Local 或修改远程配置源。

定义：sing-box 配置文件是用 JSON 描述日志、DNS、入站、出站和路由等运行参数的文件，不等同于单条节点链接、Clash YAML 或 Base64 节点列表。

30 秒速查：先判断配置类型，再决定编辑方法

如果你只是想尽快改一个字段，先按下面顺序操作：本地 JSON 先备份，再执行 format 和 check；Remote Profile 先确认 URL 更新来源，长期自定义时另存为 Local；Linux systemd 先运行 systemctl cat sing-box，确认服务实际使用的配置目录。sing-box 官方文档明确使用 JSON 配置，并提供 check、format 和 merge 命令，具体写法可核对官方配置文档。

配置类型与编辑方式速查

类型	你看到的内容	适合怎么改	主要风险
Local	设备上的完整 JSON	复制备份后，用 JSON 编辑器修改	语法错误或字段与内核版本不匹配
Remote	URL、远程 Profile 或订阅地址	查看内容；要长期自定义则另存为 Local，或修改远程配置源	自动更新可能覆盖本地改动
iCloud	iOS 或 macOS 的 iCloud Profile	在官方图形客户端的编辑器中修改	可能误改了另一个本地副本
单条节点链接	一行分享链接	先导入或转换为完整配置	不能直接当作完整 JSON 启动
Clash YAML 或 Base64 列表	YAML 文本或编码字符串	转换后逐项核对生成的 JSON	格式转换可能丢失规则、DNS 或路由设置

官方图形客户端规范把 Profile 分为 Local、iCloud 和 Remote：Local 是本地配置，iCloud 以 iCloud 作为更新来源，Remote 以 URL 作为更新来源，并支持自动更新；官方说明给出的 Remote 默认更新间隔为 60 分钟。编辑入口和按钮名称可能随版本变化，请以当前版本界面为准，可查看官方图形客户端通用说明。

按设备找到配置：入口、常见路径与覆盖风险

不同系统的“配置文件在哪里”并没有一个统一答案，关键是区分命令行运行、官方图形客户端和第三方封装。当前官方客户端列表包括 Android、Apple 平台、Windows 和 Linux 的 sing-box 图形客户端；因此，不能再把 Windows 或 Linux 一概写成“没有官方 GUI”。可先查看官方图形界面客户端列表。

设备与安装方式对照

设备	客户端或安装方式	常见配置位置	编辑入口	是否可能被覆盖
Windows	官方 sing-box for Desktop 或命令行	图形客户端的 Local Profile；命令行以启动参数为准	打开配置或 Profile 列表，选择 Local 后进入编辑器；命令行直接打开实际路径	Local 通常不会因远程更新覆盖；Remote 可能覆盖
macOS	官方 Apple 平台客户端、Homebrew 或命令行	Local 或 iCloud Profile；命令行以启动参数为准	在 Profile 列表中选择 Local 或 iCloud；iCloud 文件位于 iCloud 的 sing-box 文件夹	iCloud 和 Remote 都存在更新来源
Android	官方 Android 客户端或 Termux	图形客户端 Profile；Termux 以启动命令为准	在 Profile 页面选择 Local；Remote 先确认自动更新设置	Remote 可能覆盖手工改动
iOS	官方 Apple 平台客户端	Local 或 iCloud Profile	在 Profile 页面选择目标配置，再打开编辑器	iCloud 和 Remote 可能从外部来源更新
Linux	包管理安装、手动安装或 systemd	官方包常见配置文件为 `/etc/sing-box/config.json`；服务单元通常以 `-C /etc/sing-box` 加载配置目录	先用 `systemctl cat sing-box` 查看 `ExecStart`，再编辑实际路径	服务启动参数和目录中的多个配置文件会影响实际加载内容

Linux 的包管理资料列出了 /etc/sing-box/config.json 这一配置文件位置，官方服务单元则使用 -D /var/lib/sing-box -C /etc/sing-box run 启动。安装方式不同、手动部署或容器运行时路径可能不同，所以不要只凭教程猜路径，应以本机服务单元为准。可核对官方打包配置和官方 systemd 服务单元。

完整编辑流程：确认版本、备份、格式化、检查

下面流程适用于本地 JSON。菜单名称以当前版本界面为准；如果你编辑的是 Remote Profile，先导出或另存为 Local，否则后续自动更新可能把手工修改覆盖。

确认 sing-box 内核版本：命令行先执行下面的命令；图形客户端则在 Core 或关于页面查看当前 sing-box 版本。官方图形客户端规范要求 Core 区域显示当前 sing-box 版本。

sing-box version

字段变化较快，尤其是 DNS、路由和协议字段。确认版本后，应回到对应版本的官方配置页面，不要直接复制旧教程中的字段。

确认实际配置路径：普通命令行要看启动命令里的 -c、-C 和 -D；Linux systemd 先执行：

systemctl cat sing-box

-c 指定配置文件路径，-C 指定配置目录，-D 指定工作目录。官方变更记录显示，-c 支持多次传入，-C 可加载目录中的配置文件；这一能力在 sing-box 1.2-beta10 的变更记录中已有说明，可核对官方变更记录。如果服务单元使用 -C /etc/sing-box，不要只编辑某个不在该目录中的 JSON。

先备份：复制原文件，例如保存为 config.backup.json。备份文件不要上传到公开仓库、论坛或截图中。订阅 URL、密码、UUID、私钥、服务器地址和访问令牌都应视为敏感信息。
用 JSON 编辑器打开：键名和字符串使用英文双引号；对象使用大括号，数组使用方括号；同级项目之间用英文逗号分隔；最后一项不要多写逗号。标准 JSON 不要直接写 // 或块注释，也不要让编辑器把英文标点替换成中文标点。
只改目标字段：log 用于日志，dns 用于 DNS，inbounds 表示入站，outbounds 表示出站，route 表示路由。顶层字段和配置结构可在官方配置引言中核对。
先格式化：不需要工作目录时可以省略 -D；如果配置依赖相对路径，再填写实际目录，例如当前目录用 -D .。

sing-box format -w -c config.json
sing-box format -w -c config.json -D .

再检查：把 config.json 换成你实际的配置文件路径。不要把 config_directory 这样的占位符原样复制。

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

如果你使用的是 Windows 命令行，可将命令中的 sing-box 换成 sing-box.exe。format 主要整理 JSON 格式，check 用于读取并检查配置；两者都通过后，才进入重启步骤。

结构示意：理解 JSON 层级，不要把它当成节点订阅

下面是一个不含真实服务器、账号和节点信息的结构示意，用来观察括号、数组和 tag 的层级。它不是订阅模板，也不能替代与你的内核版本对应的完整配置；复制后仍应先执行 check。

{
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "final": "direct"
  }
}

这里的 inbounds 是本机接收流量的入口，outbounds 是流量发往何处的出口，route.final 指定没有被其他规则匹配时使用的出口。实际使用代理节点时，还需要根据当前版本文档添加有效的出站、DNS 和路由设置；不要把单条分享链接直接粘贴到 outbounds 数组外面，也不要把 Clash YAML 当作 JSON。

重启、查看日志与实际验证

通过 check 只说明配置能够被检查程序读取，不等于服务已经加载了这份文件。修改后要确认以下五项：配置检查无错误、重启使用了同一路径、日志没有持续报错、当前客户端选中了正确 Profile、实际访问结果符合预期。

Linux systemd 可以执行：

sudo systemctl restart sing-box
sudo journalctl -u sing-box --output cat -e
sudo journalctl -u sing-box --output cat -f

官方包管理文档列出了 systemd 的重启、历史日志和实时日志命令，可核对官方包管理与服务管理说明。如果重启后配置像是没有生效，先再次运行 systemctl cat sing-box，确认 ExecStart 的 -C、-c 和 -D，再对同一份配置运行 check。

Windows、macOS、Android 和 iOS 的图形客户端则要回到 Profile 列表，确认当前选中的是刚编辑的 Local 或 iCloud 配置，再停止并重新启动服务或 TUN。官方图形客户端的 Dashboard 用于查看运行状态、连接和流量等信息；如果配置使用了 Selector 或 URLTest，也要确认当前选择的出站组符合预期，可参考官方图形客户端通用说明。

错误关键词与排查顺序

错误关键词或现象	优先检查	处理方法
`invalid character`、`unexpected end`	引号、逗号、括号和中文标点	恢复备份，分段修改，再执行 `format` 和 `check`
`unknown field`	字段属于其他版本或其他客户端	删除未经确认的字段，按当前内核版本文档核对
`outbound not found` 或找不到出站	`route.final`、规则引用的 tag 与 `outbounds` 中的 tag	逐字检查名称、大小写和连字符是否完全一致
规则不生效	规则顺序、匹配条件和 `final`	先保留最少规则测试，再逐条恢复复杂规则
DNS 失败或域名无法解析	`dns.servers`、DNS 规则和引用的 tag	先确认基础配置能启动，再单独检查 DNS 链路
TUN 无法启动或权限错误	系统授权、客户端权限和平台支持	先关闭 TUN 验证基础配置，再根据当前系统提示处理权限
保存后重新出现旧内容	正在编辑 Remote Profile	改用 Local 副本，或修改远程配置源后再更新

本文是独立使用指南，不代表 sing-box 或相关服务的官方页面；具体客户端界面、订阅内容和账号信息请以对应官方说明为准。

常见问题