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: 检查以下几点：

1. MySQL 服务是否启动：systemctl status mysql
2. .env 中的数据库配置是否正确
3. 数据库用户是否有权限：GRANT ALL ON \rxthinkcmf.thinkphp6.elevue`.* TO 'root'@'localhost'`

Q: 登录返回 401

A: 可能原因：

1. Token 过期 → 重新登录
2. 请求头格式错误 → 确保是 Authorization: Bearer <token>
3. JWT 密钥不匹配 → 检查 .env 中的 JWT.SECRET

前端相关

Q: pnpm install 报错

A: 清除缓存重新安装：

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

Q: 前端请求后端 404

A: 检查以下几点：

1. 后端服务是否启动
2. Vite 代理配置是否正确（vite.config.ts 中的 target）
3. API 路径是否正确（应以 /api 开头）

Q: 页面白屏

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

1. JS 加载失败 → 检查网络请求
2. 路由配置错误 → 检查后端菜单数据
3. 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: 按以下顺序排查：

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）

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。