需显式执行兼容性转换而非重试或删字典；确认版本号后运行 migrate_schema 工具，检查字段映射、白名单配置、编码与工具链一致性。
升级时 restore 报错 “schema version mismatch” 怎么办
这不是数据损坏，是字典结构版本和当前代码期望的不匹配。核心动作不是重试，而是显式触发兼容性转换。
- 先确认报错里提到的具体版本号，比如
expected schema v3, got v2—— 这说明旧字典用的是 v2 结构，但新代码只认 v3 - 别直接删旧字典重导；v2 到 v3 的字段映射、默认值填充、废弃字段清理必须由转换逻辑完成
- 检查项目中是否存在
migrate_schema或upgrade_dict类函数，它们通常在dict/或storage/目录下，不是自动调用的 - 手动执行转换：比如运行
python -m dict_tool upgrade --from v2 --to v3 /path/to/dict.json，路径和参数名以你实际工具为准
DictLoader.load() 在新环境里返回空或 key 错乱
加载器没报错，但数据不对，大概率是字典文件里的字段名或嵌套层级被新版解析逻辑改写了。
- 对比新旧版本的字典 JSON 结构：重点看顶层键（如从
entries改成items）、布尔字段是否转成了字符串（"true"vstrue） - 检查
DictLoader初始化时是否传了compat_mode=True或类似开关；有些库默认关闭兼容模式，必须显式开启 - 如果用了缓存（如
.dict_cache文件），删掉它再试；缓存可能固化了旧解析结果 - 注意 Python 版本影响：3.9+ 的
dict保证插入顺序，老版本依赖collections.OrderedDict，若字典依赖顺序，升级后需补sort_keys=False参数
自定义字段在升级后丢失，extra_fields 不生效
旧字典里写的 "x_priority": 5，新版本加载后完全不见，不是被过滤，是字段白名单机制变严格了。
- 新版通常把
extra_fields改成 opt-in 模式：默认只认预定义字段，要保留扩展字段得配allow_unknown=True或strict=False - 检查加载器构造时传的 schema 类型，比如从
BaseSchema换成StrictSchema，后者会静默丢弃未知字段 - 如果字段名含下划线（如
x_type），确认新版本是否启用了 snake_case → camelCase 自动转换，导致你的字段被重命名成xType - 别依赖文档里“向后兼容”的说法——实际行为要看
CHANGELOG.md里Breaking changes小节，尤其留意dict,schema,loader相关条目
升级脚本跑通但线上恢复仍失败，ValidationError 提示字段类型不符
本地测试能过，线上报 Expected int, got str，通常是环境差异放大了隐性不兼容。
- 检查线上 Python 或 Node.js 版本是否触发了某次类型推断逻辑变更（例如 Pydantic 1.x → 2.x 对
None和空字符串的处理差异） - 确认字典文件编码：Windows 环境生成的 UTF-8 with BOM 可能让新版解析器把
"id"识别成"\ufeffid"，字段名对不上就走默认值逻辑 - 验证工具链一致性：生成字典用的
dict-builder v1.4，而线上加载用的是v1.5，二者对浮点数精度（如3.0vs3）的判定可能不同 - 最稳妥的兜底方式：用旧版工具导出为中间格式（如 YAML），再用新版工具导入，绕过二进制或 JSON 解析层的微妙差异
版本跳得越大，schema 转换越不能靠“试试看”。关键不是升级动作本身，而是清楚知道哪一行代码、哪一个配置项、甚至哪一个字节序，在哪个环节悄悄改了语义。
