xdebug.client_host必须设为开发机局域网IP而非127.0.0.1,否则手机等设备调试失败;需配合PhpStorm开启外部连接、正确配置路径映射及使用XDEBUG_SESSION_START参数触发。

php.ini 中 xdebug.client_host 必须设为开发机真实局域网 IP
局域网调试失败,90% 是因为 xdebug.client_host 还写着 127.0.0.1。Xdebug 3.x 默认只往本机发连接,而手机、测试机、内网其他设备访问时,PHP 进程运行在你的开发机上,但调试请求要反向打回 PhpStorm —— 所以必须让 Xdebug 知道“该连谁”。
操作步骤:
- 用
ipconfig(Windows)或ifconfig(macOS/Linux)查出开发机在局域网中的 IPv4 地址(如192.168.1.105),不是127.0.0.1,也不是localhost - 在 php.ini 中把
xdebug.client_host=127.0.0.1改成xdebug.client_host=192.168.1.105 - 务必重启 PHP-FPM 或 Apache/Nginx,否则配置不生效
- 若用的是 Docker 容器跑 PHP,
xdebug.client_host应填宿主机的局域网 IP,且容器需加--network=host或映射端口
PhpStorm 的 Debug Port 和服务器监听必须对外放开
默认情况下,PhpStorm 的 Xdebug 监听只绑定 127.0.0.1:9003,外部设备无法连接。即使 php.ini 配对了,也会卡在“连接被拒绝”。
解决办法:
- 进入
File → Settings → Languages & Frameworks → PHP → Debug - 将
Debug Port设为9003(或其他未被占用端口,如9004) - 关键一步:勾选
Can accept external connections(PhpStorm 2021.3+ 默认隐藏,需点击右下角齿轮图标 → 勾选) - 确保开发机防火墙放行该端口(Windows Defender / macOS 防火墙 / iptables)
- 不要启用
Force break at first line...,它会导致非项目路径脚本阻塞,干扰联调
路径映射(Path Mapping)必须按实际部署结构配准
手机或测试机通过 http://192.168.1.105/test.php 访问,但 PHP 脚本实际在你本地 /Users/me/project/web/test.php。PhpStorm 不知道远程 URL 对应哪段本地路径,断点就永远不命中。
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
配置要点:
- 进
Run → Edit Configurations → + → PHP Web Page -
Server configuration选你已定义的局域网服务器(如192.168.1.105) - 在
Path mappings表格中添加一行:
Remote path:/var/www/html/(或你服务器上 PHP 文件的实际 Web 根路径)
Local path:/Users/me/project/web/(你本地项目对应目录) - 路径末尾都**不要加斜杠**,
/var/www/html和/Users/me/project/web才是正确写法 - 如果用 Nginx/Apache 虚拟主机,Remote path 应填
server_name对应的 root,不是系统绝对路径
触发调试不能只靠 Xdebug Helper 插件
Chrome 插件只能改当前浏览器请求头,对手机 WebView、Postman、小程序、curl 测试完全无效。局域网联调必须用通用触发方式。
推荐组合:
- 在 php.ini 中设
xdebug.start_with_request=trigger(不推荐yes,太暴力) - 所有调试请求带上
XDEBUG_SESSION_START=PHPSTORM参数:
→ 浏览器地址栏追加?XDEBUG_SESSION_START=PHPSTORM
→ Postman 在 URL 后加相同参数,或 Header 加XDEBUG_SESSION_START: PHPSTORM
→ 手机访问时,直接拼完整 URL,例如http://192.168.1.105/api/user.php?XDEBUG_SESSION_START=PHPSTORM - 确保 php.ini 中
xdebug.idekey=PHPSTORM与 PhpStorm 设置一致(Settings → PHP → Debug → DBGp Proxy IDE key) - 别依赖 Cookie:某些内网环境禁用第三方 Cookie,
XDEBUG_SESSIONCookie 可能失效
局域网调试最易忽略的是路径映射的粒度和 Can accept external connections 开关 —— 它们不报错,但会让整个流程静默失败。调试前用 telnet 192.168.1.105 9003 从手机或另一台电脑测端口通不通,比反复刷新页面更高效。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!










