1. 安装Xdebug扩展
在Ubuntu终端中执行以下命令安装Xdebug：
sudo apt-get update
sudo apt-get install php-xdebug
安装完成后，需确认Xdebug是否成功加载：
php -m | grep xdebug
若输出xdebug则表示安装成功。
2. 配置php.ini文件
找到当前PHP版本的php.ini文件（路径通常为/etc/php/{php_version}/cli/php.ini、/etc/php/{php_version}/apache2/php.ini或/etc/php/{php_version}/fpm/php.ini，{php_version}替换为你的PHP版本，如8.1）。
用文本编辑器（如nano）打开文件，添加以下Xdebug配置：
zend_extension=xdebug.so # 若未自动找到路径，需替换为实际路径（如/usr/lib/php/20210902/xdebug.so）
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes # 自动触发调试（可选：trigger/yes）
保存并关闭文件。
3. 重启Web服务器
根据使用的Web服务器类型，执行对应重启命令：
- Apache：
sudo systemctl restart apache2 - Nginx + PHP-FPM：
sudo systemctl restart nginx sudo systemctl restart php{php_version}-fpm # 如php8.1-fpm
4. 配置PhpStorm
4.1 设置PHP解释器
打开PhpStorm，点击顶部菜单File > Settings（或Ctrl+Alt+S），展开Languages & Frameworks > PHP，点击Interpreter右侧的齿轮图标，选择Add，选择系统中已安装的PHP解释器（如/usr/bin/php），确保PHP Version显示正确。
4.2 添加Servers配置
在PHP设置页面，点击Servers标签，点击+添加新服务器：
- Name：自定义服务器名称（如
Local Server）； - Host：输入
localhost（或服务器IP）； - Port：输入
80（HTTP）或443（HTTPS）； - 勾选
Use path mappings（可选，用于映射项目路径，如将本地项目路径映射到服务器虚拟路径）；
点击OK保存。
4.3 配置Debug设置
在PHP设置页面，点击Debug标签，确保Xdebug已启用，且Debug port设置为9003（与php.ini中的client_port一致）。
5. 设置断点
在PhpStorm中打开需要调试的PHP文件，在代码行号左侧空白处单击，会出现红色圆圈，表示断点设置成功。可设置多个断点。
6. 启动调试会话
6.1 方式一：启动调试监听
点击PhpStorm右上角的绿色电话图标（或按Shift+F9），启动调试会话。此时PhpStorm会等待调试连接。
6.2 方式二：创建PHP Web Page配置（可选）
若需通过浏览器直接触发调试，可点击Run > Edit Configurations，点击+选择PHP Web Page，填写：
- Name：自定义配置名称（如
Xdebug Debug）； - Start URL：输入要调试的页面URL（如
/index.php）； - Server：选择之前添加的服务器（如
Local Server）； - Debugger：选择
Xdebug；
点击OK保存。之后可直接点击右上角的绿色三角形图标（或按Shift+F10）启动调试。
7. 触发断点并调试
在浏览器中访问配置的URL（如http://localhost/index.php），当代码执行到断点时，PhpStorm会自动暂停，进入调试模式。此时可：
- 查看变量值（在
Variables面板）； - 查看调用堆栈（在
Debug窗口）； - 使用调试工具栏按钮逐步执行（
Step Over/F8、Step Into/F7、Step Out/Shift+F8）； - 继续执行（
Resume Program/F9）。
8. 结束调试
调试完成后，点击调试工具栏中的红色方块按钮（或按Ctrl+F2），结束调试会话。
常见问题排查
- Xdebug未加载：检查
php.ini中的zend_extension路径是否正确，重启Web服务器； - 端口冲突：确保
9003端口未被其他程序占用（可通过netstat -tulnp | grep 9003检查）； - 断点不生效：确认
xdebug.start_with_request=yes已设置，且PhpStorm的Debug port与php.ini一致。