# A. 常见问题汇总

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

## 环境问题

| 问题 | 解决方案 |
|------|----------|
| PHP 版本低于 8.3 | 升级到 PHP 8.3+（Laravel 13 要求），项目使用了 8.3 的语言特性 |
| 缺少 pdo_mysql 扩展 | `apt install php8.3-mysql` 或 `dnf install php-mysqlnd` |
| `could not find driver`（`db:migrate` 迁到 PostgreSQL） | php.ini 扩展区启用 `extension=pdo_pgsql`（Windows 自带 `php_pdo_pgsql.dll` + `libpq.dll`，取消注释即可；Linux `apt install php8.3-pgsql`），CLI 重读 php.ini 无需重启 |
| 缺少 gd 扩展 | `apt install php8.3-gd` 或 `dnf install php-gd` |
| 缺少 redis 扩展 | `apt install php8.3-redis` 或 `pecl install redis`（**必需**：缓存/会话/队列/JWT 均依赖） |
| Redis 未安装 | 安装 Redis 6.0+ 并配置密码（本项目 `.env.example` 默认全部 Redis 驱动，不建议改 file） |
| Composer 下载慢 | `composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/` |
| 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 artisan serve --port=8080` |
| 数据库连接失败 | 检查 `.env` 中的数据库配置（注意 `DB_PREFIX=laravel_` 与 SQL 脚本一致） |
| 表不存在 | 本项目无 migration 建表，导入 `document/mysql/*.sql`（见 [2.5 数据库初始化](/zh/quickstart/database-init.html)） |
| 401 未授权 | 检查请求头是否携带 `Authorization: Bearer <token>`，确认 `JWT_SECRET` 配置（缺失/过短会 fail-close） |
| 403 禁止访问 | 检查用户权限配置，确认角色已分配菜单 |
| 502 Bad Gateway | 检查 PHP-FPM 是否启动：`systemctl status php8.3-fpm` |
| 登录失败/缓存不生效 | 检查 Redis 是否运行、`REDIS_*` 配置是否正确（见 [11.10 故障排查手册](/zh/deploy/troubleshooting.html)） |

## 业务问题

| 问题 | 解决方案 |
|------|----------|
| 唯一性校验报错 | 检查数据是否重复，确认 `uniqueFields` 配置 |
| 枚举显示名为空 | 检查字典配置，确认 `serializeMaps` 正确、字典编码已创建 |
| 文件上传失败 | 检查 `FILE_UPLOAD_DIR` / `FILE_MAX_SIZE` 配置和 `public/uploads/` 目录权限 |
| 导入失败 | 检查 Excel 表头是否与 `headerMap` 一致 |
| 排序不生效 | 检查 `pageOrderBy` 配置，或前端 `orderField` 是否在白名单（`pageOrderBy` ∪ `orderFieldAllow`）内 |

## 前端问题

| 问题 | 解决方案 |
|------|----------|
| pnpm install 失败 | `rm -rf node_modules && pnpm install --force`（锁文件 `pnpm-lock.yaml` 保留） |
| API 404 | 检查后端路由注册和 Vite 代理 / Nginx `proxy_pass` 配置 |
| 菜单不显示 | 检查菜单配置、组件路径、角色权限，重新登录刷新动态菜单 |
| 白屏 | 打开 F12 控制台查看错误 |
| Token 频繁过期 | 检查 `JWT_ACCESS_TTL` 配置（默认 7200 秒），或使用 `refresh` 刷新令牌 |

## 定时任务问题

| 问题 | 解决方案 |
|------|----------|
| 任务不执行 | 检查 crontab 配置：`crontab -l`；手动执行 `php artisan job:run` 验证 |
| 任务重复执行 | 检查是否有多个 `job:run` cron 或 `job:daemon` 守护进程在运行 |
| 任务执行超时 | 检查 PHP `max_execution_time` 配置 |
| 内部任务处理器不存在 | `url` 字段按 `App\Task\{名称}Task` 映射，确认类名与 `run()` 方法存在（见 [6.11 定时任务](/zh/modules/job.html)） |