Ubuntu PHP错误快速排查与修复清单

遇到PHP报错先别慌，按照下面这个清晰的路径走，绝大多数问题都能快速定位并解决。核心思路是：先看日志，再分模块，最后针对性修复。

一、最快定位路径

第一步永远是查看错误日志，它能直接告诉你问题是出在PHP语法、扩展、Web服务器配置，还是代码本身。这是最高效的起点。

• 日志文件在哪里？
  • Apache：日志通常在 /var/log/apache2/error.log
  • Nginx：查看 /var/log/nginx/error.log
  • PHP-FPM：日志可能在 /var/log/php-fpm.log 或版本化的 /var/log/php7.x-fpm.log
• 如何实时追踪？ 打开终端，执行 sudo tail -f /var/log/apache2/error.log 或 sudo tail -f /var/log/nginx/error.log，然后刷新网页，错误信息就会实时滚动出来。

确认你的PHP环境：运行 php -v 查看版本，用 php --ini 找到当前加载的配置文件路径。

一个必须牢记的步骤：任何配置修改或扩展安装后，务必重启相关服务才能生效：

• Apache：sudo systemctl restart apache2
• Nginx：sudo systemctl restart nginx
• PHP-FPM：sudo systemctl restart php7.x-fpm（记得将 7.x 替换为你的实际版本）

二、常见错误与一键修复

根据日志提示的错误类型，下面这些是最高频的“案发现场”和标准处理流程。

• 502 Bad Gateway（常见于 Nginx + PHP-FPM 架构）
  • 先查状态：运行 sudo systemctl status php7.x-fpm，看看FPM服务是否在运行。如果没运行，执行 sudo systemctl start php7.x-fpm && sudo systemctl enable php7.x-fpm 启动并设置开机自启。
  • 再核配置：检查Nginx站点配置中 fastcgi_pass 指令指向的地址（如Unix套接字 unix:/run/php/php7.0-fpm.sock; 或端口 127.0.0.1:9000），必须与PHP-FPM的实际监听地址一致。
  • 最后重启：sudo systemctl restart nginx。
• 权限被拒绝或访问异常
  • 这通常是Web目录或文件的所有权问题。将项目目录的所有者改为Web服务器用户（通常是 www-data）：

    sudo chown -R www-data:www-data /path/to/php/files
    sudo chmod -R 755 /path/to/php/files

• 缺少扩展（如 mbstring、gd、mysql）
  • 使用apt命令安装即可：sudo apt-get install php-mbstring php-gd php-mysql。
  • 安装后，别忘了重启Apache、Nginx或PHP-FPM服务。
• 配置文件错误
  • 用 php --ini 找到正在使用的 php.ini 文件，检查并修正其中的语法错误或配置冲突，然后重启服务。
• 开发环境需要看到详细错误
  • 在对应的php.ini文件中（区分Apache、CLI或FPM）设置：

    display_errors = On
    error_reporting = E_ALL

  • 重要提醒：这个设置绝对不要用于生产环境，否则会暴露敏感信息。

三、开发环境开启调试

对于需要深入追踪逻辑的开发者，配置一个调试器是最高效的方法。

• 安装Xdebug：sudo apt-get install php-xdebug
• 配置Xdebug：在对应的php.ini文件末尾添加以下配置（路径根据你的PHP版本调整，如 /etc/php/7.4/apache2/php.ini）：

  [Xdebug]
  zend_extension=xdebug.so
  xdebug.mode=debug
  xdebug.start_with_request=yes
  xdebug.client_port=9003

• 重启服务：sudo systemctl restart apache2 或 sudo systemctl restart php7.4-fpm。
• 性能提示：Xdebug会显著增加性能开销，仅限在开发调试时启用。

四、一键排错命令清单

最后，把这些最常用的命令收好，它们能覆盖90%以上的日常排错场景。

• 查看环境：php -v（版本），php --ini（配置）
• 追踪日志：sudo tail -f /var/log/apache2/error.log 或 sudo tail -f /var/log/nginx/error.log
• 服务管理：
  • 查状态：sudo systemctl status apache2（或 nginx、php7.x-fpm）
  • 重启：sudo systemctl restart apache2（或 nginx、php7.x-fpm）
  • 设自启：sudo systemctl enable php7.x-fpm
• 安装扩展：sudo apt-get install php-{extension-name}（例如 php-mbstring、php-gd）
• 修复权限：sudo chown -R www-data:www-data /var/www/html，sudo chmod -R 755 /var/www/html