从 FastAPI 0.68 升级到 0.100 版本时，最核心的破坏性变更风险主要来自于 Pydantic 版本的兼容性变化。FastAPI 0.100.0 是一个关键节点，它同时支持 Pydantic v1 和 v2，但后续版本如 0.119.0 引入了 pydantic.v1 子模块支持，而 0.126.0 则移除了对 Pydantic v1 的直接支持。因此，升级前必须确认项目中使用的 Pydantic 模型是否兼容 v2，建议固定 FastAPI 版本到特定最新版（如 0.100.0 或更高但低于 0.113.0），并在升级前完善测试套件，确保依赖项如 Starlette 和 Pydantic 的版本匹配，避免因语义化版本控制中的次要版本变更导致的不兼容问题。

关于 FastAPI 版本

关于 FastAPI 版本 🌐 由 AI 与人类协作翻译 本翻译由人类引导的 AI 生成。🤝 可能存在误解原意或不够自然等问题。🤖 你可以通过帮助我们更好地引导 AI LLM 来改进此翻译。英文版本 FastAPI 已在许多应用程序和系统的生产环境中使用。并且测试覆盖率保持在 100%。但其开发进度仍在快速推进。经常添加新功能，定期修复错误，并且代码仍在持续改进。这就是为什么当前版本仍然是 0.x.x，这反映出每个版本都可能有 Breaking changes。这遵循语义版本控制的约定。你现在就可以使用 FastAPI 创建生产环境应用程序 (你可能已经这样做了一段时间),你只需确保使用的版本可以与其余代码正确配合即可。固定你的 fastapi 版本¶ 你应该做的第一件事是将你正在使用的 FastAPI 版本“固定”到你知道适用于你的应用程序的特定最新版本。例如，假设你在应用程序中使用版本 0.112.0。如果你使用 requirements.txt 文件，你可以使用以下命令指定版本：fastapi[standard]==0.112.0 这意味着你将使用版本 0.112.0。或者你也可以将其固定为：fastapi[standard]>=0.112.0,<0.113.0 这意味着你将使用 0.112.0 或更高版本，但低于 0.113.0，例如，版本 0.112.2 仍会被接受。如果你使用任何其他工具来管理你的安装，例如 uv、Poetry、Pipenv 或其他工具，它们都有一种定义包的特定版本的方法。可用版本¶ 你可以在发行说明中查看可用版本 (例如查看当前最新版本)。关于版本¶ 遵循语义版本控制约定，任何低于 1.0.0 的版本都可能会添加 breaking changes。FastAPI 还遵循这样的约定：任何"PATCH"版本更改都是为了 bug 修复和 non-breaking changes。提示 "PATCH"是最后一个数字，例如，在 0.2.3 中，PATCH 版本是 3。因此，你应该能够固定到如下版本：fastapi>=0.45.0,<0.46.0 "MINOR"版本中会添加 breaking changes 和新功能。提示 "MINOR"是中间的数字，例如，在 0.2.3 中，MINOR 版本是 2。升级 FastAPI 版本¶ 你应该为你的应用程序添加测试。使用 FastAPI 编写测试非常简单 (感谢 Starlette),请参考文档：测试 添加测试后，你可以将 FastAPI 版本升级到更新版本，并通过运行测试来确保所有代码都能正常工作。（该信息的时间戳是 2026 年 4 月 17 日）

从 Pydantic v1 迁移到 Pydantic v2

