VSCode配置FastAPI与Tortoise ORM 环境搭建教程【指南】-VSCode-PHP中文网

能直接跑通 fastapi + tortoise-orm 的最小 vscode 环境核心是三件事：python 解释器必须指向项目虚拟环境、uvicorn 和 tortoise-orm 必须装在此环境中、app 实例与 tortoise.init() 初始化逻辑顺序不能错位；其余均为可选。

vscode配置fastapi与tortoise orm 环境搭建教程【指南】

能直接跑通 FastAPI + Tortoise-ORM 的最小 VSCode 环境，核心就三件事：Python 解释器必须指向项目虚拟环境、uvicorn 和 tortoise-orm 必须装在这个环境里、app 实例和 Tortoise.init() 初始化逻辑不能错位。其余都是锦上添花。

VSCode 里选不对 Python 解释器，后续全白搭

VSCode 默认不自动识别项目虚拟环境，哪怕你用 python -m venv .venv 创建了，它仍可能用系统 Python 或其他全局解释器。后果是：ImportError: No module named 'tortoise'、ModuleNotFoundError: No module named 'uvicorn' 这类报错根本不是代码问题，而是包压根没装对地方。

按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Python: Select Interpreter
从列表里选带 .venv、venv 或你自定义名（如 myenv）的路径；没出现就点 Enter interpreter path，手动填：
– Windows：.venv\Scripts\python.exe
– macOS/Linux：.venv/bin/python
选完后，右下角状态栏必须显示该路径；如果没变，关掉所有终端再新开一个

`uvicorn` 启动失败，90% 是 `main:app` 找不到

错误信息常是 ImportError: cannot import name 'app' from 'main' 或 Application not found。本质是 Python 导入链断裂，和 FastAPI 本身无关。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

main.py 文件顶层必须有且仅有一个变量名是 app，类型是 FastAPI() 实例（不能是函数、类、带下划线前缀如 _app）
终端当前工作目录必须是 main.py 所在的项目根目录（不是子文件夹）
必须已激活虚拟环境：(.venv) 要出现在终端提示符最前面；Windows 激活命令是 .venv\Scripts\activate，macOS/Linux 是 source .venv/bin/activate
推荐安装 fastapi[all] 而非单独装 fastapi 和 uvicorn——它会一并装好 asyncpg、aiosqlite、python-multipart 等 Tortoise-ORM 常用依赖

`Tortoise.init()` 放错位置，数据库连不上还无报错

很多人把 Tortoise.init() 写在路由函数里、或者写在 if __name__ == "__main__": 下，结果服务启动了但模型注册失败，查数据库时直接 AttributeError: type object 'User' has no attribute 'all'。

Tortoise.init() 必须在 app 实例创建之后、uvicorn.run() 之前执行，且只执行一次
推荐统一放在 db.py 中初始化，然后在 main.py 开头 import 并调用，例如：
```
from db import init_db<br>init_db()
```
连接 URL 中的驱动名要匹配实际安装的异步驱动：postgres:// 对应 asyncpg，sqlite:// 对应 aiosqlite；写成 postgresql:// 却没装 asyncpg，会静默失败
别漏掉 register_tortoise(app, ...) —— 它负责把 Tortoise 生命周期绑定到 FastAPI 的 startup/shutdown 事件，否则服务重启时连接不释放

调试时断点不生效，其实是 uvicorn 模式配错了

VSCode 调试 FastAPI 不能用 "program": "main.py"，否则异步上下文丢失，await 会卡死，断点也进不去视图函数。

必须用 "module": "uvicorn" 模式，在 .vscode/launch.json 中配置：

{<br>  "configurations": [<br>    {<br>      "name": "FastAPI Debug",<br>      "type": "python",<br>      "request": "launch",<br>      "module": "uvicorn",<br>      "args": ["main:app", "--reload", "--host", "127.0.0.1", "--port", "8000"],<br>      "console": "integratedTerminal",<br>      "justMyCode": false<br>    }<br>  ]<br>}

"justMyCode": false 很关键——否则断点进不了 tortoise 或 uvicorn 内部，查连接池、事务、异常堆栈时完全抓瞎
确保 main.py 里没有 if __name__ == "__main__": uvicorn.run(...) 这种写法，它和调试模式冲突