附录 A：常见错误排查
新手最常遇到的报错和坑，按出现频率排列。遇到问题先 Ctrl+F 搜关键词。
排查通用心法
- 看报错的最后几行：Python 的 Traceback 最下面才是真正的错误类型和位置
- 看终端不看浏览器：500 错误时，浏览器只显示 Internal Server Error，完整堆栈在运行 fastapi dev 的终端里
- 422 看响应体：
detail里的loc和msg精确指出哪个字段错了
启动类问题
ModuleNotFoundError: No module named 'app'
启动命令的执行位置不对。必须在项目根目录（app 文件夹的上一层）执行 fastapi dev app/main.py；同时确认 app/__init__.py 存在。
ModuleNotFoundError: No module named 'fastapi'
- 虚拟环境没激活（命令行前面没有
(venv)） - 或者 VS Code 终端用的是系统 Python：重新选择解释器后新开终端
[Errno 10048] error while attempting to bind on address（端口被占用）
上一个服务没关。找到那个终端 Ctrl+C，或换端口：fastapi dev app/main.py --port 8001。
启动时报 PendingDeprecationWarning / 各种 Warning
Warning 不是错误，服务照常运行，可以先忽略。
请求/响应类问题
接口返回 422，但我觉得数据没问题
- 看
detail[0].loc：["query", "x"]说明它把参数当成了查询参数——是不是想传请求体却没定义 Pydantic 模型？ - POST JSON 时，客户端要带
Content-Type: application/json（用 requests 库时用json=参数而不是data=） - 登录接口是表单：curl/requests 要用
data=，不是json=
访问 /users/me 报 422 说 me 不是整数
路由顺序问题：/users/me 必须定义在 /users/{user_id} 之前。
返回的 JSON 里缺字段 / 多字段
检查 response_model：它按模型过滤输出。缺字段说明模型里没声明；敏感字段没被过滤说明你没设 response_model。
返回数据库对象时报错 Unable to serialize 或字段全空
输出模型忘了加 model_config = ConfigDict(from_attributes=True)。
前端跨域报 CORS 错误，Postman 却正常
没配 CORSMiddleware，见 5.2 中间件与 CORS。注意：后端 500 时错误响应没有 CORS 头，前端也会显示成 CORS 错——先确认接口本身没报错。
SQLAlchemy 类问题
表没有创建出来
create_all 之前必须导入过定义模型的模块（from app import models）。没导入，Base 就不知道有这些模型。
改了模型，数据库没变化 / 报 no such column
create_all 不会修改已存在的表。删掉 .db 文件重启（丢数据），或用 Alembic 迁移。
sqlite3.ProgrammingError: SQLite objects created in a thread can only be used in that same thread
SQLite 配 FastAPI 必须加：create_engine(url, connect_args={"check_same_thread": False})。
IntegrityError: UNIQUE constraint failed
往 unique 列插了重复值。应在插入前先查询是否存在，返回 409（见用户接口章节）。注意：这个异常发生后 Session 已损坏，后续操作前需要 db.rollback()。
DetachedInstanceError: Instance is not bound to a Session
Session 关闭后才去访问对象的懒加载属性。解决：在 Session 存活期间用 selectinload 预加载需要的关联，或先访问一次属性。
改了对象属性但数据库没更新
- 忘了
db.commit() - 或者对象不是从当前 Session 查出来的（比如是自己 new 的且没 add）
查询返回的是 Row/元组而不是模型对象
用了 db.execute(select(User))。查整个模型请用 db.scalars(select(User))。
列表接口非常慢 / echo 里刷出一大串 SQL
N+1 问题：循环里访问了懒加载关系。查询加 .options(selectinload(Model.relation))。
认证类问题
/docs 里点了 Authorize 还是 401
- Token 已过期：重新登录
OAuth2PasswordBearer(tokenUrl=...)的地址和登录接口实际路径不一致- SECRET_KEY 改过：旧 Token 全部失效，重新登录
jwt.exceptions.InvalidTokenError
手动测试时 Token 复制不完整，或 Authorization 头忘了 Bearer 前缀（注意 Bearer 后有个空格）。
bcrypt / passlib 报错 AttributeError: module 'bcrypt' has no attribute '__about__'
passlib 与新版 bcrypt 不兼容（passlib 已停更）。按本教程改用 pwdlib[bcrypt]。
环境类问题
pip install 特别慢或超时
用国内镜像：pip install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple
PowerShell 无法激活虚拟环境（禁止运行脚本）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Windows 下中文乱码
- 响应里的中文变成
\uXXXX：这是 JSON 的合法转义，前端解析后显示正常，不是 bug - 终端打印乱码：
chcp 65001切换 UTF-8 代码页
还是解决不了？
- 把报错最后一行原文粘贴到搜索引擎，加关键词 fastapi 或 sqlalchemy
- 官方文档：FastAPI https://fastapi.tiangolo.com/zh/ （有中文版）、SQLAlchemy https://docs.sqlalchemy.org/
- 把最小复现代码和完整报错发给 AI 助手，通常能快速定位