如果你用 sing-box 搭过代理（服务端或手机/电脑客户端），手里大概率有一份从教程、面板或者订阅转换器里抄来的 config.json。sing-box 的更新节奏一直是"先废弃、隔一个版本删除"：某些在 1.12 就标上 deprecated 的字段，升到 1.14 会直接变成 FATAL，服务起不来。

这篇把升级 1.14 前必须处理的 6 个翻车点一次讲清，默认你第一次看：sing-box 是什么先简单说一句——它是开源代理软件内核，VLESS、Hysteria2、Trojan、Shadowsocks 都能用它跑，客户端和服务端共用同一套 JSON 配置。升级前养成一个习惯：先跑一遍 sing-box check -c config.json，它会告诉你哪些字段已经非法。

1. 旧式 DNS 服务器写法：1.14 彻底删除

最常见的翻车。1.11 时代的 DNS 配置长这样：

复制"dns": {
  "servers": [
    { "tag": "remote", "address": "tls://8.8.8.8" },
    { "tag": "local", "address": "223.5.5.5" }
  ]
}

address 这种写法在 1.12 被标记弃用，1.14 直接删除，配置校验会报 FATAL。必须拆成 type + server：

复制"dns": {
  "servers": [
    { "tag": "remote", "type": "tls", "server": "8.8.8.8" },
    { "tag": "local", "type": "udp", "server": "223.5.5.5" }
  ]
}

规则是：type 是协议（udp/tcp/tls/https/quic），server 只填主机名或 IP，别再带 :// 前缀。官方的完整迁移说明见 sing-box 迁移指南。

2. TUN 入站的 inet4_address：1.12 就没了

TUN 模式（接管手机/电脑全局流量）的老写法：

复制{ "type": "tun", "inet4_address": "172.19.0.1/30", "auto_route": true }

inet4_address / inet6_address 在 1.12 就已被删除，新写法是 address 数组，一次写全双栈：

复制{ "type": "tun", "address": ["172.19.0.1/30", "fdfe:dcba:9876::1/126"], "auto_route": true }

注意如果你的 TUN 只配了 v4，建议顺手把 v6 也加上——否则裸 IPv6 流量可能绕过隧道走物理网卡。

3. Hysteria2 端口跳跃：hop_ports 从来不存在

这个坑反直觉：很多面板和订阅转换器给 hy2 出站写 hop_ports: "20000-30000"，但 sing-box 的 hy2 出站里根本没有这个字段，写了会被静默忽略，端口跳跃等于没开。正确的字段是：

复制{ "type": "hysteria2", "server_ports": ["20000:30000"], "hop_interval": "30s" }

两处细节：server_ports 是数组，起止端口用冒号分隔（"20000:30000"，不是连字符）；hop_interval 必须是时长字符串 "30s"，写成裸数字会直接导致整个配置解析失败。官方字段说明见 Hysteria2 出站文档。

4. address_resolver 改名 + 补上 default_domain_resolver

配合第 1 点，DNS 服务器里的 address_resolver（用于解析 DoH 域名本身的 bootstrap 解析器）已改名为 domain_resolver。同时建议在 route 块里显式声明：

复制"route": { "default_domain_resolver": "local" }

不声明的话，1.14 会在启动日志里刷 "missing route.default_domain_resolver" 警告——能跑，但刷屏很烦。

5. 规则集下载：download_detour 换成 http_client

如果你的分流用远程规则集（remote rule_set），旧配置里可能有：

复制{ "type": "remote", "tag": "geosite-cn", "download_detour": "proxy" }

download_detour 在 1.14 被标记弃用，计划在后续版本删除。换成新写法：

复制"route": {
  "http_clients": [{ "tag": "proxy-dl", "detour": "proxy" }],
  "default_http_client": "proxy-dl"
}

规则集里不再需要每个都指定下载走哪个出站，统一由 default_http_client 接管。

6. DNS 的 independent_cache 弃用，顺手启用新特性

dns.independent_cache 在 1.14 被标记弃用（缓存现在默认按传输方式区分键，它已经没用了），配置里有就删掉。顺手可以把 1.14 新增的两个 DNS 选项加上：

复制"dns": { "optimistic": true, "timeout": "10s" }

optimistic 是"乐观缓存"：缓存条目刚过期时先返回旧结果、后台再刷新，页面打开体感更快；timeout 给每次 DNS 查询设定超时（默认 10 秒）。

升级前的自查清单

1. 备份旧配置再动手，出问题直接回滚。
2. 跑 sing-box check -c config.json：FATAL 级别必须清零，deprecated 警告尽量清掉——它们就是下个版本的 FATAL。
3. 不要从 1.11 一步跳到 1.14，先升到中间版本让 check 告诉你每一波的变化。
4. 面板/订阅转换器生成的配置，升级内核后重新生成一次，别指望旧模板自动适配。

sing-box 的文档更新很勤快，遇到拿不准的字段直接查 官方配置文档，比看第三方教程靠谱。之前写过一篇 VLESS+Reality、Hysteria2 与 VMess+WS 的实战对比，如果还在纠结装哪个协议，可以先看看那篇。