A. 常见问题汇总

概述

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

环境问题

问题	解决方案
PHP 版本低于 8.2	升级到 PHP 8.2+，项目使用了 8.2 的强类型特性
缺少 pdo_mysql 扩展	apt install php8.2-mysql 或 dnf install php-mysqlnd
缺少 gd 扩展	apt install php8.2-gd 或 dnf install php-gd
Composer 下载慢	composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
Redis 未安装	可选，改用 file 缓存：.env 中 [CACHE] 下设置 DRIVER = file
缺少 redis 扩展	pecl install redis
Oracle pdo_oci 加载失败（Windows）	安装 Oracle Instant Client 19c + VC++ 2015-2022 Redistributable，php.ini 启用 extension=pdo_oci，配置系统 PATH 后重启 Apache
命令行有 pdo_oci，浏览器 phpinfo 没有	Apache 服务启动时 PATH 未刷新，完全停止再启动 Apache 即可
Oracle Instant Client 路径含中文/空格导致加载失败	解压到 C:\oracle\instantclient_19_20 等固定路径，避免空格与中文

启动问题

问题	解决方案
端口被占用	php think run --port 8080
数据库连接失败	检查 .env 中的数据库配置
401 未授权	检查请求头是否携带 Authorization: Bearer <token>
403 禁止访问	检查用户权限配置，确认角色已分配菜单
502 Bad Gateway	检查 PHP-FPM 是否启动：systemctl status php8.2-fpm

业务问题

问题	解决方案
唯一性校验报错	检查数据是否重复，确认 uniqueFields 配置
枚举显示名为空	检查字典配置，确认 serializeMaps 正确
文件上传失败	检查 FILE.UPLOAD_DIR 配置和目录权限
导入失败	检查 Excel 表头是否与 headerMap 一致
排序不生效	检查 pageOrderBy 配置，或前端 orderField 参数

前端问题

问题	解决方案
pnpm install 失败	rm -rf node_modules pnpm-lock.yaml && pnpm install
API 404	检查后端路由注册和 Vite 代理配置
菜单不显示	检查菜单配置、组件路径、角色权限
白屏	打开 F12 控制台查看错误
Token 频繁过期	检查 JWT.ACCESS_TTL 配置（默认 7200 秒）

定时任务问题

问题	解决方案
任务不执行	检查 crontab 配置：crontab -l
任务重复执行	检查是否有多个 cron 或 daemon 在运行
任务执行超时	检查 PHP max_execution_time 配置