xdebug 连不上云端服务器主要是 xdebug.client_host ip 错误或 xdebug.mode 未设为 debug；需确认 mode=debug、client_host 可达、路径映射严格一致（大小写敏感）、防火墙放行 9003 端口，并正确配置 phpstorm 服务器与路径映射。
Xdebug 连不上云端服务器？90% 是 xdebug.client_host 填错了 IP，或 xdebug.mode 没设成 debug。
确认 xdebug.mode=debug 且 client_host 可达
PHP 8.0+ 不再用 xdebug.remote_enable，必须显式设 xdebug.mode=debug（可加 ,develop）。phpinfo() 里搜不到 mode 值，说明 Xdebug 根本没加载成功。
- 在云服务器上执行
php -m | grep xdebug，无输出就先检查zend_extension路径是否真实存在 -
xdebug.client_host必须填你本地机器的**可路由 IP**：公司内网填192.168.x.x，家庭宽带+路由器通常得启用xdebug.discover_client_host=true（旧版叫remote_connect_back=1），但生产环境禁用 - 从云服务器执行
ping -c 1 [你的本机IP]必须通；不通就别硬写 IP，改用discover_client_host+ 开放防火墙端口 - 腾讯云/阿里云安全组、云防火墙必须放行
xdebug.client_port（默认9003）入方向
PhpStorm 的 Server 配置必须匹配路径映射
断点灰色、跳转到 “unknown file” —— 典型症状是路径映射没对上。PHP 进程在云服务器跑，代码路径是 /var/www/html/app/；而你本地打开的是 /Users/me/project/，Xdebug 发送的是前者，PhpStorm 找不到后者就失效。
- 进
Settings → Languages & Frameworks → PHP → Servers，添加条目，Host填云服务器域名/IP，Port填 Web 端口（如80或443） -
Path mappings左边填服务器绝对路径（如/var/www/html），右边填本地项目根目录绝对路径（如/Users/me/project） - 两边路径末尾都**不加斜杠**，大小写严格一致（Linux 区分大小写）
- 如果用了 SFTP 自动部署，这里的映射必须和
Deployment → Mappings中的Web server root URL和Local path完全一致
监听端口、触发方式、CLI 调试要分开处理
按了 Start Listening for PHP Debug Connections 按钮却没反应？不是按钮坏了，是端口被占、防火墙拦了，或根本没触发。
-
xdebug.client_port（默认9003）必须和 PhpStorm 的Settings → PHP → Debug → Xdebug → Debug port完全一致；PHP-FPM 占了9000，别再用它 -
xdebug.start_with_request=trigger时，必须靠浏览器插件（如 Xdebug Helper）点 “Debug”，或手动带 Cookie：XDEBUG_SESSION_START=PHPSTORM - 调试 CLI 脚本（如
php artisan command）？start_with_request=trigger失效，得设yes，或直接命令行加参数：php -dxdebug.mode=debug -dxdebug.client_host=10.0.2.2 script.php - Docker 部署 PHP？检查
ports: ["9003:9003"]是否映射，host.docker.internal在 Mac/Win 可用，Linux 宿主机需填真实 IP
Remote Host 不等于远程执行，File Watcher 不能真正在云端监听
别被界面里的 “Remote Host” 文字骗了 —— PhpStorm 的 File Watcher 是本地 JVM 插件，只监听本地文件系统事件（inotify/kqueue），它不会、也不能在云服务器上起守护进程监听文件变更。
- 远程 Git Pull、其他编辑器改了服务器文件，本地 Watcher 完全收不到通知
- 正确做法：用本地 Watcher 触发脚本，脚本里用
rsync+ssh执行远程构建或重启，例如：rsync -avz ./dist/ user@prod.example.com:/var/www/app/ && ssh user@prod.example.com 'cd /var/www/app && npm ci' - 脚本路径必须用绝对路径（别用
~），Working directory设为$FileDir$或显式写死，Enabled复选框务必勾上 - 触发时机选
On save，别用On type，否则保存中途就高频误触发
最常被忽略的其实是路径映射大小写和 xdebug.mode 的值 —— 云环境里 Linux 默认区分大小写，而 macOS 本地开发机不区分，一模一样的路径名可能就映射失败；mode 若是 off 或 develop 单独存在，Xdebug 根本不尝试连接，连错误日志都不会有。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
