服务器环境配置常见错误与处理
汇总安装部署阶段的高频报错，按现象、原因、处理三步给出排查与修复方法。
一、安装向导连接数据库失败
现象：填写数据库信息后提示连接失败。按顺序核对：
- 库名、账号、密码、端口是否与面板中完全一致，注意密码不要带多余空格。
- 数据库主机：同机用
localhost或127.0.0.1，远程库需在数据库权限中放行来源 IP。 - 账号是否拥有该库权限，缺少授权时补齐：
GRANT ALL ON 库名.* TO '账号'@'localhost';，再FLUSH PRIVILEGES;。 - 数据库服务是否运行，可用
systemctl status mysqld查看。
二、提示“未能写入输出文件”或全站 500
这类报错多由运行用户没有写权限引起：PHP 需要写日志、缓存与临时目录。
# 确认站点运行用户
ps aux | grep nginx | head
# 修正属主与可写目录
chown -R www:www /www/wwwroot/你的域名
chmod -R 755 /www/wwwroot/你的域名/data同样要检查 upload/、data/ 两个可写目录；PHP-FPM 的临时目录被占满或不可写，也会出现同类报错。
三、扩展缺失与版本不匹配
访问首页出现白屏或报错，先看 PHP 错误日志，常见于扩展未装或版本不符：
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 白屏无输出 | 缺 pdo_mysql 或 PHP 版本过低 | 切换 PHP 8.2 并安装 pdo_mysql |
| 图片无法处理 | 缺 gd | 安装并启用 gd 扩展 |
| 验证码不显示 | 缺 gd 或 session 目录不可写 | 安装 gd，检查 session 保存路径权限 |
| 中文乱码 | 连接未指定 utf8mb4 | 库与连接统一 utf8mb4 |
四、502 / 504 网关错误
- 502：PHP-FPM 未启动或崩溃，查看
php-fpm.log，必要时重载；访问量大时适当调大pm.max_children。 - 504：脚本执行超时，多出现在批量操作，可临时提高 Nginx
fastcgi_read_timeout与 PHPmax_execution_time，调完复查。 - PHP-FPM 反复重启多为内存不足被系统终止，先降并发，再考虑扩容。
五、通用排查手法
- 先看 Nginx 站点日志与 PHP 错误日志，定位文件与行号，不要凭猜测改配置。
- 临时开启
display_errors复现一次，拿到真实报错后立即关闭。 - 用备份做二分：先恢复模板目录，再恢复 app、core 目录，逐层缩小到单个文件。
- 每次只改一处，改完立即复测，避免多个变量叠加后无法判断因果。
环境问题八成落在权限、扩展、版本三者之一，按这三项对照往往最快定位。