翻旧账。 写代码的日子总是充满意外——有时一个小小的逻辑错误，就会让页面崩溃得像被雷劈了一样。别慌， PHPStorm + Xdebug 的黄金组合，能把这些“坑”瞬间变成可视化的线索，让你在 Ubuntu 上畅快地追踪每一次函数调用、每一个变量变化。下面我把从零开始的完整流程，用最接地气的语言一步步拆解，帮你省去摸索的时间。

一、 环境准备：让系统先做好“热身”

在正式敲代码之前，请确保你的 Ubuntu 已经装好了 PHP 与对应版本的 Xdebug。下面这几行命令，是我每天早上打开终端必打的“仪式”。

sudo apt-get update
sudo apt-get install php php-cli php-fpm
# 根据实际 PHP 版本选择合适的 Xdebug 包， 比方说 PHP 8.1
sudo apt-get install php8.1-xdebug

如果你已经装了多个 PHP 版本，请务必确认 /etc/php/8.1/cli/php.ini里已经加载了 Xdebug，否则后面的调试步骤会卡壳。

二、 配置 Xdebug

Xdebug 的配置其实很直白，只需要往 php.ini 操作一波... 加几行关键指令就能让它跟 PHPStorm 打成一片。

① 找到正确的 php.ini 文件

• CLI 模式：/etc/php/8.1/cli/php.ini
• FPM 模式：/etc/php/8.1/fpm/php.ini
• Aapache2 模式：/etc/php/8.1/apache2/php.ini

我好了。 编辑文件，在末尾加入下面这段表格中列出的配置项。

# Xdebug 配置示例
zend_extension=/usr/lib/php/20220829/xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log_level=0
xdebug.idekey=PHPSTORM
xdebug.max_nesting_level=256
        

保存后记得重启对应服务：

# 如果使用 FPM
sudo systemctl restart php8.1-fpm
# Apache 场景下
sudo systemctl restart apache2
        

三、在 PhpStorm 中点燃调试火花 🎇

① 创建或打开项目并配置解释器

P​hpStorm 会自动探测系统里的 PHP 可施行文件。如果没有，请手动指定：，PTSD了...

• ACTION → Settings → Languages & Frameworks → PHP → CLI Interpreter → “+” 添加本地解释器。
• Clique “…”，选取 /usr/bin/php7.x 或 /usr/bin/php8.x。
\end{ul}

② 启动 Debug Listener🛎️

P​hpStorm 左上角有个 ③ 配置运行/调试配置 Select “+” → “PHP Web Application”。填入名称，如“本地项目”。 Select Server；如果是本机直接访问， 就填 localhost；若是容器，则填容器 IP 并勾选 “Use path mappings”。路径映射一定要对齐，否则断点永远不会生效！ The URL field 填写入口页面如 http://localhost/myproject/index.php 。保存。 \end{ol} 四、设置断点 & 开始你的“追踪之旅” 🚀️️️️️️️️️️️︎︎︎︎︎︎︎︎⁣⁣⁣⁣⁣⁣⁣‍‍‍‍‍‍‍✦✦✦✦✦✦✦✦✦✦✦   — 小技巧来了！  — ✧✧✨✨✨✨✨✨✨✨✨✨. 只要在想观察变量或函数返回值的位置左侧单击，就会出现一个鲜红的小圆点——这就是断点。 我不敢苟同... 别忘了给关键循环或者异常捕获处都安上“小哨兵”，否则错误可能悄悄跑掉。 温馨提醒：如果你在浏览器里使用 Chrome 的「XDebug Helper」插件， 只要点击「Start Debugging」按钮，再刷新页面IDE 就会立刻弹出断点停留画面。 请大家务必... 没装插件？没关系，直接在地址栏加上?XDEBUG_SESSION_START=PHPSTORM&...`也能触发。 五、 实战演练：一步步追踪代码施行过程 🕵️‍♂️🕵️‍♀️             ‑‑‑–——–―――――‑‑‑‐‑‐‐−−−−—–—–‒‒‒‒‒‒---​ – ——  **关键操作** —​ — ‑‑‑ ​—​ —​​     : 公正地讲... Step Over : 跳过当前行，仅施行不进入函数内部；适合快速扫过无关紧要的逻辑。 Step Into : 深入到函数体内部，你可以看到参数是怎么被传递和修改的；常用于排查黑盒库。 Step Out : 从当前函数跳出返回到调用者；当你已经看清楚内部细节后用它回到上一层视野。 Evaluate Expression : 随时输入任意 PHP 表达式查看即时后来啊；比起打印日志， 这招更优雅、更平安。 ⚡Toggle Breakpoint : 快速启停断点，让你随心所欲地控制哪段代码需要被监控。 \ \ \ . .，改进一下。