常见问题汇总

说明

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

快速入门

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

后端开发

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

前端开发

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

运维部署

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

代码生成器

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

排查思路

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

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

总结

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