第七章常见问题与调试技巧

本章目标：掌握常见报错的解决方法和调试技巧，遇到问题不慌。

7.1 学会看报错信息

遇到问题不要慌，90% 的问题都能从报错信息中找到答案。

后端报错：看终端

后端出错时，运行 uvicorn 的终端窗口会显示红色的错误信息：

ERROR:    [Some error message]
Traceback (most recent call last):
  File "main.py", line 25, in create_todo
    ...
TypeError: xxx

看报错的技巧：

先看最后一行 → 这是错误类型和简短描述
再往上找 File "xxx", line xx → 这是出错的文件和行号
对照你的代码看那一行有什么问题

前端报错：看浏览器控制台

按 F12 打开浏览器开发者工具：

Console（控制台）面板：显示 JavaScript 报错
Network（网络）面板：显示所有 HTTP 请求的详情

Network 面板是联调时最有用的工具：

关注点	说明
Status	状态码（200/404/422/500等）
Request URL	请求发到了哪个地址
Request Body	发送了什么数据
Response	后端返回了什么

7.2 常见错误及解决方法

错误 1：端口被占用

ERROR: [Errno 10048] error while attempting to bind on address ('127.0.0.1', 8000)

原因：8000 端口已经有程序在用了（可能是之前的 uvicorn 没关掉）。

解决：

方法一：换个端口启动

uvicorn main:app --reload --port 8001

方法二：找到并关闭占用端口的进程

# Windows
netstat -ano | findstr :8000
taskkill /PID <进程ID> /F

# Mac / Linux
lsof -i :8000
kill -9 <PID>

错误 2：422 Unprocessable Entity

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "title"],
      "msg": "Field required"
    }
  ]
}

原因：请求参数格式不对。FastAPI 做了数据校验，发现你少传了字段或者类型不对。

常见情况：

POST 请求忘了传请求体
JSON 里的字段名写错了（比如 titl 而不是 title）
字段类型不对（比如 id 应该是数字但传了字符串）

解决：仔细看 detail 里的提示，它会告诉你哪个字段有问题。

错误 3：404 Not Found

{"detail": "Not Found"}

原因：访问的 URL 不存在。

常见情况：

URL 拼写错误（比如 /todo 写成了 /todos）
路径参数写错（比如 /todos/abc 但 id 应该是数字）
后端没有定义这个路由

解决：打开 http://127.0.0.1:8000/docs 检查实际有哪些接口。

错误 4：500 Internal Server Error

{"detail": "Internal Server Error"}

原因：后端代码出 bug 了。

解决：去看运行 uvicorn 的终端，里面会有详细的报错信息（Traceback）。常见原因包括：

变量名写错
导入的模块不存在
数据库操作逻辑有误

错误 5：CORS 跨域错误

浏览器控制台显示：

Access to XMLHttpRequest at 'http://127.0.0.1:8000/todos' 
from origin 'http://localhost:5173' has been blocked by CORS policy

原因：后端没有配置 CORS 中间件。

解决：参照第六章 6.1 节，在 main.py 中添加 CORS 中间件。

错误 6：ModuleNotFoundError

ModuleNotFoundError: No module named 'fastapi'

原因：依赖没安装，或者装到了别的 Python 环境里。

解决：

pip install fastapi uvicorn sqlmodel

如果安装了还是报错，检查你的 Python 环境是否正确（特别是用了虚拟环境的同学）：

# 看看 pip 和 python 是不是同一个环境
which python
which pip

# 或者 Windows
where python
where pip

错误 7：数据库表不存在

sqlalchemy.exc.OperationalError: no such table: todo

原因：数据库表没有被创建。

解决：确认 main.py 中的 lifespan 函数调用了 create_db_and_tables()，并且 models.py 被正确导入了。

简单粗暴的方法：删掉 database.db 文件，重启服务，会自动重建。

7.3 调试技巧

技巧 1：善用 print

在后端代码中加 print() 是最简单的调试方法：

@app.post("/todos", status_code=201)
def create_todo(todo: TodoCreate):
    print("收到的数据：", todo)
    # ...

print 的输出会显示在运行 uvicorn 的终端窗口中。

技巧 2：善用 /docs 页面

在连接前端之前，先在 /docs 页面把每个接口都测试一遍，确保后端没问题。

如果 /docs 页面测试没问题，但前端调用有问题，那问题一定在前端。

技巧 3：善用浏览器 Network 面板

前后端联调出问题时：

按 F12 打开开发者工具
切到 Network 面板
做一个操作（比如点添加按钮）
看请求的详情：URL 对不对？参数对不对？返回了什么？

技巧 4：echo=True 看 SQL

我们在 database.py 中设置了 echo=True，这会在终端打印每次执行的 SQL 语句：

INFO sqlalchemy.engine.Engine SELECT todo.id, todo.title, todo.done FROM todo

这有助于理解你的 Python 代码最终执行了什么数据库操作。

7.4 推荐开发工具

工具	用途	说明
浏览器 /docs	测试后端接口	FastAPI 自带，最方便
Apifox	专业接口测试	国产工具，免费好用，支持团队协作
Postman	专业接口测试	国际主流工具
DB Browser for SQLite	查看数据库	可视化查看表结构和数据
浏览器 F12	前端调试	Network 看请求，Console 看报错

本章小结

错误类型	常见原因	排查方法
422	请求参数不对	看 detail 提示
404	URL 不存在	检查 /docs 里的接口列表
500	后端代码有 bug	看终端的报错日志
CORS	没加跨域中间件	添加 CORSMiddleware
ModuleNotFoundError	依赖没装	pip install
端口占用	上次服务没关	换端口或 kill 进程

记住两个最重要的调试原则：

先后端，后前端：先用 /docs 确认后端没问题，再调前端
看报错信息：报错信息已经告诉你答案了，认真看

下一章，我们做总结回顾，并介绍后续的进阶方向。

第七章 常见问题与调试技巧