从 Pydantic v1 迁移到 Pydantic v2 英文版本 如果你有一个较旧的 FastAPI 应用，可能在使用 Pydantic v1。FastAPI 0.100.0 同时支持 Pydantic v1 和 v2，会使用你已安装的任一版本。FastAPI 0.119.0 引入了在 Pydantic v2 内部以 pydantic.v1 形式对 Pydantic v1 的部分支持，以便于迁移到 v2。FastAPI 0.126.0 移除了对 Pydantic v1 的支持，但在一段时间内仍支持 pydantic.v1。警告 从 Python 3.14 开始，Pydantic 团队不再为最新的 Python 版本提供 Pydantic v1 的支持。这也包括 pydantic.v1，在 Python 3.14 及更高版本中不再受支持。如果你想使用 Python 的最新特性，需要确保使用 Pydantic v2。如果你的旧 FastAPI 应用在用 Pydantic v1，这里将向你展示如何迁移到 Pydantic v2，以及 FastAPI 0.119.0 中可帮助你渐进式迁移的功能。官方指南¶ Pydantic 有一份从 v1 迁移到 v2 的官方迁移指南。其中包含变更内容、校验如何更准确更严格、可能的注意事项等。你可以阅读以更好地了解变更。测试¶ 请确保你的应用有测试，并在持续集成 (CI) 中运行它们。这样你就可以升级并确保一切仍按预期工作。bump-pydantic¶ 在很多情况下，如果你使用的是未做自定义的常规 Pydantic 模型，可以将从 Pydantic v1 迁移到 v2 的大部分过程自动化。你可以使用同一 Pydantic 团队提供的 bump-pydantic。该工具会帮助你自动修改大部分需要变更的代码。之后运行测试检查是否一切正常。如果正常，你就完成了。😎 v2 中的 Pydantic v1¶ Pydantic v2 以子模块 pydantic.v1 的形式包含了 Pydantic v1 的全部内容。但在 Python 3.13 以上的版本中不再受支持。这意味着你可以安装最新的 Pydantic v2，并从该子模块导入并使用旧的 Pydantic v1 组件，就像安装了旧版 Pydantic v1 一样。Python 3.10+ frompydantic.v1importBaseModelclassItem(BaseModel):name:strdescription:str|None=Nonesize:float FastAPI 对 v2 中 Pydantic v1 的支持¶ 自 FastAPI 0.119.0 起，FastAPI 也对 Pydantic v2 内的 Pydantic v1 提供了部分支持，以便迁移到 v2。因此，你可以将 Pydantic 升级到最新的 v2，并将导入改为使用 pydantic.v1 子模块，在很多情况下就能直接工作。Python 3.10+ fromfastapiimportFastAPIfrompydantic.v1importBaseModelclassItem(BaseModel):name:strdescription:str|None=Nonesize:floatapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item)->Item:returnitem（2026 年 4 月 3 日）

FastAPI 版本控制终极指南：语义化版本管理最佳实践

FastAPI 版本控制终极指南：语义化版本管理最佳实践 为什么语义化版本对 FastAPI 至关重要？语义化版本 (SemVer) 是 FastAPI 版本控制的核心原则。根据 FastAPI 官方文档中的部署/版本说明，FastAPI 目前仍处于 0.x.x 版本阶段，这意味着每个次要版本 (MINOR) 都可能包含不兼容的变更。FastAPI 遵循标准的语义化版本规范：主版本 (MAJOR):重大变更，不向后兼容 次要版本 (MINOR):新增功能，可能不向后兼容 补丁版本 (PATCH):错误修复，向后兼容 FastAPI 自动生成的 Swagger UI 界面，良好的版本控制确保 API 文档的稳定性 FastAPI 版本锁定策略：保护你的生产环境 1. 精确锁定版本号 在您的 requirements.txt 或 pyproject.toml 中，明确指定 FastAPI 版本是首要任务。例如：fastapi[standard]==0.135.2 txt 这种精确锁定确保您的应用始终使用已知的、经过测试的版本。2. 使用版本范围锁定 更灵活的锁定方式是使用版本范围，这在 fastapi/init.py 中定义的当前版本 0.135.2 基础上：fastapi[standard]>=0.135.0,<0.136.0 txt 这种方法允许自动获取安全补丁 (PATCH 版本更新),同时防止不兼容的次要版本更新。3. 检查项目配置 查看 FastAPI 项目的 pyproject.toml，可以看到项目的依赖管理配置：dependencies = [ "starlette>=0.46.0", "pydantic>=2.9.0", "typing-extensions>=4.8.0", "typing-inspection>=0.4.2", "annotated-doc>=0.0.2", ] toml 升级 FastAPI 版本的完整流程 第一步：建立测试套件 在升级任何版本之前，确保您的应用有完善的测试覆盖。（撰于 2026 年 3 月 27 日）

FAQ

FastAPI 0.100.0 是否支持 Pydantic v1？

FastAPI 0.100.0 同时支持 Pydantic v1 和 v2，会使用你已安装的任一版本。

升级 FastAPI 版本前应该做什么？

你应该为你的应用程序添加测试。添加测试后，你可以将 FastAPI 版本升级到更新版本，并通过运行测试来确保所有代码都能正常工作。

如何固定 FastAPI 版本？

你应该做的第一件事是将你正在使用的 FastAPI 版本“固定”到你知道适用于你的应用程序的特定最新版本。例如，假设你在应用程序中使用版本 0.112.0。如果你使用 requirements.txt 文件，你可以使用以下命令指定版本：fastapi[standard]==0.112.0