import{_ as s,o as e,c as i,a2 as t}from"./chunks/framework.BbmSSMjL.js";const k=JSON.parse('{"title":"2.9 常见问题 FAQ","description":"","frontmatter":{},"headers":[],"relativePath":"zh/quickstart/faq.md","filePath":"zh/quickstart/faq.md"}'),o={name:"zh/quickstart/faq.md"};function l(h,a,n,d,r,p){return e(),i("div",null,[...a[0]||(a[0]=[t('

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: 配置中国镜像：

bash
# 配置阿里云 Composer 镜像（加速依赖下载）\n# -g → 修改全局配置（所有项目生效）\n# repo.packagist → 设置 Packagist 仓库镜像地址\ncomposer 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 的完整路径调用：

bash
$PHP_HOME\\php.exe artisan list\n$PHP_HOME\\php.exe vendor\\bin\\pint --test

启动相关 ​

Q: php artisan serve 报 "Address already in use" ​

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

bash
# --port → 指定监听端口（默认 8000）\nphp 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.naivevue.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
# 删除依赖目录和锁文件，重新安装\nrm -rf node_modules pnpm-lock.yaml      # 删除旧的依赖和锁文件\npnpm install                             # 重新安装所有依赖

Q: 前端请求后端 404 ​

A: 检查以下几点：

  1. 后端服务是否启动（curl http://admin.laravel13.naivevue/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.naivevue < document/mysql/rxthinkcmf.laravel13.naivevue.sql

详见 2.5 数据库初始化。

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 快速体验。

Q: Docker 启动即退出，日志报 JWT_SECRET？ ​

A: 容器内读取的 JWT_SECRET 不足 32 字符。在 docker/.env.docker 中生成随机值后重启：

bash
openssl rand -base64 32\ndocker 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 缺失、无效或过期。检查：

  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 统一响应格式。

',63)])])}const u=s(o,[["render",l]]);export{k as __pageData,u as default};