# 常见问题汇总

:::tip 说明
本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
:::

## 快速入门

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 端口被占用 | 8000 或 8001 端口被其他进程占用 | [故障排查](/zh/volume6/troubleshooting) |
| 数据库连接失败 | MySQL 未启动或配置错误 | [故障排查](/zh/volume6/troubleshooting) |
| Redis 连接失败 | Redis 未启动或密码配置错误 | [故障排查](/zh/volume6/troubleshooting) |
| pip install 安装失败 | 网络问题或依赖冲突 | [快速入门 FAQ](/zh/volume1/faq) |
| pnpm install 安装失败 | Node.js 版本或网络问题 | [快速入门 FAQ](/zh/volume1/faq) |
| API 请求返回 404 | 路由未注册或代理配置错误 | [故障排查](/zh/volume6/troubleshooting) |
| 验证码图片不显示 | Pillow 依赖或字体问题 | [故障排查](/zh/volume6/troubleshooting) |
| 接口返回 403 权限不足 | 权限节点未配置 | [故障排查](/zh/volume6/troubleshooting) |
| 文件上传失败 | 扩展名不在白名单或大小超限 | [故障排查](/zh/volume6/troubleshooting) |

## 后端开发

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 字段类型不匹配 | 模型字段与表单类型不一致 | [Form层规范](/zh/volume7/form) |
| 唯一性校验遗漏 | 未在 Form 中配置唯一性验证 | [Form层规范](/zh/volume7/form) |
| 软删除过滤缺失 | filter() 不自动过滤软删除 | [删除规范](/zh/volume7/deletion) |
| 分页参数命名不一致 | pageNo/pageSize 命名规范 | [分页规范](/zh/volume7/pagination) |
| 权限节点未配置 | 后端装饰器与前端指令不匹配 | [权限节点联动](/zh/volume4/integration/perm-sync) |
| Django 环境初始化失败 | 未激活虚拟环境或缺少依赖 | [故障排查](/zh/volume6/troubleshooting) |

## 前端开发

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 开发环境 API 请求 404 | Vite 代理配置错误 | [前端构建](/zh/volume4/frontend/build) |
| 构建后页面空白 | VITE_PUBLIC_PATH 不一致 | [前端构建](/zh/volume4/frontend/build) |
| 环境变量不生效 | 变量名未以 VITE_ 开头 | [前端构建](/zh/volume4/frontend/build) |
| 热更新不工作 | 修改了 vite.config.ts 需重启 | [前端构建](/zh/volume4/frontend/build) |

## 运维部署

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 502 Bad Gateway | 后端服务未启动 | [Nginx 反向代理](/zh/volume6/nginx) |
| 413 Request Entity Too Large | 上传文件超过限制 | [Nginx 反向代理](/zh/volume6/nginx) |
| 刷新页面 404 | 缺少 try_files 配置 | [Nginx 反向代理](/zh/volume6/nginx) |
| Supervisor 启动失败 | 配置文件路径错误 | [Supervisor](/zh/volume6/supervisor) |
| Docker 容器启动失败 | 环境变量或网络配置错误 | [Docker 容器化](/zh/volume6/docker) |
| 数据库迁移失败 | 数据类型不兼容 | [数据库迁移](/zh/volume6/db-migrate) |

## 代码生成器

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 生成后前端页面不显示 | 菜单未创建或权限未分配 | [代码生成器 FAQ](/zh/volume5/faq) |
| 生成代码报错 | 模板语法或配置问题 | [代码生成器 FAQ](/zh/volume5/faq) |
| 字段识别不准确 | 注释或类型推断问题 | [代码生成器 FAQ](/zh/volume5/faq) |
| 如何重新生成 | 清理旧文件后重新生成 | [代码生成器 FAQ](/zh/volume5/faq) |

## 排查思路

遇到问题时，按以下顺序排查：

```
1. 查看后端日志（终端输出或 logs/ 目录）
2. 查看浏览器 Network 面板（请求 URL、状态码、响应体）
3. 检查 .env 配置（环境变量是否正确）
4. 检查 Redis/MySQL 连接（服务是否启动）
5. 查阅对应模块的详细文档
```

## 总结

常见问题主要集中在环境配置、权限节点、文件上传、部署配置四个方面。遇到问题时优先查看后端日志和浏览器 Network 面板，大部分问题可通过检查 `.env` 配置定位原因。