需启用PHP扩展调试模式：一、编译时加--enable-debug和--enable-zts；二、设ZEND_DONT_UNLOAD_MODULES、USE_ZEND_ALLOC等环境变量；三、在php.ini中配置扩展debug选项；四、用GDB附加进程动态调试；五、PHP 8.2+可用--runtime-debug参数。
如果您在开发或调试PHP扩展时需要查看详细的运行日志、函数调用栈或内存分配行为，则需启用PHP扩展的调试模式。以下是开启PHP扩展调试模式的具体操作步骤：
一、编译时启用ZEND_DEBUG和DEBUG_ZTS
PHP扩展的底层调试能力依赖于PHP内核在编译阶段开启的调试宏。未启用这些宏时，扩展无法输出调试信息或触发断点。必须重新编译PHP源码，并传入对应配置参数。
1、进入PHP源码根目录，执行 ./configure 命令并添加 --enable-debug 参数。
2、添加 --enable-zts（仅多线程环境需要）以确保线程安全调试符号可用。
立即学习“PHP免费学习笔记（深入）”；
3、运行 make clean && make && sudo make install 完成编译安装。
4、验证是否生效：执行 php -i | grep "Debug"，确认输出中包含 debug => enabled 和 zts => enabled（如适用）。
二、设置环境变量启用扩展级调试输出
部分PHP扩展（如xdebug、opcache、pcov）支持通过环境变量控制调试行为。这些变量在PHP进程启动前生效，影响扩展初始化阶段的行为。
1、在终端中执行 export ZEND_DONT_UNLOAD_MODULES=1，防止调试过程中模块被意外卸载。
2、设置 export USE_ZEND_ALLOC=0，禁用Zend内存管理器，便于使用valgrind或AddressSanitizer检测内存问题。
3、若扩展支持，导出扩展专属变量，例如 export PHP_EXT_DEBUG_LOG=/tmp/ext_debug.log。
4、启动PHP CLI或Web服务器前确保环境变量已加载，可通过 echo $USE_ZEND_ALLOC 验证。
三、修改php.ini启用扩展调试选项
某些扩展提供ini配置项用于开启调试日志、错误追踪或内部状态报告。这些选项通常默认关闭，需手动激活。
1、打开当前生效的php.ini文件，可通过 php --ini 查找路径。
2、定位到目标扩展配置段，例如 [xdebug] 或 [opcache]。
3、添加或修改配置项：xdebug.mode = debug、opcache.debug = 1、extension.debug = On（依扩展而定）。
4、保存后重启Web服务器或PHP-FPM进程，执行 php -m | grep 扩展名 确认加载成功。
四、使用GDB附加到PHP进程进行动态调试
当需要单步跟踪扩展C代码执行流程、检查变量值或分析崩溃现场时，可借助GDB对正在运行的PHP进程进行实时调试。
1、启动PHP脚本并保持其运行，例如 php /path/to/script.php &。
2、获取进程PID：ps aux | grep "php script.php"，记录对应PID。
3、执行 gdb -p PID 进入调试会话。
4、输入 set follow-fork-mode child 启用子进程跟踪（适用于FPM或Web请求场景）。
5、在扩展关键函数处下断点，例如 break myext_do_something。
五、启用PHP内置的--runtime-debug参数
PHP 8.2+ 版本引入了 --runtime-debug 命令行参数，可在不重新编译的情况下启用部分运行时调试功能，包括扩展函数调用日志与类型检查增强。
1、确认PHP版本不低于8.2：php -v 输出中显示 8.2.x 或更高。
2、执行 php --runtime-debug -d extension=myext.so /path/to/test.php。
3、观察标准错误输出中是否出现 [RUNTIME DEBUG] calling myext_function 类似提示。
4、该参数仅对CLI SAPI有效，Web服务器环境不可用。
