Debian PHP配置中常见错误有哪些

Debian PHP配置常见错误与排查要点

说实话，在Debian上折腾PHP环境，翻来覆去就那么几件事——模块、通信、权限、语法、源。下面把这些坑一个一个掰开来看，省得大家再走弯路。

模块与扩展相关

• 最典型的莫过于调用mysql_connect时直接摔了个Fatal error: Call to undefined function。不用慌，多半是PHP模块没装或者没启用。老项目用php-mysql，新项目建议上php-mysqli或php-pdo_mysql。装上之后别忘了phpenmod mysql，然后重启服务（systemctl restart php8.2-fpm或service apache2 restart）。
• Apache搭配PHP-FPM时，如果访问.php文件直接变成下载或空白页，大概率是漏了libapache2-mod-phpX.Y-fpm这个包。安装后执行a2enmod phpX.Y-fpm，再重启Apache即可。
• 历史遗留的扩展问题也常见，比如老版本的suhosin扩展文件已经丢失，PHP启动时直接报错。解决方案很简单：卸载掉无效扩展（例如aptitude purge php5-suhosin），然后重启FPM或Apache。

进程通信与网关错误

• Nginx + PHP-FPM组合下，502 Bad Gateway是高频问题。原因往往出在通信地址不匹配——Nginx配的UNIX Socket路径是/var/run/php/phpX.Y-fpm.sock，可FPM却在监听127.0.0.1:9000，或者反过来。统一两端配置（要么都用Socket，要么都用TCP端口），再检查一下FPM是否在运行（systemctl status phpX.Y-fpm），基本就能解决。
• PHP-FPM启动失败，有时候是因为运行时目录缺失，比如/var/run/php/不存在。手动创建目录（mkdir -p /var/run/php/php5）后重启即可。注意新版Debian的FPM默认使用/run/php/，包维护阶段会自动创建，一般不需要手动干预。
• 长时间运行后出现504 Gateway Timeout，通常是FPM进程处理能力或网关超时设置不合适。调大listen.backlog（比如1024），再根据业务负载调整pm.max_requests（200或更高），可以有效缓解内存泄漏带来的影响。

文件权限与访问控制

• Web目录属主或权限不对，直接报Permission denied。标准做法：把目录属主设为www-data:www-data，权限设为755（业务要求严格时可以再收紧）。一条命令搞定：chown -R www-data:www-data /var/www/html && chmod -R 755 /var/www/html。
• 开了UFW防火墙却忘了放行HTTP/HTTPS，浏览器端会显示连接被拒绝。放行规则很简单：ufw allow 'Apache Full'或者ufw allow 'Nginx Full'。

配置语法与版本管理

• php.ini或站点代码里藏着语法错误，导致服务异常。用php -l /etc/php/php.ini和php -l /var/www/html/index.php分别检查，修正错误后再重启服务。
• 多版本PHP并存时，配置路径容易搞混。用php --ini查看当前加载的php.ini和扩展目录，针对性修改对应版本的文件（比如/etc/php/8.2/和/etc/php/8.1/分开处理）。
• 修改FPM池配置（如www.conf）后启动失败或不生效。先检查语法，重点关注listen和pm相关参数。建议改之前备份原文件，改完再重启FPM（systemctl restart php8.2-fpm）。

网络源与依赖问题

• APT源不可用，装包或更新直接失败。换一个可用的镜像源，编辑/etc/apt/sources.list后执行apt update。
• 安装扩展时提示依赖不满足，比如缺少开发库。先装上对应的依赖包（常见的有libcurl4-gnutls-dev、libxml2-dev等），再安装扩展就顺畅了。
• 极少数环境开启了SELinux，导致PHP访问受限。临时的快速诊断办法：setenforce 0。正式环境则要为目录设置正确的安全上下文，用semanage fcontext配合restorecon搞定。