PHP代码在Ubuntu如何调试
小樊
32
2025-11-14 21:27:16
Ubuntu下PHP调试实操指南
一 环境准备与版本确认
- 确认 PHP 版本与 SAPI：运行 php -v 查看版本；运行 php -m | grep -i xdebug 检查是否已安装 Xdebug；用 php --ini 定位正在使用的 php.ini（区分 CLI 与 FPM/Apache 的配置）。
- 注意 CLI 与 Web 环境使用不同的 php.ini，修改后需分别重启对应服务。
- 若需远程调试（本机或容器外 IDE），确保 Ubuntu 防火墙/云安全组放行调试端口（默认 9003）。
二 使用 Xdebug 3 进行断点调试（推荐）
- 安装 Xdebug（适配你的 PHP 版本，如 7.4/8.0/8.1/8.2/8.3）：
- Ubuntu 20.04/22.04 常见命令：sudo apt-get update && sudo apt-get install php-xdebug
- 配置 php.ini（仅示例关键项，建议放在对应 SAPI 的 php.ini 末尾）：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003
- xdebug.start_with_request=yes
- 可选：xdebug.idekey=PHPSTORM（与 IDE 约定一致）
- 重启服务：
- Apache：sudo systemctl restart apache2
- Nginx + PHP-FPM：sudo systemctl restart php{version}-fpm && sudo systemctl restart nginx
- VS Code 调试配置（.vscode/launch.json）：
- {
“version”: “0.2.0”,
“configurations”: [
{
“name”: “Listen for Xdebug”,
“type”: “php”,
“request”: “launch”,
“port”: 9003,
“pathMappings”: {
“/var/www/html”: “${workspaceFolder}”
}
}
]
}
- PhpStorm：Settings → PHP → Debug 设置端口 9003，使用 Xdebug 作为调试器；CLI 脚本可直接“Run/Debug”配置。
- 触发调试：浏览器访问对应 URL 或在 CLI 下执行脚本，命中断点后查看变量、调用栈与单步执行。
三 无调试器的快速定位方法
- 内置打印与日志：
- 临时输出：var_dump($var); print_r($var); exit;
- 写入日志：error_log(‘msg’, 0); 或指定文件：error_log(‘msg’, 3, ‘/var/log/php_app.log’);
- 开启错误报告（开发环境 php.ini）：
- error_reporting=E_ALL
- display_errors=On（生产建议 Off）
- log_errors=On
- error_log=/var/log/php_errors.log（确保目录与文件可写）
- 验证日志：故意触发错误并检查 /var/log/php_errors.log 是否写入。
四 常见问题与排查清单
- 端口占用：检查 9003 是否被占用（如：ss -lntp | grep 9003），必要时更换端口并同步 IDE 与 php.ini。
- 配置未生效：确认修改的是对应 SAPI 的 php.ini（CLI 与 FPM/Apache 不同）；修改后重启 Apache/php-fpm。
- 路径映射错误：VS Code 的 pathMappings 必须与服务器路径一致（如 /var/www/html ↔ 本地工作区）。
- 防火墙/安全组：远程调试需放行 9003；本机回环 127.0.0.1 无需放行。
- 旧版 Xdebug 2 配置不兼容：若看到 xdebug.remote_enable 等参数，说明是 Xdebug 2，建议升级到 Xdebug 3 并使用新参数。
五 进阶建议
- 使用单元测试：结合 PHPUnit 做回归与边界测试，提升稳定性与可维护性。
- 性能分析：在 Xdebug 中启用 profile 模式，配合工具分析瓶颈（开发环境使用，避免生产开启）。
