签入版本
This commit is contained in:
@@ -1,14 +1,14 @@
|
||||
# 2.8 常见问题 FAQ
|
||||
# 2.9 常见问题 FAQ
|
||||
|
||||
## 环境相关
|
||||
|
||||
### Q: PHP 版本低于 8.2 能运行吗？
|
||||
### Q: PHP 版本低于 8.3 能运行吗？
|
||||
|
||||
A: 不能。项目使用了 PHP 8.2 的强类型特性（如 `readonly` 属性、`DNF` 类型等），必须使用 PHP 8.2+。
|
||||
A: 不能。项目基于 Laravel 13（composer.json 要求 `php ^8.3`），必须使用 PHP 8.3+。执行 `composer install` 时 Composer 会直接校验版本并报错。
|
||||
|
||||
### Q: 缺少 PHP 扩展怎么办？
|
||||
|
||||
A: 运行 `php -m` 检查已安装的扩展。缺少的扩展参考 [2.1 节](/zh/quickstart/environment.html) 安装。最常见的是缺少 `pdo_mysql` 和 `gd`。
|
||||
A: 运行 `php -m` 检查已安装的扩展。缺少的扩展参考 [2.1 开发环境准备](/zh/quickstart/environment.html) 安装。最常见的是缺少 `pdo_mysql`、`gd` 和 **`redis`**——`redis` 扩展缺失时报 `Class "Redis" not found`，验证码、登录直接不可用。
|
||||
|
||||
### Q: Composer 安装很慢怎么办？
|
||||
|
||||
@@ -23,32 +23,54 @@ composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
|
||||
|
||||
### Q: Redis 不安装可以吗？
|
||||
|
||||
A: 可以。Redis 是可选的缓存驱动，不安装时使用 file 缓存。将 `.env` 中 `CACHE.DRIVER` 设为 `file` 即可。
|
||||
A: **不可以。** 本项目强依赖 Redis：验证码、JWT 双令牌会话、权限缓存、字典缓存、会话/队列驱动均依赖它。Redis 相关问题（扩展安装、密码同步）见 [2.1 开发环境准备](/zh/quickstart/environment.html) 与 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)。
|
||||
|
||||
### Q: shell 里执行 php artisan 报版本过低 / 找不到类？
|
||||
|
||||
A: PATH 中的 `php` 可能是旧版本（Laragon 默认 PATH 常指向低版本 PHP）。使用 8.3 的完整路径调用：
|
||||
|
||||
```bash
|
||||
$PHP_HOME\php.exe artisan list
|
||||
$PHP_HOME\php.exe vendor\bin\pint --test
|
||||
```
|
||||
|
||||
## 启动相关
|
||||
|
||||
### Q: `php think run` 报错 "Address already in use"
|
||||
### Q: `php artisan serve` 报 "Address already in use"
|
||||
|
||||
A: 端口被占用，更换端口：
|
||||
|
||||
```bash
|
||||
# --port → 指定监听端口（默认 8000）
|
||||
php think run --port 8080
|
||||
php artisan serve --port=8080
|
||||
```
|
||||
|
||||
### Q: 数据库连接失败 "Connection refused"
|
||||
### Q: 应用拒绝启动，报 JWT_SECRET 错误？
|
||||
|
||||
A: `.env` 中 `JWT_SECRET` 为空或不足 32 字符——应用启动时执行 fail-close 校验（不满足直接抛异常）。生成强随机密钥后重启：
|
||||
|
||||
```bash
|
||||
openssl rand -base64 32 # 或 php -r "echo bin2hex(random_bytes(32));"
|
||||
```
|
||||
|
||||
### Q: 数据库连接失败 "Connection refused" 或表不存在？
|
||||
|
||||
A: 检查以下几点：
|
||||
|
||||
1. MySQL 服务是否启动：`systemctl status mysql`
|
||||
2. `.env` 中的数据库配置是否正确
|
||||
3. 数据库用户是否有权限：`GRANT ALL ON \`rxthinkcmf.thinkphp6.elevue\`.* TO 'root'@'localhost'`
|
||||
2. `.env` 中的 `DB_*` 配置是否正确（`DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD`、`DB_DATABASE`）
|
||||
3. 数据库是否已创建并导入 `document/mysql/rxthinkcmf.laravel13.elevue.sql`（本项目 migrations 为空，**不会自动建表**）
|
||||
4. `DB_PREFIX` 是否为 `laravel_`（漏配会报 `Table 'xxx.users' doesn't exist`）
|
||||
5. 原生测试连接：`mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT 1;"`
|
||||
|
||||
### Q: 登录返回 401
|
||||
|
||||
A: 可能原因：
|
||||
1. Token 过期 → 重新登录
|
||||
|
||||
1. Token 过期 → 重新登录（access_token 默认 2 小时，refresh_token 7 天）
|
||||
2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
|
||||
3. JWT 密钥不匹配 → 检查 `.env` 中的 `JWT.SECRET`
|
||||
3. `JWT_SECRET` 变更 → 旧令牌全部失效，重新登录即可
|
||||
4. Redis 中会话被清除（如重启 Redis、执行 `FLUSHDB`）→ 重新登录
|
||||
|
||||
## 前端相关
|
||||
|
||||
@@ -65,40 +87,78 @@ pnpm install # 重新安装所有依赖
|
||||
### Q: 前端请求后端 404
|
||||
|
||||
A: 检查以下几点：
|
||||
1. 后端服务是否启动
|
||||
2. Vite 代理配置是否正确（`vite.config.ts` 中的 `target`）
|
||||
|
||||
1. 后端服务是否启动（`curl http://localhost:8000/api/captcha` 验证）
|
||||
2. Vite 代理配置是否正确（`vite.config.ts` 中的 `target`，改完重启 `pnpm dev`）
|
||||
3. API 路径是否正确（应以 `/api` 开头）
|
||||
|
||||
### Q: 页面白屏
|
||||
|
||||
A: 打开浏览器控制台（F12）查看错误信息，常见原因：
|
||||
|
||||
1. JS 加载失败 → 检查网络请求
|
||||
2. 路由配置错误 → 检查后端菜单数据
|
||||
2. 路由配置错误 → 检查后端菜单数据（`/api/index/getMenus` 是否正常返回）
|
||||
3. Token 过期 → 重新登录
|
||||
|
||||
## Oracle 相关
|
||||
## 数据库初始化相关
|
||||
|
||||
### Q: ThinkPHP 连接 Oracle 需要哪个 PHP 扩展？
|
||||
### Q: `composer setup` / `php artisan migrate` 后依然提示表不存在？
|
||||
|
||||
A: 需要 `pdo_oci` 扩展。ThinkPHP 的 Oracle 连接器通过 PDO 连接数据库（DSN 前缀 `oci:dbname=`），XAMPP 8.2 已自带 `php_pdo_oci.dll`，只需在 php.ini 中启用即可。
|
||||
A: 正常现象。本项目 `database/migrations/` 为空，**建表以 SQL 脚本为准**，`migrate` 只初始化迁移记录表。请手动导入：
|
||||
|
||||
### Q: XAMPP 下 pdo_oci 扩展加载失败怎么办？
|
||||
```bash
|
||||
mysql -uroot -proot rxthinkcmf.laravel13.elevue < document/mysql/rxthinkcmf.laravel13.elevue.sql
|
||||
```
|
||||
|
||||
A: 按以下顺序排查：
|
||||
1. 是否安装了 Oracle Instant Client 19c（x64）并解压到固定路径
|
||||
2. 该路径是否已添加到**系统变量** PATH 中（不是用户变量）
|
||||
3. 是否安装了 VC++ 2015-2022 Redistributable（x64）
|
||||
4. `php.ini` 中 `extension=pdo_oci` 是否已去掉分号
|
||||
5. XAMPP 是否**完全关闭再启动**（不是只点 Apache 的 Start/Stop）
|
||||
详见 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
|
||||
|
||||
### Q: 命令行 `php -m` 能看到 pdo_oci，但浏览器 phpinfo() 里找不到？
|
||||
### Q: 导入 SQL 很慢或中断？
|
||||
|
||||
A: Apache 作为 Windows 服务运行时，读取的是服务启动时的系统 PATH。如果在 Apache 启动**之后**才修改了 PATH 环境变量，Apache 不会感知到。解决方法：在 XAMPP 控制面板中完全停止 Apache，再重新启动。
|
||||
A: 脚本约 226MB（含全国行政区划等大数据量表），导入需 1~3 分钟属正常。确保：
|
||||
|
||||
### Q: Oracle Instant Client 应该下载哪个版本？
|
||||
1. 数据库字符集为 `utf8mb4`
|
||||
2. 命令行窗口保持打开直到导入完成
|
||||
3. MySQL 的 `max_allowed_packet` 足够（默认 64MB 一般够用，不足时调大）
|
||||
|
||||
A: 推荐下载 **19c** 的 **Basic Package**（x64）。下载地址：https://www.oracle.com/database/technologies/instant-client/downloads.html
|
||||
## Docker 相关
|
||||
|
||||
### Q: 为什么 Instant Client 必须解压到固定路径？
|
||||
### Q: Docker 启动后 mysql 一直 unhealthy？
|
||||
|
||||
A: 因为系统 PATH 环境变量写入的是绝对路径。如果解压到桌面或下载文件夹，后续清理、移动或重命名都会导致 PATH 失效，PHP 无法加载 Oracle 客户端库。推荐路径：`C:\oracle\instantclient_19_20`。
|
||||
A: 首次启动需导入约 226MB SQL，健康检查已预留缓冲（1~3 分钟）。查看进度：
|
||||
|
||||
```bash
|
||||
docker compose logs -f mysql
|
||||
```
|
||||
|
||||
详见 [2.8 Docker 快速体验](/zh/quickstart/docker.html)。
|
||||
|
||||
### Q: Docker 启动即退出，日志报 JWT_SECRET？
|
||||
|
||||
A: 容器内读取的 `JWT_SECRET` 不足 32 字符。在 `docker/.env.docker` 中生成随机值后重启：
|
||||
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
docker compose restart app
|
||||
```
|
||||
|
||||
### Q: 本机 Laragon 与 Docker 端口冲突？
|
||||
|
||||
A: 修改 `docker/.env.docker` 中的宿主机端口（如 `MYSQL_PORT=3307`、`REDIS_PORT=6380`），容器内部通过服务名通信不受影响。见 [2.8 Docker 快速体验](/zh/quickstart/docker.html) 「端口冲突处理」。
|
||||
|
||||
## 认证与权限相关
|
||||
|
||||
### Q: 接口返回 `{"code":403,"msg":"无访问权限"}`？
|
||||
|
||||
A: 当前账号角色缺少该接口的权限节点。到「系统管理 → 角色管理」为角色勾选对应菜单/按钮权限（权限码如 `sys:user:add`），或使用超级管理员账号测试。权限模型见 [5.4 权限管理（RBAC）](/zh/core/rbac.html)。
|
||||
|
||||
### Q: 接口返回 `{"code":401,"msg":"未授权，请先登录"}`？
|
||||
|
||||
A: Token 缺失、无效或过期。检查：
|
||||
|
||||
1. 请求头是否携带 `Authorization: Bearer <token>`
|
||||
2. access_token 是否过期（默认 2 小时），过期后调 `/api/refresh` 续签或重新登录
|
||||
3. 是否被踢下线 / 改密后全端失效（Redis 会话已清除）
|
||||
|
||||
### Q: 接口都是 HTTP 200，怎么判断成功失败？
|
||||
|
||||
A: 项目约定 HTTP 状态码恒为 200（403 例外），以响应体 `code` 判断：`code=0` 成功，其他为失败；`code=401` 时前端跳转登录。见 [8.1 统一响应格式](/zh/api-spec/response.html)。
|
||||
|
||||
Reference in New Issue
Block a user