必须安装 asyncmy 驱动并正确配置 db_url：pip install tortoise-orm[asyncmy]，且 db_url 必须含 ?charset=utf8mb4；modules 参数需指定模型文件路径如 "app.models"，不可写为包名或带 .py 后缀。
能直接用，但必须装 asyncmy 驱动，且 db_url 格式不能错 —— 否则连不上、报 ModuleNotFoundError 或 ConnectionRefusedError。
安装 asyncmy 驱动是硬性前提
只装 tortoise-orm 不够，MySQL 连接会直接失败。Tortoise ORM 把数据库驱动拆成可选依赖，MySQL 必须额外装 asyncmy：
-
pip install tortoise-orm[asyncmy]（推荐，自动带asyncmy>=0.2.9） - 或手动装：
pip install asyncmy tortoise-orm（注意版本兼容：asyncmy 0.3.x 要求 Python ≥3.9） - 不装
asyncmy就调mysql://，运行时抛ModuleNotFoundError: No module named 'asyncmy'
db_url 字符串必须含 charset 参数
MySQL 默认字符集是 latin1，但 Tortoise ORM 写入中文或 emoji 会乱码或报错。db_url 必须显式加 ?charset=utf8mb4：
- 正确：
"mysql://root:123456@127.0.0.1:3306/mydb?charset=utf8mb4" - 错误：
"mysql://root:123456@127.0.0.1:3306/mydb"（可能写入失败或乱码） - 如果 MySQL 服务端没开
utf8mb4支持，需先执行：ALTER DATABASE mydb CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;
初始化时 modules 列表要包含模型路径，不能只写包名
modules 参数不是 Python 包导入路径，而是字符串路径列表，每个元素对应一个含 Model 子类的 Python 文件（不含 .py 后缀）：
- 假设模型在
app/models.py，就写{"models": ["app.models"]} - 如果还用了
aerich做迁移，必须把"aerich.models"也加进去，否则aerich migrate找不到迁移表 - 路径写错（比如写成
app/models或app.models.py）会导致generate_schemas()无反应、表不创建
FastAPI 中别在 startup 里用 await Tortoise.init()
FastAPI 的 startup 事件函数本身是异步的，但直接 await Tortoise.init() 有风险 —— 如果多个路由并发触发初始化，可能重复建连接或报 Tortoise is not initialized：
- 正确做法：用
asyncio.Lock()或全局 flag 控制仅初始化一次 - 更稳妥的是把
Tortoise.init()提前到应用启动前，比如在main.py顶层用run_async()初始化 - 生产环境务必配合
aerich做迁移，禁用generate_schemas()（它会删表重建，危险）
真正容易被忽略的是 charset=utf8mb4 和 modules 路径写法 —— 这两个点不卡死，但会让数据无声损坏或模型根本加载失败，debug 时很难联想到配置上。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
