路径映射必须手动配置，因为PHP解释器仅执行CLI脚本，而Xdebug调试依赖HTTP请求链路，IDE需明确将URL路径（如http://localhost/myapp/index.php）精准对应到本地磁盘绝对路径（如E:/www/myapp/index.php），该映射独立于解释器且决定文件定位与断点触发。
路径映射配错，Xdebug断点就永远不触发——不是代码问题，是 PhpStorm 根本找不到你本地的 index.php 对应服务器上哪个文件。
为什么“Local path → Web path”必须手动配，不能靠自动识别？
PhpStorm 的 PHP 解释器只管执行命令行脚本，而 Xdebug 调试走的是 HTTP 请求链路（比如浏览器访问 http://localhost/shop/public/index.php）。IDE 需要明确知道：这个 URL 背后的真实文件，在你电脑硬盘上的绝对路径是啥。这个“URL 路径 ↔ 本地磁盘路径”的对应关系，就是路径映射，它和解释器配置完全独立。
- 没配或配空 → 控制台报
Cannot resolve path 'C:\xxx\index.php' on server -
Web path写成/，但项目实际放在E:\www\myapp，且 Apache 的DocumentRoot是E:\www→ 正确值应为/myapp，否则所有$_SERVER['REQUEST_URI']和重写规则都错位 - Windows 下用反斜杠
\当分隔符写进Local path→ 可以，但建议统一用正斜杠/，避免某些版本解析异常
Settings → PHP → Servers 里三个关键字段怎么填？
进入 File → Settings → Languages & Frameworks → PHP → Servers，点击 + 添加一条记录：
-
Host：填localhost（不是127.0.0.1；Xdebug 3 默认只认localhost，除非你改过xdebug.client_host） -
Port：填你 Web 服务实际监听的端口，例如 Apache 是80、Nginx 是8080、php内置服务器是8000 -
Local path：填你项目根目录的**绝对路径**，如E:/www/myapp或/Users/name/project（结尾不加斜杠） -
Web path：必须以/开头，且严格等于该目录在浏览器 URL 中暴露的路径。例如项目部署在http://localhost/myapp/，这里就填/myapp；若入口是public/子目录，且你通过http://localhost/myapp/public/访问，则填/myapp/public
务必勾选 Use path mappings，否则下面的映射列表灰掉不可用。
立即学习“PHP免费学习笔记（深入）”；
ThinkPHP/Laravel 等框架的 public 目录怎么映射？
这类框架要求 Web 根目录指向 public/，但你的项目根目录其实是上层（含 app/、config/ 等）。此时路径映射不能只映射到项目根，而要对齐真实 DocumentRoot：
- 假设项目在
E:\www\tp8，Apache 的DocumentRoot设为E:\www\tp8\public→Local path填E:/www/tp8/public，Web path填/ - 更常见做法是保持
DocumentRoot指向E:\www，再用虚拟主机把tp8.test指向E:\www\tp8\public→ 此时Local path填E:/www/tp8/public，Web path填/，Host填tp8.test - 若不想动 Apache 配置，又想用
http://localhost/tp8/访问，就必须让DocumentRoot是E:\www，并在httpd-vhosts.conf中加别名或重写，同时Web path必须设为/tp8，否则$_SERVER['SCRIPT_NAME']会漏掉前缀
验证映射是否生效的最快方式
不用等调试启动，直接在 PhpStorm 里右键某个 PHP 文件 → Open in Browser。如果跳转 URL 是 http://localhost/xxx/yyy.php 且页面能正常加载，说明映射已生效；如果 404，大概率是 Web path 和服务器实际路由不一致。
最易被忽略的是：同一套 PHP 配置下，CLI（命令行）和 Web（Apache/Nginx）可能加载不同的 php.ini，导致你在终端跑 php -v 看到 xdebug，但浏览器访问 phpinfo() 却没有——路径映射只依赖 Web 版本的配置，务必确认 phpinfo() 页面中 “Loaded Configuration File” 指向的才是你要改的那个 php.ini。
