在 VSCode 中调试 PHP 代码主要依赖 XDebug 扩展和 PHP Debug 插件,以下是详细步骤:
1. 准备工作
1.1 确保环境满足
- 已安装 PHP(建议 7.4+ 或 8.x),终端运行
php -v
确认。 - 已安装 VSCode 并配置好 PHP 基础插件(如
PHP Intelephense
)。
1.2 安装 XDebug
-
自动安装(推荐):
运行以下命令,根据提示操作:php -r "copy('https://xdebug.org/wizard', 'xdebug-wizard.php');" php xdebug-wizard.php
脚本会分析你的环境并给出安装指令(如下载的 DLL 或 SO 文件路径)。
-
手动安装:
- 访问 XDebug 官网,上传
phpinfo()
的输出,获取定制化安装指南。 - 将下载的
xdebug.so
(Linux/Mac)或xdebug.dll
(Windows)放到 PHP 扩展目录。 - 修改
php.ini
(通过php --ini
查找路径):[XDebug] zend_extension=path/to/xdebug.so # 替换为实际路径 xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_port=9003 # 默认端口 xdebug.idekey=VSCODE
- 重启 Web 服务器(如 Apache/Nginx)或 PHP-FPM。
- 访问 XDebug 官网,上传
1.3 验证 XDebug 是否启用
- 运行
php --version
,输出中应包含with XDebug
。 - 或创建一个
phpinfo.php
文件:
浏览器访问该文件,搜索<?php phpinfo();
XDebug
确认已加载。
2. 配置 VSCode 调试
2.1 安装 PHP Debug 插件
- 在 VSCode 扩展商店搜索
PHP Debug
(作者:XDebug),安装并重启 VSCode。
2.2 生成调试配置文件
- 点击左侧 调试图标(或
Ctrl+Shift+D
) → 顶部点击 “创建 launch.json”。 - 选择环境 PHP,自动生成如下配置:
{ "version": "0.2.0", "configurations": [ { "name": "Listen for XDebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html": "${workspaceFolder}" // 关键!映射服务器路径到本地 } } ] }
pathMappings
:如果代码在远程服务器或 Docker 中,需正确映射服务器路径到本地项目路径(如/var/www/html
→C:\project
)。
2.3 启动调试
- 在 PHP 文件中设置断点(点击行号左侧)。
- 按
F5
或点击 绿色播放按钮 启动调试。 - 访问对应的 PHP 页面(如
http://localhost/test.php
),触发断点。
3. 常见问题解决
3.1 断点不生效
- 检查
pathMappings
:确保服务器路径与本地路径正确映射。 - 验证 XDebug 连接:
在终端运行php -m | grep xdebug
(Linux/Mac)或php -m | findstr xdebug
(Windows),确认输出xdebug
。 - 查看日志:
在php.ini
中添加:
重启服务后检查日志文件。xdebug.log=/tmp/xdebug.log # Linux/Mac xdebug.log=C:\xdebug.log # Windows
3.2 端口冲突
- 默认端口为
9003
,如果被占用,修改php.ini
和launch.json
中的port
为其他值(如9000
)。
3.3 调试慢或超时
- 在
php.ini
中调整:xdebug.remote_timeout=600 # 超时时间(秒) xdebug.max_nesting_level=500 # 提高递归层数限制
4. 高级用法
4.1 调试 CLI 脚本
在 launch.json
中添加配置:
{
"name": "Launch CLI Script",
"type": "php",
"request": "launch",
"program": "${file}", // 调试当前文件
"cwd": "${workspaceFolder}"
}
然后打开终端,直接按 F5
调试。
4.2 调试 Docker 中的 PHP
- 确保容器内已安装 XDebug,且
php.ini
配置如下:xdebug.client_host=host.docker.internal # 或宿主机的本地 IP xdebug.client_port=9003
- 在
launch.json
中正确映射容器路径:"pathMappings": { "/var/www/html": "${workspaceFolder}" }
5. 验证调试效果
- 成功触发断点后,可以:
- 查看变量值(悬浮或侧边栏)。
- 单步执行(
F10
)、进入函数(F11
)。 - 修改代码后实时生效(需配合
xdebug.start_with_request=trigger
)。
遇到具体问题可以根据你的环境(如 Windows/WSL/Docker)和错误日志,进一步帮你排查! 🛠️