Ubuntu20.04下VSCode的Xdebug无法触发Laravel项目断点求助

已知环境信息 #

• 操作系统：Ubuntu 20.04
• PHP版本：7.4.3
• Xdebug版本：v2.9.2
• IDE：VSCode

问题现象 #

Xdebug在其他PHP项目可正常命中断点，仅Laravel项目内断点失效。

解决步骤 #

1. 补充VSCode launch.json路径映射配置 #

当前配置缺少本地项目路径与服务端路径的映射规则，是Laravel项目Xdebug断点失效的最常见原因。修改launch.json中Listen for XDebug配置块，新增pathMappings参数：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "log": true,
            // 新增路径映射规则，左侧替换为你的Laravel项目在系统中的绝对路径
            "pathMappings": {
                "/var/www/laravel项目根目录": "${workspaceFolder}"
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000,
            "log": true
        }
    ]
}

2. 清空Laravel各类缓存 #

Laravel的路由、配置缓存会导致代码路径与运行路径不匹配，无法触发断点，执行以下命令清空缓存：

php artisan optimize:clear
php artisan route:clear
php artisan config:clear

如果开启了OPcache，需要在php.ini中新增以下配置，避免缓存导致的代码不更新问题：

opcache.validate_timestamps = 1
opcache.revalidate_freq = 0

修改完成后重启PHP-FPM服务生效：sudo systemctl restart php7.4-fpm

3. 查看Xdebug日志确认问题 #

你已配置Xdebug日志路径为/tmp/xdebug.log，触发一次Laravel接口/页面请求后，执行以下命令查看日志：

cat /tmp/xdebug.log

如果日志中出现breakpoint not set或路径不匹配的提示，回到第一步调整pathMappings的路径参数即可。

4. .env配置验证 #

你当前的.env配置无需调整，保持APP_ENV=local、APP_DEBUG=true即可，这两个参数不会影响Xdebug断点命中。

内容的提问来源于stack exchange，提问作者Aref Mardani