签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 常见问题汇总
+
+:::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. 查阅对应模块的详细文档
+:::