Xdebug连接失败的关键在于IDE本机需开放9003端口入站规则，而非出站或服务器端口；Windows/macOS/Linux均需配置入站放行，Docker环境还需确保xdebug.client_host指向宿主机。
不是开放出站端口，也不是服务器防火墙放行——Xdebug 是 PHP 进程主动往外连，目标是你本地 IDE 监听的 9003 入站端口。关键在 IDE 所在机器（你的开发机）上放行该端口的入站连接。
Windows：用高级安全防火墙添加入站规则
别只关防火墙，要精准放行：
- 打开「控制面板 → 系统和安全 → Windows Defender 防火墙 → 高级设置」
- 左侧选「入站规则」→ 右侧点「新建规则」
- 规则类型选「端口」→ 协议选「TCP」→ 特定本地端口填 9003
- 操作选「允许连接」→ 配置文件勾选「域、专用、公用」（或按需精简）
- 名称建议写「Xdebug IDE Port 9003」便于识别
macOS：系统防火墙 + pfctl 双保险
系统自带防火墙对端口控制较弱，推荐命令行补位：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 先确认防火墙开启：「系统设置 → 网络 → 防火墙」→ 点「选项」→ 勾选「启用防火墙」
- 手动放行 9003：
sudo pfctl -f /etc/pf.conf默认不生效，需临时加载规则 - 更稳妥做法：创建
/etc/pf.anchors/xdebug，内容为pass in proto tcp from any to any port 9003，再执行sudo pfctl -f /etc/pf.conf - 验证：
sudo lsof -i :9003应显示 IDE 进程监听中
Linux（ufw/firewalld）：一条命令到位
不同发行版命令略有差异，但逻辑一致：
- Ubuntu/Debian（ufw）：
sudo ufw allow 9003 - CentOS/RHEL（firewalld）：
sudo firewall-cmd --add-port=9003/tcp --permanent && sudo firewall-cmd --reload - 验证监听：
sudo ss -tlnp | grep :9003或sudo netstat -tuln | grep :9003 - 注意：若用 Docker Desktop，宿主机防火墙仍需放行，容器内无需额外开
别漏掉：IDE 监听状态与端口占用检查
防火墙开了≠一定能连，还得看端口是否干净、IDE 是否真在听：
- 查谁占了 9003：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows） - 常见抢占者：另一个 PhpStorm 实例、VS Code 的 PHP Debug 插件、Docker 映射（-p 9003:9003）、甚至某些杀软后台服务
- PhpStorm 必须勾选「Start listening for PHP Debug Connections」
- VS Code 要确保
.vscode/launch.json中"port": 9003且调试会话已启动（点击 ▶ 启动，不是直接 F5）
