文章
sing-box 更新后配置报错？按版本迁移而不是盲删字段
sing-box 更新后出现配置错误，不一定是订阅服务突然失效。程序版本、配置格式和客户端外壳可能分别变化；先确定错误来自哪一层，再决定修改哪部分。
本文以官方迁移文档为依据，资料核对日期为 2026 年 9 月 28 日。文档可能包含多个版本及预发布迁移项，不应把页面顶部的版本标题自动当成当前稳定版。
先记录三个版本信息
记录图形客户端版本、实际运行的 sing-box 内核版本，以及配置的来源或生成日期。有些客户端会打包特定内核，客户端版本号与内核版本号并不相同。
如果服务提供专门的订阅格式，还要核对它声明支持哪个客户端或内核范围。只有“这是 sing-box 配置”一句话，不足以确认跨版本兼容。
区分警告、校验失败与运行失败
| 阶段 | 现象 | 处理重点 |
|---|---|---|
| 迁移提醒 | 弃用警告，但当前仍能运行 | 记录未来移除条件，计划迁移 |
| 配置校验 | 字段未知、类型错误、引用不存在 | 按错误路径核对格式 |
| 运行阶段 | 校验通过，连接仍失败 | 检查路由、解析与实际网络 |
不要把所有提示都归为“版本不兼容”。也不要认为校验通过就证明出口、DNS 和规则完全符合自己的预期。
官方文档中的一个具体例子
官方迁移页列有从 1.12.0 起的新 DNS 服务器格式迁移，以及多个后续变更。读者应找到与自己升级跨度对应的条目，核对旧字段、新结构和移除时点。
这个例子说明的是阅读方式，并不表示每份配置都只需要修改 DNS。跳过多个版本时，可能涉及多项累计变更，不能只搜索最后一行错误后套用陌生模板。
一次可恢复的迁移流程
- 保存当前可用配置及其适用版本，确认能够恢复。
- 复制一份作为迁移副本，保留原件不动。
- 对照当前版本的配置文档与迁移条目，先解决格式和引用问题。
- 用当前工具提供的配置检查功能验证副本，保留完整错误路径。
- 启动后依次测试直连目标、代理目标、DNS 和需要的应用范围。
- 记录成功条件，再决定是否替换日常配置。
不建议直接删除报错字段直到程序启动。某个字段可能原本承担分流或解析作用，删除后虽然能够运行，行为却改变了。
远程订阅与本地修改要分清
若错误来自服务生成的订阅，应优先向服务方报告实际版本与脱敏错误。直接编辑下载文件可能在下次更新时被覆盖，造成“修好后又坏了”的循环。
需要保留个人改动时，先确认客户端支持何种持久覆盖方式。不要假设其他客户端的脚本或合并机制在当前工具中也适用。
提交问题时提供最小材料
建议包含：客户端与内核版本、升级前后版本、错误字段路径、发生阶段，以及删除凭据后的最小配置片段。不附完整订阅链接、密钥或全部节点库。