xdebug.remote_host应填本地开发机的可路由IP（如192.168.1.105），而非127.0.0.1；若服务器与本地网络隔离，可启用xdebug.remote_connect_back=1自动获取客户端IP，但生产环境禁用。
php.ini里xdebug.remote_host该填什么
填你本地开发机的**可路由 IP**，不是127.0.0.1，也不是服务器自己的localhost。常见错误是直接写127.0.0.1，结果 Xdebug 尝试连本地回环，但 PhpStorm 根本没在服务器上运行，连接必然失败。
判断依据很简单：从 Linux 服务器上执行 ping -c 1 [你的本机IP] 必须通。如果是公司内网，填内网 IP（如 192.168.1.105）；如果本地是 macOS/Windows，且服务器能直连你本机（无 NAT 隔离），就填那个 IP；如果走的是家庭宽带+路由器，多数情况得启用 xdebug.remote_connect_back=1（见下一条），并确保防火墙放行xdebug.remote_port端口。
-
xdebug.remote_connect_back=1是 fallback 机制：Xdebug 会从 HTTP 请求头（X-Forwarded-For或REMOTE_ADDR）自动提取发起请求的客户端 IP —— 也就是你浏览器所在机器的 IP。但它有安全风险，生产环境禁用 - 若服务器在腾讯云/阿里云等公有云，且你本地是动态公网 IP，
remote_connect_back往往比硬写 IP 更可靠 - 填错会导致 PhpStorm 完全收不到调试连接，控制台日志里看不到任何 Xdebug 连入记录
PHPStorm 的 Server 配置必须设路径映射
远程调试时，PHP 进程在 Linux 上执行，代码路径是/var/www/html/app/这类；而你的 PhpStorm 项目打开的是本地目录/Users/me/project/。Xdebug 发送的文件路径是服务器上的绝对路径，PhpStorm 如果不认识这个路径，就无法把断点和源码对上 —— 表现为：请求来了、连接建立了、但断点灰色不生效，或者跳转到“unknown file”。
必须在 Settings → Languages & Frameworks → PHP → Servers 中添加对应条目，并严格配置 Host、Port 和最关键的 Path mappings：
立即学习“PHP免费学习笔记（深入）”；
- 左边填服务器上的绝对路径（如
/var/www/html） - 右边填你本地项目根目录的绝对路径（如
/Users/me/project） - 如果用 SFTP 自动部署，这里映射必须和 Deployment 配置里的
Web server root URL和Local path保持一致 - 路径末尾不加斜杠，大小写需完全匹配（Linux 区分大小写）
xdebug.remote_port 和 PhpStorm 监听端口必须一致
默认是 9000，但 PHP 8.0+ 官方推荐改用 9003，因为 9000 已被 PHP-FPM 占用。如果你没改，又装了 PHP-FPM，Xdebug 绑定端口会失败，php -m | grep xdebug 看不到扩展，或 phpinfo() 里 Xdebug 模块显示“disabled”。
检查方式：在服务器上运行 ss -tlnp | grep :900，确认没有其他进程占着你配的端口。
- PhpStorm 默认监听
9003（Settings → PHP → Debug → Xdebug → Debug port） - 务必让
php.ini里的xdebug.remote_port=9003和 PhpStorm 设置完全一致 - 如果用了 Docker 或云服务器安全组，还要确保该端口对外（或对你的本机 IP）开放
- Chrome 插件 Xdebug Helper 的“Debug”开关开启后，请求头会带
XDEBUG_SESSION_START=PHPSTORM，这是触发 Xdebug 连接的关键信号
为什么 xdebug.so 路径总配错
zend_extension 的值不是固定写 xdebug.so，而是必须指向编译安装后生成的完整路径，例如：/usr/lib/php/20220829/xdebug.so。PECL 安装完会打印类似 Installing '/usr/lib/php/20220829/xdebug.so' 的提示，这就是你要抄的路径。
常见坑：
- 用
pecl install xdebug后没记下输出路径，就去瞎猜，比如填/usr/lib/php/modules/xdebug.so—— 大概率不存在 - CLI 和 Web（Apache/Nginx）用的是不同 php.ini，要分别确认：用
php --ini查 CLI 配置，用phpinfo()页面查 Web 配置 - PHP 版本升级后，
20220829这类 API 版本号会变，旧路径立刻失效 - 用
php -v和php -m | grep xdebug双重验证扩展是否真正加载成功
最稳妥的做法：每次安装完，立刻执行 find /usr -name "xdebug.so" 2>/dev/null 找到确切位置，再填进 php.ini。
