升级 sing-box v1.14.3 后报错或无法使用怎么办？
简答：先不要反复重装：备份旧配置并确认实际运行版本，然后执行 sing-box check 检查 JSON 和字段兼容性，再根据日志重点排查 1.14 系列的 DNS、证书、macOS 客户端数据迁移及已废弃字段。v1.14.3 官方发布说明只写了修复与改进，无法据此断定某一个具体报错由该小版本单独引起。
定义：sing-box 升级后无法使用，通常是新版本不再接受旧配置、客户端数据未迁移、权限变化或运行的核心版本与配置要求不一致。
先判断：到底是版本问题、配置问题还是连接问题
升级 sing-box v1.14.3 后出现“无法启动”“配置无效”“启动后没有流量”或客户端界面打不开，处理顺序应当是先验证核心，再验证配置，最后才检查 DNS、路由和节点连接。官方 v1.14.3 发布页的说明只有“修复和改进”，没有列出一项可以覆盖所有用户的统一故障原因，因此不要把任何报错都简单归因于 v1.14.3。
先在终端执行 sing-box version，确认当前调用的二进制确实是 v1.14.3，而不是系统中残留的旧版本。随后记录配置文件路径、运行方式、操作系统、完整错误日志和升级前版本。图形客户端用户还应确认客户端实际使用的是哪个核心，以及远程配置是否在升级后重新下载。
| 现象 | 优先检查 | 不要先做的事 |
|---|---|---|
| 启动立即退出 | JSON 格式、字段名称、已移除或废弃字段 | 不要先更换节点 |
| 提示 legacy DNS 或 DNS server 错误 | DNS 配置格式、旧 DNS 字段迁移 | 不要只删除整段 DNS |
| macOS 升级后配置消失 | standalone 客户端数据迁移和权限提示 | 不要覆盖原数据目录 |
| 核心能启动但无法连接 | DNS、路由、TUN 权限、节点参数和系统代理 | 不要把配置错误误判为线路延迟 |
可先查看sing-box v1.14.3 官方发布说明，再对照官方迁移指南确认是否触发了 1.14 系列的兼容变化。
按这个顺序修复，避免越改越乱
- 备份原配置和运行目录。复制 config.json、订阅生成的本地文件、证书文件以及客户端数据目录。若配置来自远程订阅，先保存当前已下载的副本，避免重新拉取后无法对比。
- 确认配置文件能被读取。在配置文件所在目录执行
sing-box check -c config.json；如果你的构建不接受该参数，可先执行sing-box check，并参考当前版本的配置入口说明。官方文档明确提供了sing-box check检查命令，也提供了sing-box format -w -c config.json -D config_directory格式化方式。 - 一次只修一个报错。如果日志先提示 JSON 语法错误，先修逗号、括号、引号和重复键；如果提示未知字段或字段已废弃，再根据字段名称查官方文档。不要一次性删除 DNS、route、inbounds 和 outbounds，否则很难判断真正原因。
- 检查 1.14 系列的 DNS 迁移项。官方迁移文档指出，旧式 DNS 配置、旧地址过滤字段、
independent_cache、store_rdrc等项目需要按新格式处理。对于使用ip_version、query_type或地址规则的配置，还要留意是否需要用evaluate获取 DNS 响应，再通过match_response匹配。 - 检查证书和 ACME 配置。如果日志涉及
certificate_provider、ACME 或 TLS 字段，按 v1.14 的 TLS 文档迁移，不要把旧字段直接复制到新配置。证书路径、权限、域名和系统时间也要分别核对。 - macOS standalone 用户单独处理数据目录。官方迁移指南说明，Apple 平台客户端迁移到新的开发者账户后，macOS standalone 客户端不会自动继承旧应用的配置和设置。执行迁移命令前必须退出客户端并备份目录；如果不确定自己使用的是哪个应用版本，不要直接移动目录，先确认应用名称和数据路径。
- 配置通过后再检查连接。启动核心后观察日志是否出现监听成功、DNS 初始化成功和出站连接成功。若只是无法访问，依次关闭 TUN、系统代理或自定义 DNS 做最小化测试，再逐项恢复，区分是权限、DNS、路由还是节点参数问题。
官方配置文档还提供 JSON Schema：可以在配置中加入 "$schema": "https://sing-box.sagernet.org/schema.json"，或用 sing-box schema -o schema.json 生成与当前构建匹配的 Schema，帮助编辑器提示字段和检查结构。详情可查看配置文件说明与JSON Schema 文档。
常见报错的处理思路
提示 legacy DNS servers 或 DNS 配置无法启动
这类提示通常说明配置仍使用旧 DNS 格式，或旧字段与 1.14 引入的 DNS 规则写法混用。先保留原文件，复制一份测试配置，再对照迁移指南改写 DNS server、DNS rule 和缓存相关字段。independent_cache 已被标记为废弃，store_rdrc 应按官方说明评估是否改为 store_dns；不要只根据网上示例盲目替换，因为不同配置的 DNS 结构可能不同。
提示 unknown field、deprecated 或 removed
unknown field 通常表示当前版本不认识该字段，deprecated 表示暂时还能使用但不建议继续保留，removed 则表示已经不能继续使用。复制日志中的完整字段名，到官方文档对应章节搜索；如果字段来自第三方生成器或旧订阅转换器，还要检查转换器是否生成了旧格式。
核心启动成功但客户端没有网络
先确认是否有有效的入站、出站和 route 规则，再检查 TUN 或系统代理权限。Windows、macOS、Linux、Android 和 iOS 的权限机制不同，不能用某一平台的修复方式直接套用到另一平台。测试时可先关闭复杂规则和自定义 DNS，仅保留一个已知可用的出站，以便判断是规则匹配还是连接本身失败。
升级后配置文件不见了
如果是 macOS standalone 客户端，优先查看官方迁移指南中的数据目录迁移说明。其他图形客户端则检查配置存储位置、当前用户权限和远程配置是否重新导入。未确认目录归属前，不要删除旧目录或覆盖新目录。
什么时候适合回退，什么时候应该继续迁移
如果 v1.14.3 能通过 sing-box check，但实际运行时出现新的明确错误，建议先保留新版本日志，再用备份配置在旧版本环境中做对照测试。若旧版本也无法通过检查，问题更可能是配置文件本身；若旧版本正常、新版本只在某个字段报错，则应优先按官方迁移文档修复，而不是永久停留在旧版本。
回退前要记录二进制版本、配置版本、操作系统、启动命令和完整日志。不要混用新版本生成的配置、旧版本核心和第三方客户端的缓存文件。修复后再次执行配置检查，并进行一次最小化连接测试，确认核心能够启动、DNS 能解析、路由能匹配，最后再恢复复杂规则和 TUN 模式。
截至 2026-10-17，本文只依据官方发布页、官方迁移指南和官方配置文档整理；对于某个特定设备、第三方客户端或订阅转换器是否兼容 v1.14.3，如果没有对应版本说明，结论应标记为“未核实”。
常见问题
升级 sing-box v1.14.3 后一定要改配置吗？
不一定。v1.14.3 发布页只写明修复和改进，不能据此认定所有配置都必须修改。如果原配置能通过当前版本的 sing-box check 并正常启动，可以先保留；只有日志指出字段不兼容、DNS 格式错误或客户端数据未迁移时，才按对应文档处理。
sing-box check 应该怎么执行？
命令行核心通常可执行 sing-box check；如果需要指定文件，可尝试 sing-box check -c config.json。若命令行提示参数不适用，先查看当前构建的帮助信息，并确认终端调用的确实是目标版本。检查通过只代表配置可解析，不代表节点、DNS 或 TUN 一定可连接。
DNS 报错是不是换一个 DNS 就能解决？
不一定。1.14 系列涉及 DNS 配置结构和规则行为变化，错误可能来自旧字段、规则匹配方式或服务器定义格式，而不是 DNS 地址本身。应先按官方迁移指南确认配置格式，再做 DNS 连通性测试。
macOS 升级后找不到原来的配置怎么办？
先不要删除新旧目录。官方迁移指南说明，macOS standalone 客户端因开发者账户变化可能不会继承原配置和设置。退出应用、备份目录后，再根据官方命令迁移；不确定应用类型或路径时，先确认版本和目录归属。
配置检查通过但仍然无法使用怎么办？
继续分层排查：先确认核心进程和监听端口，再检查出站连接、DNS 解析、route 匹配、系统代理或 TUN 权限。关闭复杂规则并只保留一个出站做最小化测试，可以更快判断是配置逻辑问题还是网络连接问题。