PHP 在 Ubuntu 上出错时，最怕的不是报错本身，而是不知道该先看哪里。开发环境适合直接把错误抛到页面上，生产环境则更依赖日志，而遇到逻辑分支、变量值异常这类问题，单靠报错信息往往还不够。
下面按“页面错误显示、日志追踪、Xdebug 断点调试”三层方式整理一遍，并补上权限、服务重启和配置自检这些常见细节。看完后，你可以根据当前环境快速判断该改 php.ini、查哪份日志，还是直接进 IDE 单步跟踪。
开发环境先开错误显示
在开发环境里，最快的排查方式通常是直接显示 PHP 错误。这样语法错误、未定义变量、函数调用问题，都会立即出现在浏览器页面里，不需要先翻日志。
先找到正在生效的 php.ini
先用下面的命令确认配置文件位置：
php --ini常见路径包括：
/etc/php/8.2/apache2/php.ini/etc/php/8.2/fpm/php.ini
具体使用哪一个，取决于你当前跑的是 Apache，还是 Nginx + PHP-FPM。
修改关键报错参数
找到文件后，可以用 sudo nano 等编辑器打开，并确认下面几项配置：
display_errors = On # 开启错误显示
error_reporting = E_ALL # 报告所有类型错误
log_errors = On # 同时记录错误日志
error_log = /var/log/php_errors.log # 可选，自定义日志路径这几项的作用可以直接理解为：
display_errors = On：把错误输出到页面error_reporting = E_ALL：尽量不要漏掉错误类型log_errors = On：保留日志记录，方便回看error_log = /var/log/php_errors.log：把日志写到指定文件，便于集中排查
如果只是本地开发，这一组配置通常已经足够解决大部分基础问题。
修改后记得重启服务
保存 php.ini 后，配置不会自动生效，需要重启对应服务。
Apache 用户执行：
sudo systemctl restart apache2Nginx + PHP-FPM 用户则需要重启 PHP-FPM 和 Nginx：
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx完成后再访问页面，通常就能直接看到 PHP 报错内容。
生产环境优先看错误日志
线上环境一般不会把 PHP 错误直接暴露给浏览器，这时候日志就是主要线索来源。尤其是数据库连接失败、包含路径错误、运行时异常这类问题，通常都能从日志里拿到文件名、行号和报错类型。
几份常见日志的位置
在 Ubuntu 上，常见日志文件通常包括：
- Apache：
/var/log/apache2/error.log - Nginx：
/var/log/nginx/error.log - PHP-FPM：
/var/log/php8.2-fpm.log
如果你已经在 php.ini 里自定义了 error_log，那就优先检查自定义路径，例如 /var/log/php_errors.log。
用 tail -f 实时追踪报错
排查时最实用的方式之一，是边触发请求边盯日志更新：
sudo tail -f /var/log/php_errors.log # 查看自定义日志
sudo tail -f /var/log/apache2/error.log # 查看Apache日志如果页面一访问就报错，这种实时跟踪方式通常能最快对上时间点。日志里常见的信息包括：
- 错误类型
- 发生文件
- 具体行号
- 调用上下文
对于“页面白屏但没有明显提示”的情况，这一步尤其重要。
复杂问题再上 Xdebug
当问题不是简单的语法错误，而是逻辑分支走错、变量值异常、函数调用链太长时，日志往往只能告诉你“哪里出错了”，却很难说明“为什么会走到这里”。这时就该用 Xdebug 做断点调试。
安装 Xdebug 扩展
先安装扩展包：
sudo apt-get install php-xdebug如果你使用的是明确版本的 PHP，包名也可能是：
php8.2-xdebug在 php.ini 中加入调试配置
安装后，在 php.ini 中加入或确认以下内容：
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes其中几个关键点值得注意：
xdebug.mode=debug：启用调试模式xdebug.client_host=127.0.0.1：指定 IDE 监听地址xdebug.client_port=9003：Xdebug 3 默认常用端口xdebug.start_with_request=yes：请求到来时自动尝试启动调试
改完配置后，同样要重启 PHP 相关服务。
以 PhpStorm 为例配置 IDE
接下来在 IDE 中完成服务映射。以 PhpStorm 为例，进入：
File > Settings > Languages & Frameworks > PHP > Servers然后添加服务器，重点设置这些信息：
- 主机：
127.0.0.1 - 端口：
80或443 - 勾选
Use path mappings - 把项目目录映射到实际运行路径
完成后，在代码里打断点，点击 IDE 的“Start Debugging”按钮，再访问对应页面，程序就会在断点处暂停。此时你可以直接查看变量值、调用栈和执行路径，比单纯翻日志更适合处理复杂问题。
别忽略这些辅助排查细节
很多 PHP 问题表面上像代码错误，实际却和权限、版本或配置文件本身有关。这几项可以顺手检查。
确认 Web 服务用户有权限访问文件
Web 服务器用户通常是 www-data。如果它没有读取项目文件或日志目录的权限，错误信息可能不完整，甚至会引出新的权限报错。
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html及时更新 PHP 和扩展
部分异常可能来自已知 bug，更新系统包和 PHP 扩展能减少这类问题：
sudo apt update && sudo apt upgrade php修改配置后先做一次语法检查
改完 php.ini 或相关配置后，可以先检查语法，避免因为配置写错导致服务启动失败：
php -c /path/to/php.ini -l这一步成本很低，但能提前拦住不少低级错误。
不同场景怎么选排查方式
如果是本地开发，优先开启 display_errors，速度最快；如果是线上环境，先看 error.log 和 PHP-FPM 日志；如果已经能复现问题，但报错信息解释不了原因，就直接切到 Xdebug。
简单说，页面报错适合找“明显错误”，日志适合找“运行时线索”，Xdebug 适合查“执行过程为什么不对”。把这三种方式配合起来，Ubuntu 上的大多数 PHP 问题都能更快定位。
