# 常见问题汇总

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

## 环境与启动

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| PHP 版本低于 8.2 | 项目要求 PHP >= 8.2 | [环境准备](/zh/quickstart/environment.html) |
| 缺少 pdo_mysql 扩展 | 数据库驱动缺失 | [环境准备](/zh/quickstart/environment.html) |
| 缺少 gd 扩展 | 验证码图片生成需要 | [环境准备](/zh/quickstart/environment.html) |
| Composer 安装慢 | 配置国内镜像 | [后端启动](/zh/quickstart/backend-start.html) |
| 端口被占用 | 更换端口 `php think run --port 8080` | [后端启动](/zh/quickstart/backend-start.html) |
| 数据库连接失败 | 检查 .env 配置 | [数据库初始化](/zh/quickstart/database-init.html) |
| pnpm install 失败 | 清除缓存重装 | [前端启动](/zh/quickstart/frontend-start.html) |

## 认证与权限

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 401 未授权 | Token 缺失或过期 | [JWT 认证](/zh/core/jwt.html) |
| 403 禁止访问 | 权限不足或租户异常 | [RBAC 权限](/zh/core/rbac.html) |
| Token 频繁过期 | 检查 JWT.ACCESS_TTL 配置 | [JWT 认证](/zh/core/jwt.html) |
| 权限变更不生效 | 需重新登录 | [RBAC 权限](/zh/core/rbac.html) |
| 菜单不显示 | 检查菜单配置和角色权限 | [路由与菜单](/zh/frontend/router.html) |

## 业务功能

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 唯一性校验报错 | 数据重复，检查 uniqueFields | [逻辑层开发](/zh/guide/logic.html) |
| 枚举显示名为空 | 检查字典配置和 serializeMaps | [字典配置](/zh/core/dict-guide.html) |
| 文件上传失败 | 检查 FILE.UPLOAD_DIR 和目录权限 | [文件上传](/zh/tools/upload.html) |
| 导入失败 | 检查 Excel 表头与 headerMap 一致 | [导入导出](/zh/tools/excel.html) |
| 排序不生效 | 检查 pageOrderBy 配置 | [逻辑层开发](/zh/guide/logic.html) |
| 富文本图片不显示 | 检查 FILE.DOMAIN_URL 配置 | [富文本处理](/zh/tools/rich-text.html) |

## 前端开发

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| API 请求 404 | 检查后端路由和 Vite 代理 | [HTTP 请求](/zh/frontend/http.html) |
| 白屏 | 打开 F12 控制台查看错误 | [前端概述](/zh/frontend/overview.html) |
| 按钮权限不生效 | 检查 v-perm 指令和权限码 | [权限控制](/zh/frontend/permission.html) |
| 动态路由不加载 | 检查菜单配置和组件路径 | [路由与菜单](/zh/frontend/router.html) |

## 运维部署

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 502 Bad Gateway | PHP-FPM 未启动 | [故障排查](/zh/deploy/troubleshooting.html) |
| 404 Not Found | Nginx URL 重写配置错误 | [后端部署](/zh/deploy/backend.html) |
| 文件上传 413 | Nginx client_max_body_size 限制 | [后端部署](/zh/deploy/backend.html) |
| OPcache 不生效 | 检查 php.ini 配置 | [性能调优](/zh/deploy/performance.html) |
| 日志中 IP 为 127.0.0.1 | 部署在 CDN/代理后面时需配置 `PROXY_IPS` | [后端部署](/zh/deploy/backend.html) |
| IP 归属地为空 | 检查 `zoujingli/ip2region` 包是否安装 | [后端部署](/zh/deploy/backend.html) |

## 代码生成器

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 生成后页面不显示 | 菜单未创建或权限未分配 | [代码生成器 FAQ](/zh/generator/faq.html) |
| 生成代码报错 | 模板语法或配置问题 | [代码生成器 FAQ](/zh/generator/faq.html) |
| 表名不合法 | 只允许字母、数字、下划线 | [代码生成器 FAQ](/zh/generator/faq.html) |

## 排查思路

:::tip 排查步骤
遇到问题时，按以下顺序排查：
1. 查看 PHP 错误日志（Linux: `/var/log/php_errors.log`，XAMPP: `D:\xampp\php\logs\php_error_log`，路径可在 `php.ini` 的 `error_log` 配置项中确认）
2. 查看浏览器 Network 面板（请求 URL、状态码、响应体）
3. 检查 `.env` 配置（环境变量是否正确，注意 INI 分组格式）
4. 检查 Redis/MySQL 连接（服务是否启动）
5. 查阅对应模块的详细文档
:::