# 2.9 常见问题 FAQ

## 环境相关

### Q: PHP 版本低于 8.3 能运行吗？

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` 和 **`redis`**——`redis` 扩展缺失时报 `Class "Redis" not found`，验证码、登录直接不可用。

### Q: Composer 安装很慢怎么办？

A: 配置中国镜像：

```bash
# 配置阿里云 Composer 镜像（加速依赖下载）
# -g → 修改全局配置（所有项目生效）
# repo.packagist → 设置 Packagist 仓库镜像地址
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```

### Q: Redis 不安装可以吗？

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 artisan serve` 报 "Address already in use"

A: 端口被占用，更换端口：

```bash
# --port → 指定监听端口（默认 8000）
php artisan serve --port=8080
```

### 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` 中的 `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 过期 → 重新登录（access_token 默认 2 小时，refresh_token 7 天）
2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
3. `JWT_SECRET` 变更 → 旧令牌全部失效，重新登录即可
4. Redis 中会话被清除（如重启 Redis、执行 `FLUSHDB`）→ 重新登录

## 前端相关

### Q: `pnpm install` 报错

A: 清除缓存重新安装：

```bash
# 删除依赖目录和锁文件，重新安装
rm -rf node_modules pnpm-lock.yaml      # 删除旧的依赖和锁文件
pnpm install                             # 重新安装所有依赖
```

### Q: 前端请求后端 404

A: 检查以下几点：

1. 后端服务是否启动（`curl http://localhost:8000/api/captcha` 验证）
2. Vite 代理配置是否正确（`vite.config.ts` 中的 `target`，改完重启 `pnpm dev`）
3. API 路径是否正确（应以 `/api` 开头）

### Q: 页面白屏

A: 打开浏览器控制台（F12）查看错误信息，常见原因：

1. JS 加载失败 → 检查网络请求
2. 路由配置错误 → 检查后端菜单数据（`/api/index/getMenus` 是否正常返回）
3. Token 过期 → 重新登录

## 数据库初始化相关

### Q: `composer setup` / `php artisan migrate` 后依然提示表不存在？

A: 正常现象。本项目 `database/migrations/` 为空，**建表以 SQL 脚本为准**，`migrate` 只初始化迁移记录表。请手动导入：

```bash
mysql -uroot -proot rxthinkcmf.laravel13.elevue < document/mysql/rxthinkcmf.laravel13.elevue.sql
```

详见 [2.5 数据库初始化](/zh/quickstart/database-init.html)。

### Q: 导入 SQL 很慢或中断？

A: 脚本约 226MB（含全国行政区划等大数据量表），导入需 1~3 分钟属正常。确保：

1. 数据库字符集为 `utf8mb4`
2. 命令行窗口保持打开直到导入完成
3. MySQL 的 `max_allowed_packet` 足够（默认 64MB 一般够用，不足时调大）

## Docker 相关

### Q: Docker 启动后 mysql 一直 unhealthy？

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)。