6.3 KiB
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 开发环境准备 安装。最常见的是缺少 pdo_mysql、gd 和 redis——redis 扩展缺失时报 Class "Redis" not found，验证码、登录直接不可用。
Q: Composer 安装很慢怎么办？
A: 配置中国镜像：
# 配置阿里云 Composer 镜像（加速依赖下载）
# -g → 修改全局配置（所有项目生效）
# repo.packagist → 设置 Packagist 仓库镜像地址
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
Q: Redis 不安装可以吗？
A: 不可以。 本项目强依赖 Redis：验证码、JWT 双令牌会话、权限缓存、字典缓存、会话/队列驱动均依赖它。Redis 相关问题（扩展安装、密码同步）见 2.1 开发环境准备 与 2.2 Laragon 环境搭建。
Q: shell 里执行 php artisan 报版本过低 / 找不到类？
A: PATH 中的 php 可能是旧版本（Laragon 默认 PATH 常指向低版本 PHP）。使用 8.3 的完整路径调用：
$PHP_HOME\php.exe artisan list
$PHP_HOME\php.exe vendor\bin\pint --test
启动相关
Q: php artisan serve 报 "Address already in use"
A: 端口被占用，更换端口：
# --port → 指定监听端口（默认 8000）
php artisan serve --port=8080
Q: 应用拒绝启动，报 JWT_SECRET 错误？
A: .env 中 JWT_SECRET 为空或不足 32 字符——应用启动时执行 fail-close 校验（不满足直接抛异常）。生成强随机密钥后重启：
openssl rand -base64 32 # 或 php -r "echo bin2hex(random_bytes(32));"
Q: 数据库连接失败 "Connection refused" 或表不存在？
A: 检查以下几点：
- MySQL 服务是否启动：
systemctl status mysql .env中的DB_*配置是否正确（DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_DATABASE）- 数据库是否已创建并导入
document/mysql/rxthinkcmf.laravel13.naivevue.sql（本项目 migrations 为空，不会自动建表） DB_PREFIX是否为laravel_（漏配会报Table 'xxx.users' doesn't exist）- 原生测试连接：
mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT 1;"
Q: 登录返回 401
A: 可能原因：
- Token 过期 → 重新登录（access_token 默认 2 小时，refresh_token 7 天）
- 请求头格式错误 → 确保是
Authorization: Bearer <token> JWT_SECRET变更 → 旧令牌全部失效，重新登录即可- Redis 中会话被清除（如重启 Redis、执行
FLUSHDB）→ 重新登录
前端相关
Q: pnpm install 报错
A: 清除缓存重新安装：
# 删除依赖目录和锁文件，重新安装
rm -rf node_modules pnpm-lock.yaml # 删除旧的依赖和锁文件
pnpm install # 重新安装所有依赖
Q: 前端请求后端 404
A: 检查以下几点：
- 后端服务是否启动（
curl http://admin.laravel13.naivevue/api/captcha验证） - Vite 代理配置是否正确（
vite.config.ts中的target，改完重启pnpm dev） - API 路径是否正确（应以
/api开头）
Q: 页面白屏
A: 打开浏览器控制台（F12）查看错误信息，常见原因：
- JS 加载失败 → 检查网络请求
- 路由配置错误 → 检查后端菜单数据（
/api/index/getMenus是否正常返回） - Token 过期 → 重新登录
数据库初始化相关
Q: composer setup / php artisan migrate 后依然提示表不存在？
A: 正常现象。本项目 database/migrations/ 为空，建表以 SQL 脚本为准，migrate 只初始化迁移记录表。请手动导入：
mysql -uroot -proot rxthinkcmf.laravel13.naivevue < document/mysql/rxthinkcmf.laravel13.naivevue.sql
详见 2.5 数据库初始化。
Q: 导入 SQL 很慢或中断？
A: 脚本约 226MB（含全国行政区划等大数据量表），导入需 1~3 分钟属正常。确保：
- 数据库字符集为
utf8mb4 - 命令行窗口保持打开直到导入完成
- MySQL 的
max_allowed_packet足够（默认 64MB 一般够用，不足时调大）
Docker 相关
Q: Docker 启动后 mysql 一直 unhealthy？
A: 首次启动需导入约 226MB SQL，健康检查已预留缓冲（1~3 分钟）。查看进度：
docker compose logs -f mysql
详见 2.8 Docker 快速体验。
Q: Docker 启动即退出，日志报 JWT_SECRET？
A: 容器内读取的 JWT_SECRET 不足 32 字符。在 docker/.env.docker 中生成随机值后重启：
openssl rand -base64 32
docker compose restart app
Q: 本机 Laragon 与 Docker 端口冲突？
A: 修改 docker/.env.docker 中的宿主机端口（如 MYSQL_PORT=3307、REDIS_PORT=6380），容器内部通过服务名通信不受影响。见 2.8 Docker 快速体验 「端口冲突处理」。
认证与权限相关
Q: 接口返回 {"code":403,"msg":"无访问权限"}？
A: 当前账号角色缺少该接口的权限节点。到「系统管理 → 角色管理」为角色勾选对应菜单/按钮权限（权限码如 sys:user:add），或使用超级管理员账号测试。权限模型见 5.4 权限管理（RBAC）。
Q: 接口返回 {"code":401,"msg":"未授权，请先登录"}？
A: Token 缺失、无效或过期。检查：
- 请求头是否携带
Authorization: Bearer <token> - access_token 是否过期（默认 2 小时），过期后调
/api/refresh续签或重新登录 - 是否被踢下线 / 改密后全端失效（Redis 会话已清除）
Q: 接口都是 HTTP 200，怎么判断成功失败？
A: 项目约定 HTTP 状态码恒为 200（403 例外），以响应体 code 判断：code=0 成功，其他为失败；code=401 时前端跳转登录。见 8.1 统一响应格式。