说起在 Linux 上写 PHP， 很多朋友会抱怨「错误信息总是藏得太深」；而我呢，常常在凌晨三点被一行未捕获的 Notice 折磨得睡不着。 我好了。 别慌， 这篇文章把从系统准备到高级追踪的每一步都细致拆解，让你在 Debian 上的调试之路像喝咖啡一样顺畅。

一、为何在 Debian 上调试 PHP 如同探险？

Debian 以其「稳定」著称，却也正主要原因是如此，很多新手在配置 时会碰壁。Xdebug 是官方推荐的调试神器， 它把隐藏在后台的变量、调用栈和错误日志全部搬到可视化界面。只要装好它，你再也不用靠「猜」来定位 bug——每一次断点都是一次灯塔，为你指明前方。

二、 基础环境准备与错误可见性

1）系统更新 & Xdebug 安装

# 更新软件源
sudo apt-get update
# 安装 Xdebug
sudo apt-get install php-xdebug

安装完成后用下面的命令确认 Xdebug 已经被加载：

php -v   # 看到类似 “with Xdebug v3.x.x” 的字样即表示成功
php --ri xdebug   # 查看详细配置信息

2）让错误信息不再躲猫猫——php.ini 必备设置

打开对应的配置文件，比方说：

# 查找 php.ini 路径
php --ini
# 常见路径 /etc/php/8.2/apache2/php.ini 或 /etc/php/8.2/cli/php.ini
sudo nano /etc/php/8.2/apache2/php.ini

把下面几行打开或添加进去：

绝了... 小贴士：如果你正用 Nginx + php-fpm，只需要重启 php-fpm 即可。

三、IDE 联动：VS Code 与 PhpStorm 的对决

a）VS Code 配置步骤

左侧点击「运行」图标 → 创建.vscode/launch.json. Select “PHP Debug”。 走捷径。 接着将生成的模板改成如下：

{
    "version": "0.2.0",
    "configurations": 
}

// demo.php

# 按 F5 启动监听，然后访问对应 URL；IDE 会自动停住你可以查看变量、 摆烂。 调用栈甚至修改现场数据！ \end{ul} \end{ol}

b）PhpStorm 快速上手

A) 打开 Settings → Languages & Frameworks → PHP → Debug，把端口改成9003​ 。 B) 在 Servers 页面添加一个服务器条目，将本地项目根目录映射到远程路径 /var/www/html​ 。 摆烂。 C) 点击右上角的小虫子图标，「Start Listening for PHP Debug Connections」。此时只要浏览器插件激活，请求就会被捕获。断点设置方式和 VS Code 完全相同， 只是 UI 更加华丽～

四、命令行脚本与高级追踪技巧

a）CLI 调试其实比 GUI 更直接。当你只想快速定位某段函数逻辑时 可以这样启动：，希望大家...

# 开启 xdebug 调试模式
export XDEBUG_MODE=debug
export XDEBUG_CONFIG="client_port=9003 idekey=VSCODE_XDEBUG"
php -dxdebug.start_with_request=yes my_script.php

b）手动插入断点——如果 IDE 没有响应，可以使用原生函数：

// 任意位置强制暂停：
xdebug_break;   // 当 IDE 正在监听时这里会马上停住
// 把关键变量写入自定义日志：
error_log; // 第四个参数表示直接输出到 STDERR
error_log, 4);

C）性能分析 & 跟踪 Xdebug 除了调试，还能生成 trace 文件和 profiling 数据。只需要在 php.ini 加上：

xdebug.mode=profile,trace   # 一边开启两种功能  
xdebug.output_dir="/tmp/xdebug"

客观地说... - Trace 文件记录每一次函数入口/退出，可用 KCacheGrind 或 Webgrind 可视化查看。 - Profile 文件则提供耗时排行，让你发现“卡在哪儿”。这些工具往往比盲目加 log 更省事儿。

五、常见坑与解决方案

在理。 问题表现 快速定位办法 - 浏览器访问页面后没有任何断点触发 - 确认浏览器插件已打开 “Debug” 模式；检查是否使用了 HTTPS 且插件仅对 HTTP 生效；检查防火墙是否阻止了本机端口 9003。可以用 netstat -tunlp | grep 9003) - 错误日志根本不写入 /var/log/php_errors.log - 检查文件权限：确保 www-data 用户对该文件拥有写权限；如果目录不存在请先 mkdir -p /var/log && chown www-data:www-data /var/log 。一边确认 php.ini 中 log_errors 已设为 On 。 - Xdebug 报错 “Could not connect to client” - 检查 xdebug.client_host 是否指向你的开发机器 IP；若是容器内部运行， 需要把 host IP 映射进去，比方说 xdebug.client_host=172.17.0.1 。 - 使用 Docker 时 IDE 收不到断点 - 在 docker-compose.yml 中映射端口 9003:9003；并且将容器内 /usr/local/etc/php/conf.d/docker-php-ext-xd… 中的 xdebug.remote_host 设置为宿主机 IP。

- 部署后生产环境仍然显示错误页 - 确保生产服务器使用的是专用 php.ini， 其中 display_errors=Off； 对吧？ 一边通过 nginx/apache 配置禁止泄露详细信息，并开启 log_errors.

- 多个项目共用同一台服务器导致断点混乱 - 为每个项目设置不同的 idekey并在 IDE 中分别创建对应的 launch 配置；这样即使请求交叉，也能准确匹配到相应代码库，靠谱。。

基本上... 温馨提醒：每次修改 php.ini 后务必重启相应服务，否则新配置永远不会生效哦！ 六、 收官——让调试成为编码的一部分

    回首一路走来从一开始的「看不到报错」到现在可以站在代码旁边敲敲键盘、一步步逼出 bug，你是否也体会到了那份成就感？别忘了把这些配置写进文档，让团队新人能“一键上手”。毕竟一个好的开发环境，是提升效率最直接的利器。

不地道。 ©2026 技术分享社区 | 本文基于个人实践撰写，仅供学习交流。如有疑问，请留言交流。 关键词：Debian、PHP 调试、Xdebug、VS Code、PhpStorm、CLI 调试