Become a sponsor
常见问题汇总
说明
本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
环境与启动
| 问题 | 说明 | 详细文档 |
|---|---|---|
| PHP 版本低于 8.2 | 项目要求 PHP >= 8.2 | 环境准备 |
| 缺少 pdo_mysql 扩展 | 数据库驱动缺失 | 环境准备 |
| 缺少 gd 扩展 | 验证码图片生成需要 | 环境准备 |
| Composer 安装慢 | 配置国内镜像 | 后端启动 |
| 端口被占用 | 更换端口 php think run --port 8080 | 后端启动 |
| 数据库连接失败 | 检查 .env 配置 | 数据库初始化 |
| pnpm install 失败 | 清除缓存重装 | 前端启动 |
认证与权限
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 401 未授权 | Token 缺失或过期 | JWT 认证 |
| 403 禁止访问 | 权限不足或租户异常 | RBAC 权限 |
| Token 频繁过期 | 检查 JWT.ACCESS_TTL 配置 | JWT 认证 |
| 权限变更不生效 | 需重新登录 | RBAC 权限 |
| 菜单不显示 | 检查菜单配置和角色权限 | 路由与菜单 |
业务功能
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 唯一性校验报错 | 数据重复，检查 uniqueFields | 逻辑层开发 |
| 枚举显示名为空 | 检查字典配置和 serializeMaps | 字典配置 |
| 文件上传失败 | 检查 FILE.UPLOAD_DIR 和目录权限 | 文件上传 |
| 导入失败 | 检查 Excel 表头与 headerMap 一致 | 导入导出 |
| 排序不生效 | 检查 pageOrderBy 配置 | 逻辑层开发 |
| 富文本图片不显示 | 检查 FILE.DOMAIN_URL 配置 | 富文本处理 |
前端开发
| 问题 | 说明 | 详细文档 |
|---|---|---|
| API 请求 404 | 检查后端路由和 Vite 代理 | HTTP 请求 |
| 白屏 | 打开 F12 控制台查看错误 | 前端概述 |
| 按钮权限不生效 | 检查 v-perm 指令和权限码 | 权限控制 |
| 动态路由不加载 | 检查菜单配置和组件路径 | 路由与菜单 |
运维部署
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 502 Bad Gateway | PHP-FPM 未启动 | 故障排查 |
| 404 Not Found | Nginx URL 重写配置错误 | 后端部署 |
| 文件上传 413 | Nginx client_max_body_size 限制 | 后端部署 |
| OPcache 不生效 | 检查 php.ini 配置 | 性能调优 |
| 日志中 IP 为 127.0.0.1 | 部署在 CDN/代理后面时需配置 PROXY_IPS | 后端部署 |
| IP 归属地为空 | 检查 zoujingli/ip2region 包是否安装 | 后端部署 |
代码生成器
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 生成后页面不显示 | 菜单未创建或权限未分配 | 代码生成器 FAQ |
| 生成代码报错 | 模板语法或配置问题 | 代码生成器 FAQ |
| 表名不合法 | 只允许字母、数字、下划线 | 代码生成器 FAQ |
排查思路
排查步骤
遇到问题时，按以下顺序排查：
- 查看 PHP 错误日志（Linux:
/var/log/php_errors.log，XAMPP:D:\xampp\php\logs\php_error_log，路径可在php.ini的error_log配置项中确认） - 查看浏览器 Network 面板（请求 URL、状态码、响应体）
- 检查
.env配置（环境变量是否正确，注意 INI 分组格式） - 检查 Redis/MySQL 连接（服务是否启动）
- 查阅对应模块的详细文档