PHP断点调试([wsl2|docker]+swoole+xdebug+phpstorm)

目录前沿环境前置条件的安装xdebug配置phpstorm服务器配置​编辑phpstorm中xdebug端口​编辑调试配置入口设置​编辑解释器配置​编辑运行/调试配置(hyperf)​编辑运行/调试配置(laravel)​编辑环境变量的参数配置好了​编辑docker的额外配置镜像中需要暴露端口​编辑端口绑定​编辑镜像配置好了# 框架相关的hyperfmineadminscan_cacheabledaemonizeworker_nummineadmin 不要使用php watch -Claravel# 浏览器插件chromefirefox解决laravel无法动态设置xdebug.mode的问题增加命令根目录新增一个serve.php# tips# 文档前沿在 PHP 开发领域dd()等传统调试方式曾长期占据主流但在面对 Hyperf 这类基于 Swoole 的高性能协程框架时其局限性逐渐凸显 —— 异步任务的执行流程难以追踪、常驻内存进程的状态无法实时观测调试效率大打折扣。而远程断点调试作为更高效的调试手段能直接在代码执行节点暂停、查看变量与调用栈成为解决这类问题的最优解。然而远程断点调试的配置涉及多环境联动WSL2 系统的 PHP 源码编译与扩展依赖、Xdebug 3.x 的参数适配、PhpStorm 与容器 / 本地服务的端口映射、Hyperf 框架的调试模式适配任何一个环节配置不当都会导致调试失败。网上现有教程多零散片面缺乏针对 WSL2DockerHyperf 组合场景的完整指引。基于此本文整合实战经验从环境搭建到调试验证逐步拆解全流程配置要点旨在为开发者提供一套可直接复用的远程断点调试方案助力提升 Hyperf 框架下的开发与排障效率。环境系统wsl2为什么不再win里面安装PHP,因为最新的swoole没有dllPHP8.1.31Swoole5.1.5Xdebug3.2.2前置条件的安装swoolepecl安装方式sudo pecl install --configureoptions enable-socketsno enable-opensslyes enable-http2yes enable-mysqlndyes enable-swoole-jsonno enable-swoole-curlyes enable-caresyes enable-swoole-pgsqlyes swoole-5.1.5swoole.use_shortnameOff 这些设置就参考swoole官方文档没有用hyperf的也不需要安装swoolexdebugpecl安装方式sudo pecl install xdebug-3.2.2xdebug配置可以通过 “php --ini” 找到你的xdebug.ini; Xdebug 3.2.2 完整配置 ; 扩展加载 zend_extensionxdebug.so [xdebug] ; 模式设置可多个模式用逗号分隔 ; debug - 调试模式 ; develop - 开发功能包括堆栈跟踪 ; coverage - 代码覆盖率 ; gcstats - 垃圾回收统计 ; profile - 性能分析 ; trace - 函数跟踪 xdebug.mode ; 自动发现客户端主机WSL2 推荐 xdebug.discover_client_host0 xdebug.client_host 127.0.0.1 ; 客户端端口 xdebug.client_port9001 ; 对于 Swoole 常驻内存应用建议使用 yes 而不是 trigger xdebug.start_with_requesttrigger ; xdebug.trigger_valuehantaohuang 这里一定要注释掉的不能填填了就只支持一个项目不填就是支持传进来的任何值 xdebug.max_nesting_level 512 ; 日志配置调试时启用 xdebug.log/tmp/xdebug.log xdebug.log_level7 ; 其他配置 tail -f /tmp/xdebug3 查看日志 xdebug.output_dir/tmp/xdebug3 xdebug.use_compression1 xdebug.connect_timeout_ms200tips:xdebug.mode 你可以统一的都设置为空或者offlaravel项目需要修改“php artisan serve”命令看下方文档如果不想修改命令则需要固定设置为develop,否则调试不会成功xdebug.log/tmp/xdebug.log 没配置好之前可能会频繁的看日志php --ri xdebug 可以看到你的实际配置xdebug.client_port9001 需要和后面的phpstrom配置一致xdebug.client_hosthost.docker.internal docker需要换成这个地址phpstorm服务器配置phpstorm中xdebug端口调试配置入口设置解释器配置运行/调试配置(hyperf)运行/调试配置(laravel)环境变量的参数PHP_IDE_CONFIGserverNameums 和你配置的服务器一致即可XDEBUG_TRIGGERumsService 随意取每个项目不一样即可配置好了docker的额外配置镜像中需要暴露端口端口绑定镜像registry.cn-chengdu.aliyuncs.com/mz-andy/php-nginx-alpine:8.1-hyperf-debugregistry.cn-chengdu.aliyuncs.com/mz-andy/php-nginx-alpine:8.1-laravel-debug按照下方的修改“php artisan serve”命令则可以不使用php-nginx-alpine:8.1-laravel-debug镜像我准备了阿里云的镜像不想搞环境的直接上docker实际测下来docker的方式没有直接在环境中跑php来得快启动时还是有卡顿不流程有需要dockerfile的留下邮箱配置好了照样显示连接成功docker ps之后你会发现多了一个实例# 框架相关的hyperfmineadminscan_cacheablepackage-ordering\config\config.php scan_cacheabletrue (因为hyperf断点调试的初始只能是代理类)daemonizepackage-ordering\config\autoload\server.php settings[ .... Constant::OPTION_DAEMONIZE false, ] # true时Xdebug 无法附着到前台进程断点调试会失效worker_numpackage-ordering\config\autoload\server.php settings[ .... Constant::OPTION_WORKER_NUM env(APP_DEBUG) ? 1 : swoole_cpu_num(), ] worker_num让它等于1就行了也就是APP_DEBUGtruemineadmin 不要使用php watch -C如果watch本身接受debug就会卡住不动这就是为啥有的人加入debug之后启动在文件监听那一块停止不动了的原因修改了代码之后需要像java一样重新启动。或者自己再取研究一下热启动laravel暂时没有发现需要特殊的地方# 浏览器插件chromehttps://chromewebstore.google.com/detail/xdebug-helper-by-jetbrain/aoelhdemabeimdhedkidlnbkfhnhgnhmfirefoxhttps://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/实测好像也不需要这个解决laravel无法动态设置xdebug.mode的问题原因是xdebug3的环境变量设置失败(这个没找到原因)但是可以通过-dxdebug.modedebug的方式动态设置[docker://registry.cn-chengdu.aliyuncs.com/mz-andy/php-nginx-alpine:8.1-hyperf-debug/]:php -dxdebug.modedebug -dxdebug.client_port9001 -dxdebug.client_hosthost.docker.internal /opt/project/artisan serve --port21981 --host0.0.0.0php artisan serve 里面执行的是 php -S .....把 外层的 -dxdebug.modedebug -dxdebug.client_port9001 -dxdebug.client_hosthost.docker.internal 参数给丢掉了xdebug3的环境变量设置又是失败的所以只能改 php artisan serve 这个命令期待官方修改 php artisan serve 增加 -dxdebug.mode 的动态设置方式增加命令创建一个命令 app\Console\MyServeCommand.php 并在app\Console\Kernel.php 中注册该命令?php namespace App\Console; use Illuminate\Foundation\Console\ServeCommand; use Symfony\Component\Process\PhpExecutableFinder; class MyServeCommand extends ServeCommand { /** * The console command name. * * var string */ protected $name serve; /** * Get the full server command. * * return array */ protected function serverCommand() { $server file_exists(base_path(server.php)) ? base_path(server.php) : __DIR__ . /../resources/server.php; $mode ini_get(xdebug.mode); return array_merge_recursive( [ (new PhpExecutableFinder)-find(false) ], $mode ? [ -dxdebug.mode . $mode ] : [], [ -S, $this-host() . : . $this-port(), $server ] ); } }根据laravel版本不同自行更改点到父级的serverCommand方法根目录新增一个server.php?php $publicPath getcwd(); $uri urldecode( parse_url($_SERVER[REQUEST_URI], PHP_URL_PATH) ?? ); // This file allows us to emulate Apaches mod_rewrite functionality from the // built-in PHP web server. This provides a convenient way to test a Laravel // application without having installed a real web server software here. if ($uri ! / file_exists($publicPath.$uri)) { return false; } require_once $publicPath./index.php;# tips先打断点再启动重启时端口被占用再多重启一次php -S 可以启用tpyii等其他框架php artisan serve --port8000 也只是对php -S的封装php --iniphp --ri xdebugtail -f /tmp/xdebug3关掉opcache# 文档https://xdebug.org/docs/all_settings#modehttps://www.jetbrains.com/zh-cn/help/phpstorm/debugging-a-php-cli-script.html#-26okhm_126