import{_ as d,o as a,c as e,a2 as r}from"./chunks/framework.B-QBKwc1.js";const b=JSON.parse('{"title":"常见问题汇总","description":"本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。","frontmatter":{},"headers":[],"relativePath":"zh/faq.md","filePath":"zh/faq.md"}'),h={name:"zh/faq.md"};function o(l,t,i,n,c,s){return a(),e("div",null,[...t[0]||(t[0]=[r('

常见问题汇总 ​

说明

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

环境与启动 ​

问题说明详细文档
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 GatewayPHP-FPM 未启动故障排查
404 Not FoundNginx URL 重写配置错误后端部署
文件上传 413Nginx client_max_body_size 限制后端部署
OPcache 不生效检查 php.ini 配置性能调优
日志中 IP 为 127.0.0.1部署在 CDN/代理后面时需配置 PROXY_IPS后端部署
IP 归属地为空检查 zoujingli/ip2region 包是否安装后端部署

代码生成器 ​

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

排查思路 ​

排查步骤

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

  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. 查阅对应模块的详细文档
',16)])])}const f=d(h,[["render",o]]);export{b as __pageData,f as default};