sing-box 配置迁移不是把旧文件交给新程序试运行一次。可靠的方法是先核对起止版本之间的变更，再确认每个旧字段的新表达，最后通过语法检查和实际任务验证。检查通过只能说明配置被接受，不能替代路由、解析和连接行为的验收。
用起点和终点限定文档范围
先记录实际运行的 sing-box 版本，以及准备迁移到的版本。图形客户端内置的内核可能与系统命令行版本不同，不能拿命令行显示的版本去解释另一个应用的行为。必要时同时记录图形外壳版本及其内核更新说明。
官方迁移指南按版本列出变更，配置文档则说明当前字段。两者需要配合阅读：只看当前示例，不一定知道旧字段曾经承担什么含义；只看旧教程，也可能忽略字段已被弃用或移除。跨越多个版本时，应检查中间所有影响自身配置的变更，而不是只读最后一个发布说明。
把涉及自己的变化列成表，包含旧用途、新写法、依赖条件和验证任务。不需要把不使用的全部功能复制到迁移笔记。目标是覆盖自己的入站、出站、DNS、路由和规则集，而不是制作一份没有操作重点的文档摘要。
配置中的引用关系一起检查
配置不是一堆互不相关的字段。一个路由动作可能引用出站标签，DNS 路径可能依赖特定出站，规则集又可能需要先下载才能使用。只修改一处名称而忘记引用，会让文件表面整齐却无法按照原意运行。
迁移前画一个简短依赖图：请求从哪里进入，先用什么解析，匹配哪组规则，最终到哪个出口。标签名称使用稳定且有含义的命名，避免复制示例后留下多个相似名称。需要更换名字时，搜索所有引用并逐一核对。
不要将官方示例整段覆盖到生产配置。示例用于说明一种字段关系，未必包含自己的节点、认证和本地网络例外。应保留原有需求，只修改迁移必须改变的部分。完整备份需要保护凭证，公开讨论只使用脱敏片段。
先做检查，再做受控启动
官方配置文档提供检查能力。使用与目标运行环境相同的版本检查配置，记录全部错误和弃用警告，不要只截取最后一行成功信息。格式化可以改善可读性，但格式正确并不代表语义符合自己的需求。
通过检查后，在维护窗口停止旧实例，再启动新实例。避免两者竞争端口、虚拟接口和系统路由。若采用临时环境验证，确保监听位置和接管范围不影响正在使用的网络，不把实验配置直接设为自动启动。
一次只迁移一类变化会更容易定位。例如先恢复等价的 DNS 行为，再调整路由表达，最后考虑新特性。迁移和优化应分开：如果同时启用此前没有使用的功能，成功或失败都无法清楚归因。
建立覆盖实际用途的验证表
至少包含一个应直连的目标、一个应代理的目标、局域网访问以及需要的地址族。对每项记录预期出口和实际日志，不只看网页是否显示。网页可打开而路由错误，也属于迁移未达到目标。
示例中，配置检查通过，公共网站正常，但办公域名解析错误。此时应沿依赖图查看解析服务器、规则匹配和连接出口，不应立刻删除全部 DNS 配置。引导解析形成循环时，问题可能出现在任何业务请求之前，可阅读加密 DNS 引导解析。
再检查已有长连接与新连接的差异。切换配置前建立的连接可能继续沿旧路径工作，导致测试看似成功。应在受控条件下重新建立测试请求，并注明是否重启了对应应用。切勿用清除所有用户数据的方式强迫重连。
回退文件与程序必须成对
保存迁移前的程序版本信息、配置和规则资源状态。旧程序未必理解新文件，因此回退是恢复一套已知组合，而不是只替换可执行文件。先保留新版本的错误记录，再退回基线，避免丢失唯一的故障线索。
若回退也不能恢复，检查外部条件是否改变。订阅、证书、服务状态和网络环境可能与迁移同时变化。不要把时间上的先后直接当作因果；使用配置对照测试可以帮助缩小范围。
最后把已迁移字段、未使用功能、验证结果和剩余警告写成短记录。对于由图形客户端生成的配置，还需核对它是否会在下次启动时覆盖手工修改；相关维护方法见订阅与本地覆盖层。真正可维护的迁移，应在下一次重启和更新后仍然成立，而不只是当前进程暂时工作。
把警告分成必须处理与暂不涉及
可以为每条警告补上对应配置位置和处理决定。示例中，正在使用的解析字段即将移除，就需要迁移并验证；另一条说明针对自己没有启用的功能，则记录不适用，不必因此引入新配置。不要只为让日志看起来干净而删除仍承担业务用途的设置。
验证时保留一份离线可读的恢复说明。若新配置依赖联网下载规则，而下载本身又需要代理，应预先确认启动顺序和失败时的行为。重启电脑后无法取得资源，与已经缓存资源时能够运行，是两种不同条件。至少检查一次冷启动，才能发现这种只在维护之后出现的依赖问题。
参考资料
- sing-box 官方迁移指南，核验日期：2026-10-15。
- sing-box 配置与检查说明，核验日期：2026-10-15。本文不提供跨版本通用的配置片段。