FastAPI-Mail配置ConnectionConfig提示TEMPLATE_FOLDER不存在如何解决

问题核心表现 #

初始化ConnectionConfig时触发Pydantic校验错误，核心报错信息：

conf = ConnectionConfig(
  File "pydantic/env_settings.py", line 38, in pydantic.env_settings.BaseSettings.__init__
  File "pydantic/main.py", line 341, in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError: 1 validation error for ConnectionConfig
TEMPLATE_FOLDER
  file or directory at path "/Users/abushoeb/myproject/templates" does not exist (type=value_error.path.not_exists; path=/Users/abushoeb/myproject/templates)

排查与修复步骤 #

• 第一时间检查是否直接复制了示例里的硬编码路径：示例中/Users/abushoeb/myproject/templates是示例作者本地的个人路径，直接照搬必然和本地项目路径不匹配，必须替换为自己项目的真实模板目录路径。
• 不要用相对路径配置，通过路径拼接生成模板目录的绝对路径，避免工作目录变化导致路径失效，参考配置代码：

from pathlib import Path
from fastapi_mail import ConnectionConfig

# 定位当前配置文件所在目录，拼接得到templates文件夹的绝对路径
PROJECT_ROOT = Path(__file__).resolve().parent
TEMPLATE_DIR = PROJECT_ROOT / "templates"

conf = ConnectionConfig(
    # 其余邮件配置（MAIL_SERVER、MAIL_PORT、MAIL_USERNAME、MAIL_PASSWORD、MAIL_FROM等）按实际情况填写
    TEMPLATE_FOLDER=TEMPLATE_DIR
)

• 校验本地目录结构：确认项目对应位置确实存在templates文件夹，检查是否存在拼写错误（比如少写末尾s、字母顺序拼错）、目录层级放错的问题，把写邮件用的Jinja2模板文件都放到该目录下。
• 无模板发邮件需求可直接跳过该配置：TEMPLATE_FOLDER是可选参数，如果只发纯文本/静态HTML邮件不需要渲染Jinja2模板，初始化ConnectionConfig时不传入该参数即可，不会触发对应路径校验。
• 部署场景额外校验：如果是Docker部署、远程服务器部署，检查是否在忽略规则（比如.dockerignore、.gitignore）里误排除了templates目录，导致部署包中没有带上模板文件夹，造成运行环境找不到路径。

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