在 Debian 上使用 PhpStorm 进行远程调试的标准做法
一 环境准备与网络连通
- 在 Debian 服务器安装 Xdebug（以 PHP 8.1 为例，其他版本将路径中的 8.1 替换为你的实际版本）：
- 安装扩展：sudo apt-get update && sudo apt-get install php8.1-xdebug
- 启用模块：sudo phpenmod xdebug
- 网络要点：
- 让服务器能访问你的 IDE 所在机器的 IP 与 端口 9003（Xdebug 3 默认端口）。
- 若服务器在 NAT/云厂商 VPC 后，需在路由器或安全组做 端口映射：9003 → 你的本机 IP:9003；不建议直接把 9003 暴露在公网。
- 临时放通防火墙（示例）：sudo ufw allow 9003/tcp；生产环境请改为精确来源 IP 的白名单策略。
二 Debian 服务器 Xdebug 3 配置
- 编辑 Xdebug 配置（推荐统一放在：/etc/php/8.1/mods-available/xdebug.ini）：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=你的IDE所在机器的IP
- xdebug.client_port=9003
- xdebug.start_with_request=yes（浏览器访问即连；CLI 调试可用 XDEBUG_SESSION=1 触发）
- xdebug.idekey=PHPSTORM（可选，配合浏览器书签/插件触发）
- 使配置生效：
- Apache：sudo systemctl restart apache2
- PHP-FPM + Nginx：sudo systemctl restart php8.1-fpm && sudo systemctl restart nginx
- 说明：
- 老版本 Xdebug 2 使用 remote_* 参数（如 remote_enable、remote_host、remote_port=9000），本教程面向 Xdebug 3，端口为 9003。
三 PhpStorm 端配置
- 解释器与调试端口：
- File → Settings → Languages & Frameworks → PHP → CLI Interpreter：添加远程或本机解释器（能执行 php -v 即可）。
- File → Settings → Languages & Frameworks → PHP → Debug：将 Debug port 设为 9003（与服务器一致）。
- 服务器与路径映射：
- File → Settings → Languages & Frameworks → PHP → Servers：新建服务器
- Name：自定义；Host：服务器域名或 IP；Port：80/443
- Debugger：选择 Xdebug
- 勾选 “Use path mappings”，将本地项目根目录映射到服务器上的绝对路径（例如：/var/www/html）
- 可使用 “Validate remote environment” 校验远程 Xdebug 连通性
- DBGp Proxy（可选，浏览器书签/插件方式常用）：
- IDE key：PHPSTORM；Host：localhost；Port：9003
- 运行配置：
- Run → Edit Configurations → 新建 PHP Web Application
- Server：选择上一步的服务器
- Start URL：你的入口路径（如 /）
- 勾选 “Break at first line in PHP scripts”（可选，便于确认连接是否成功）
四 启动调试与触发方式
- 方式 A（推荐，稳定可控）：
- 在 PhpStorm 点击 “电话听筒”图标开启 监听（Start Listening for PHP Debug Connections）
- 浏览器访问你的页面，并在 URL 后追加：?XDEBUG_SESSION_START=PHPSTORM
- 示例：http://your-server/your-app/index.php?XDEBUG_SESSION_START=PHPSTORM
- 方式 B（浏览器书签/插件）：
- 安装 Chrome 的 Xdebug Helper，或在 jetbrains.com/phpstorm/marklets/ 生成书签，选择 IDE key 为 PHPSTORM，访问时自动携带调试 Cookie
- 方式 C（CLI/CLI 脚本调试）：
- 在服务器上执行：XDEBUG_SESSION=1 php your-script.php
- 触发后，PhpStorm 会弹出调试会话，可逐步执行、查看变量与堆栈。
五 常见问题排查
- 端口不通：
- 服务器执行：nc -vz 你的IDE_IP 9003 或 telnet 你的IDE_IP 9003
- 本机执行：netstat -ano | grep 9003 确认监听
- 云服务器/公司网络：检查 安全组/防火墙/NAT 端口映射 是否放行
- Xdebug 未加载或版本不匹配：
- php -v 应能看到 with Xdebug
- php -m | grep xdebug 应能看到 xdebug
- 配置路径是否正确（/etc/php/8.1/mods-available/xdebug.ini），修改后是否执行了 phpenmod xdebug 并重启了 Apache/PHP-FPM
- 断点不生效/路径不对：
- 确认 Servers 中已启用 Use path mappings，本地与远程绝对路径一一对应
- 使用 “Validate remote environment” 检查连通与配置
- 使用了代理/CDN：
- 调试请求需直达源站，或在代理上放行 9003 并正确回源到你的 IDE 机器
- 日志定位（可选）：
- 在 xdebug.ini 增加：xdebug.log=/tmp/xdebug.log，观察握手与连接细节
