easygoadmin-wiki/EasyGoAdmin_Gin_Layui/zh/faq.md

常见问题汇总

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

环境与启动

问题	说明	详细文档
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

排查思路

:::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. 查阅对应模块的详细文档 :::