Mac下Python3.13运行FastAPI报错：ForwardRef._evaluate()缺失recursive_guard参数

你遇到的TypeError: ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard'错误，核心是Python 3.13对类型系统的更新，和你当前使用的旧版本FastAPI、Pydantic不兼容——旧版Pydantic（1.10.7）没有适配Python 3.13新增的recursive_guard参数要求，导致加载依赖时触发异常。

方案1：升级依赖到兼容Python 3.13的版本 #

这是最彻底的解决方式，直接更新核心依赖以适配Python 3.13：

• 修改requirements.txt中的关键版本：

  # 替换原有版本
  fastapi>=0.110.0
  pydantic>=2.5.0
  starlette>=0.27.0
  

• 执行依赖更新：

  (venv) pip install --upgrade -r requirements.txt
  

注意：Pydantic 2.x相比1.x有部分语法调整，比如BaseModel的配置方式、字段验证逻辑，但FastAPI 0.100+已完全适配Pydantic 2.x，大部分业务代码无需大幅修改。

方案2：降级Python版本到3.12及以下 #

如果暂时不想升级依赖，可以将Python版本降到和原有依赖兼容的3.12或3.11：

1. 卸载当前的Python 3.13
2. 安装Python 3.12（推荐用pyenv管理多版本，避免系统Python冲突）
3. 重新创建虚拟环境并安装依赖：

   pyenv local 3.12.0
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

• fastapi-jwt-auth==0.5.0已停止维护，建议替换为pyjwt+passlib或python-jose实现JWT认证，避免后续出现更多兼容问题
• 始终使用虚拟环境管理项目依赖，避免全局包冲突

内容的提问来源于stack exchange，提问作者Zaid