3.8 KiB
2.8 常见问题 FAQ
环境相关
Q: PHP 版本低于 8.2 能运行吗？
A: 不能。项目使用了 PHP 8.2 的强类型特性（如 readonly 属性、DNF 类型等），必须使用 PHP 8.2+。
Q: 缺少 PHP 扩展怎么办？
A: 运行 php -m 检查已安装的扩展。缺少的扩展参考 2.1 节 安装。最常见的是缺少 pdo_mysql 和 gd。
Q: Composer 安装很慢怎么办？
A: 配置中国镜像：
# 配置阿里云 Composer 镜像（加速依赖下载）
# -g → 修改全局配置（所有项目生效）
# repo.packagist → 设置 Packagist 仓库镜像地址
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
Q: Redis 不安装可以吗？
A: 可以。Redis 是可选的缓存驱动，不安装时使用 file 缓存。将 .env 中 CACHE.DRIVER 设为 file 即可。
启动相关
Q: php think run 报错 "Address already in use"
A: 端口被占用，更换端口：
# --port → 指定监听端口（默认 8000）
php think run --port 8080
Q: 数据库连接失败 "Connection refused"
A: 检查以下几点：
- MySQL 服务是否启动：
systemctl status mysql .env中的数据库配置是否正确- 数据库用户是否有权限：
GRANT ALL ON \rxthinkcmf.thinkphp8.elevue`.* TO 'root'@'localhost'`
Q: 登录返回 401
A: 可能原因：
- Token 过期 → 重新登录
- 请求头格式错误 → 确保是
Authorization: Bearer <token> - JWT 密钥不匹配 → 检查
.env中的JWT.SECRET
前端相关
Q: pnpm install 报错
A: 清除缓存重新安装：
# 删除依赖目录和锁文件，重新安装
rm -rf node_modules pnpm-lock.yaml # 删除旧的依赖和锁文件
pnpm install # 重新安装所有依赖
Q: 前端请求后端 404
A: 检查以下几点：
- 后端服务是否启动
- Vite 代理配置是否正确（
vite.config.ts中的target） - API 路径是否正确（应以
/api开头）
Q: 页面白屏
A: 打开浏览器控制台（F12）查看错误信息，常见原因：
- JS 加载失败 → 检查网络请求
- 路由配置错误 → 检查后端菜单数据
- Token 过期 → 重新登录
Oracle 相关
Q: ThinkPHP 连接 Oracle 需要哪个 PHP 扩展？
A: 需要 pdo_oci 扩展。ThinkPHP 的 Oracle 连接器通过 PDO 连接数据库（DSN 前缀 oci:dbname=），XAMPP 8.2 已自带 php_pdo_oci.dll，只需在 php.ini 中启用即可。
Q: XAMPP 下 pdo_oci 扩展加载失败怎么办？
A: 按以下顺序排查：
- 是否安装了 Oracle Instant Client 19c（x64）并解压到固定路径
- 该路径是否已添加到系统变量 PATH 中（不是用户变量）
- 是否安装了 VC++ 2015-2022 Redistributable（x64）
php.ini中extension=pdo_oci是否已去掉分号- XAMPP 是否完全关闭再启动（不是只点 Apache 的 Start/Stop）
Q: 命令行 php -m 能看到 pdo_oci，但浏览器 phpinfo() 里找不到？
A: Apache 作为 Windows 服务运行时，读取的是服务启动时的系统 PATH。如果在 Apache 启动之后才修改了 PATH 环境变量，Apache 不会感知到。解决方法：在 XAMPP 控制面板中完全停止 Apache，再重新启动。
Q: Oracle Instant Client 应该下载哪个版本？
A: 推荐下载 19c 的 Basic Package（x64）。下载地址：https://www.oracle.com/database/technologies/instant-client/downloads.html
Q: 为什么 Instant Client 必须解压到固定路径？
A: 因为系统 PATH 环境变量写入的是绝对路径。如果解压到桌面或下载文件夹，后续清理、移动或重命名都会导致 PATH 失效，PHP 无法加载 Oracle 客户端库。推荐路径：C:\oracle\instantclient_19_20。