签入版本

RXThinkCMF_ThinkPhp8_EleVue/zh/appendix/faq.md

@@ -0,0 +1,57 @@
+# A. 常见问题汇总
+
+:::tip 概述
+本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
+:::
+
+## 环境问题
+
+| 问题 | 解决方案 |
+|------|----------|
+| 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` 配置 |