Deployment path和Web path必须分开配置：前者为服务器绝对路径，决定文件实际存储位置；后者为URL前缀，须与DocumentRoot子路径严格一致且以/开头，二者任一错误均导致上传成功但无法访问或断点失效。
Deployment path 和 Web path 必须分开理解、分别配对，填错一个就上传成功但打不开，或者断点不触发。
Deployment path 填服务器上的绝对路径
它决定文件实际存到服务器哪个位置，必须是绝对路径，且与 SFTP 配置里的 Root path 逻辑一致：
- 如果 SFTP 的
Root path是/var/www/html/myapp，那么 Deployment path 通常填/myapp（映射子目录）或/（映射整个根） - 填成
myapp（缺开头斜杠）→ 文件传到用户家目录下，ls -l /var/www/html看不到 - 填成
/var/www/html/myapp（重复冗余）→ 上传可能失败，或被 SFTP 自动截断，行为不可控 - 多个映射时，每个
Local path对应的 Deployment path 必须能被Root path容纳，不能越界
Web path 必须和 DocumentRoot 子路径严格一致
它不是 URL，而是浏览器访问时 $_SERVER['REQUEST_URI'] 解析所依赖的路径前缀，必须以 / 开头，且与 Web 服务器配置完全匹配：
- Apache 的
DocumentRoot是/var/www/html，项目放在/var/www/html/myapp→ Web path 必须填/myapp - 填成
/→ 所有请求都落到/var/www/html，index.php找不到路由 - 填成
/myapp/（结尾多斜杠）→$_SERVER['REQUEST_URI']可能多出一级空段，重写规则（如 ThinkPHP 的.htaccess）失效 - 用虚拟主机时（如
loc.rule.com），Web path 仍要按 DocumentRoot 下的相对路径填，不是域名
Mapping 不生效？先检查 Use path mappings 是否勾选
这个开关在 Deployment → Mappings 页面右上角，很多人配完就走，结果 PhpStorm 根本不读你填的映射：
立即学习“PHP免费学习笔记（深入）”；
- 没勾选 → 上传退化为“按项目文件夹名硬猜远程路径”，比如本地叫
shop_order_rule_design，就往服务器/shop_order_rule_design传，不管你在 Mapping 里写了啥 - 勾选后，
Local path必须和当前项目根路径一致，否则映射关系无法命中（可点击右侧文件夹图标重新指定） - 修改后需手动触发一次上传（右键文件 →
Deployment → Upload to …）验证是否真生效
PHP 调试路径映射（Servers 设置）和 Deployment 映射是两套系统
很多人以为配了 Deployment 就不用再配 Servers，其实 Xdebug 断点、Open in Browser、URL 构造全靠后者驱动：
- 进
Settings → Languages & Frameworks → PHP → Servers，新增服务器，填Host（如localhost）、Port（如80） - 必须勾选
Use path mappings，然后添加映射：Local path指向你的项目根，Web path填和 Deployment 里一模一样的值（如/myapp） - 如果本地路径含 Windows 盘符（如
E:\www\myapp），Web path 却填/，Xdebug 会报Cannot resolve path 'E:\www\myapp\index.php' on server - WSL2 或 Docker 场景下，Local path 要用 WSL 内部路径（如
/home/user/myapp），不能用/mnt/c/...，否则断点永远不触发
最常被忽略的是：Deployment path 和 Servers 里的 Web path 看似都叫“path”，但前者管文件落点，后者管 URL 解析和调试定位——它们可以相同，但作用域完全不同，改一个不碰另一个，问题照旧。
