把 Pydantic v1 升到 v2，最省事的讲法，是把它写成一次方法名清洗：dict() 换成 model_dump()，parse_obj() 换成 model_validate()，测试重新跑一遍，任务便算结束。这样的讲法很顺手，也会漏掉真正决定迁移成本的部分。顺着官方迁移文档与当前概念文档往里看，Pydantic v2 的改动越过了表面方法名，也重新划分了验证逻辑所在的位置、模型钩子的表达方式，以及 settings 管理应当落在哪个包边界里。[1][2][3][4][5]
这层区别放到 2026 年也更重要，因为 Pydantic 早已越过“方便的 Python 小库”这一层，进入了基础设施位置。截至 2026-04-27T02:04:07Z UTC，GitHub API 显示 pydantic/pydantic 仓库有 27,596 stars、2,568 forks、559 个 open issues，最近一次 push 时间是 2026-04-24T07:37:12Z。[7] 最近几个版本标签仍然很密，v2.13.3 的日期是 2026-04-20，v2.13.2 是 2026-04-17，v2.13.1 是 2026-04-15，v2.13.0 是 2026-04-13。[8] 这已经是一条足够成熟的依赖链，迁移质量比迁移速度更值得关心。
配图说明：题图采用真实的编程工作台照片，把视觉重心放在迁移现场。这个选择贴近本文的实际落点：Pydantic v2 的设计决定，最终会变成应用代码里的验证器重写、API 改名、兼容过桥层与 settings 包边界。[5]
pydantic.v1 能买到时间，买不到终点
第一道迁移边界，落在兼容层。Pydantic 的迁移指南把这座桥写得很直白：V2 包里仍然通过 pydantic.v1 暴露 V1 API，而从 pydantic>=1.10.17 开始，V1 侧也能使用同一个命名空间，从而让 import 改写变得更平缓。[1] 这给团队提供了一条很实用的第一步。依赖可以先从 pydantic<2 松开，import 改到 pydantic.v1，项目便有了继续前进的余地，可以避开在同一批改动里同时翻过所有模型、验证器与框架接缝的压力。[1]
FastAPI 的迁移文档也把这条桥的现实价值照得更亮。框架在 0.119.0 版本里加入了对 Pydantic v2 内部 pydantic.v1 子模块的部分支持，目的正是让迁移可以分阶段进行。[6] 这条信号很有分量，因为它来自直接压在 Pydantic 模型语义之上的上层框架。[6]
不过，这座桥有一条很硬的边界。FastAPI 文档明确提醒，Pydantic v2 的 model 不能把 Pydantic v1 的 model 当成自己的字段类型，反向组合也同样不受支持。[6] 在这条边界上，pydantic.v1 适合放在模块边界、router 边界、应用边界上过渡；若把两套语义长时间揉进同一棵领域模型树里，风险会很快升高。很多团队在这里看见了一条“渐进迁移”路径，实际得到的却是同一张对象图里并存的两套验证语义。
同一节迁移指南还指向了 bump-pydantic 这把 beta 状态的 codemod 工具。[1] 把它看成排期工具，比把它看成迁移结论更合适。它很适合推平 import 与方法表面的工作量，真正决定迁移深浅的部分，仍然在项目内部依赖的那些 V1 语义上。
方法改名这一层，反而最容易收拾
Pydantic v2 确实改了很多常用方法名，迁移指南把映射表列得很清楚：copy() 改成 model_copy()，dict() 改成 model_dump()，json() 改成 model_dump_json()，parse_obj() 改成 model_validate()，update_forward_refs() 改成 model_rebuild()。[1] 文档也把 parse_raw() 与 parse_file() 标成 deprecated，把调用路径推向“先显式加载，再交给 model_validate() 或 model_validate_json()”。[1]
这些改名背后其实带着两层更深的含义。第一层，模型表面变得更规整了。第二层，验证入口与 I/O 便利函数被分得更开，项目希望开发者把加载、解析、验证这几件事说得更清楚。[1]
别的迁移缝也有同样气质。from_orm() 被折回 model_validate() 加 from_attributes=True 这一组配置表达里。[1][2] 旧时代的 __root__ 路径转交给 RootModel，普通类型验证则交给 TypeAdapter，许多以前绕路才能做的事情，在这里有了更直接的入口。[1] 这类变化都带着明确分工：model 处理 model，adapter 处理普通类型，属性式加载通过配置开关表达，不再继续依赖一条特殊方法通道。
真正容易出问题的地带，落在 validators 与 config
下一道边界，正是大多数团队真正花时间的地方。Pydantic 的迁移指南把 “changes to config” 和 “changes to validators” 单独拆开，这个结构本身就说明了问题。[1] 到了这里，迁移已经不像一次简单改名，更像一次语义重排。
先看 config。项目把方向收束到 ConfigDict，同时把几组高频开关换了名字：allow_population_by_field_name 对应 populate_by_name，从 v2.11 开始也可用 validate_by_name；orm_mode 对应 from_attributes；schema_extra 对应 json_schema_extra；validate_all 对应 validate_default。[1][2] getter_dict 也一并退出，因为它依附的 orm_mode 语境已经不存在了。[1] 许多框架级行为在 V1 里落在这些小开关上，迁移时自然会在这里反复返工。
validators 这一层也一样。V2 文档把新世界写在 field_validator() 与 model_validator() 这两个入口上，同时要求开发者为钩子声明更清楚的位置：before、after，以及其他 mode 选择，再配合 ValidationInfo 读取字段名、验证模式与已经通过验证的数据。[1][3] 这套系统更灵活，也要求开发者把“这个钩子该在验证流的哪一段出现”说得更清楚。[3]
许多迁移 bug 会集中在这里，原因也就在这里。代码依旧能跑，语义却未必已经对齐。一个原本依赖 V1 验证器签名的小钩子，一段以前搭在 root_validator 上的模型级假设，在 V2 里往往都需要重新安放位置。[1][3]
settings 拆包以后，运行时边界也跟着变了
最后一道边界，落在运行时，已经越过语法层。Pydantic v2 把 BaseSettings 从主包里拆了出去，交给 pydantic-settings。[1][4] 迁移指南直接点出了这一点，当前的 settings 管理文档又把它继续展开：settings 现在有自己的包、有自己的 SettingsConfigDict，还带着一套更明确的环境变量、dotenv、secrets 目录、嵌套分隔符与 CLI 解析能力。[1][4]
这个拆分有利于职责清晰，同时也改变了迁移顺序。settings-heavy 的项目已经不能把配置层继续看成 model 层旁边的一块附属区域。迁移它，往往连着依赖管理、环境加载测试与部署时行为校验一起移动。[4] 项目若依赖 .env、嵌套环境变量名，或者 secrets 目录，那么最值得尽早跑通的，正是这一层测试；等模型改名完成后再慢慢补，往往会把运行时偏差留到后段。
这也是迁移顺序最容易决定结果的地方。文档已经把 pydantic-settings 作为一套独立能力面写了出来。[4] settings 现在更像一个单独子系统。团队若先把模型层推过去，却把 settings 工作压在后面，线上环境里那些更难复现的偏差便很容易在最后出现。
最合适的迁移路径，与最容易走歪的路径
最干净的一次性迁移，适合一类比较窄的项目：大量使用普通 BaseModel，自定义 validator 不多，框架耦合较轻，测试又足够扎实。这样的代码库里，bump-pydantic 加迁移表，再配一轮有纪律的测试，通常就能把工作压下来。[1][6]
更常见、也更贴近工程现实的分阶段路径，适合另一类项目：FastAPI 路由、定制 validator、属性式加载、运行时 secrets 与环境变量规则，都在代码里深深咬合。对这类项目来说，pydantic.v1 最适合扮演短期 import 过桥层；先把表面 import 与依赖切过去，再分别处理 validator 语义、config 开关与 settings 包迁移，通常更接近项目节奏。[1][2][3][4][6]
最容易走歪的路径，则是把兼容层误认成迁移终点。Pydantic v2 之所以值得迁移，一部分原因正落在 pydantic-core、更清楚的职责划分，以及更显式的 model API 上。[5] 代码库若长期停在 pydantic.v1 上，拿到的是排期便利，核心设计红利还留在桥的另一边。
所以，对这次升级最有用的一句概括，会比“改几个方法名”更窄，也更准。Pydantic v1 到 v2 的迁移，更像三道边界同时改道：一座应该尽快撤掉的兼容桥，一套被重新说清楚的 validator 与 config 语义，以及一个需要单独对待的 settings 子系统。[1][2][3][4][5][6] 围绕这三道接缝排迁移，往往能得到一次真正完成的升级；围绕方法名排迁移，得到的更像一次停顿。
来源
- Pydantic 迁移指南：
pydantic.v1、bump-pydantic、模型 API 改名、config 键名变化、TypeAdapter，以及BaseSettings从主包迁出。 - Pydantic 配置文档：
ConfigDict、显式配置行为，以及 V2 风格的模型配置表面。 - Pydantic validators 文档：
field_validator、model_validator、验证模式与ValidationInfo。 - Pydantic settings 管理文档：
pydantic-settings、SettingsConfigDict、环境变量加载、dotenv 支持、secrets 目录与相关运行时行为。 - Samuel Colvin，《Introducing Pydantic v2 - Key Features》——
pydantic-core、Rust 验证核心、strict mode，以及 V2 背后的更深层架构动机。 - FastAPI 关于 Pydantic v1 到 v2 的迁移指南：渐进迁移支持、FastAPI 对
pydantic.v1的处理，以及 V1/V2 model 不可混用的提醒。 - GitHub API，
pydantic/pydantic仓库快照 —— 文章写作时的 stars、forks、open issues 与最近 push 时间。 - GitHub releases，
pydantic/pydantic—— 最近 v2.13.x 版本的发布节奏。