Deployment → Mappings 中 Web path 必须按域名对应 DocumentRoot 的子路径严格填写，如 dev.example.com 的 DocumentRoot 为 /var/www/dev 则填 /，不可统一写 /；需为每个域名在 PHP → Servers 中单独配置服务器记录，且 Deployment 与 Servers 的 Web path、本地路径、Use path mappings 必须完全一致，否则导致 404 或断点失效。
Deployment → Mappings 里 Web path 必须按域名子路径填，不能只写 /
多域名环境（比如 dev.example.com、api.example.com）本质是多个虚拟主机共用同一台服务器，每个域名对应独立的 DocumentRoot。PhpStorm 不会自动识别你访问的是哪个域名，它只认你在 Settings → PHP → Servers 或 Deployment → Mappings 里填死的 Web path。
常见错误现象：
- 上传成功，但浏览器访问
http://dev.example.com/index.php报 404，而文件明明在服务器上 - Xdebug 断点不触发，控制台报
Cannot resolve path '/var/www/dev/index.php' on server
根本原因：你把所有域名都配成了同一个 Web path（比如统一填 /），但实际每个域名的 DocumentRoot 并不相同——dev.example.com 可能指向 /var/www/dev，api.example.com 指向 /var/www/api。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 进
Settings → PHP → Servers，为每个域名单独建一条服务器记录，名称如dev-server、api-server -
Host填域名本身（dev.example.com），不是 IP；Port填对应监听端口（通常 80/443） -
Web path必须严格等于该域名下DocumentRoot相对于服务器根目录的路径 —— 如果dev.example.com的DocumentRoot是/var/www/dev，这里就填/；如果api.example.com的DocumentRoot是/var/www/api/v1，这里就填/v1 - 务必勾选
Use path mappings，否则下面的映射列表灰掉不可用
Deployment 配置要和 Servers 配置一一对应，不能混用
很多人以为 Deployment 是“上传专用”，Servers 是“调试专用”，于是 Deployment 里只配一个 SFTP，Servers 里却配了三个域名，结果上传到 dev 目录，断点却在 api 上打，IDE 完全对不上路。
真实使用场景：
- 你想上传代码到
dev.example.com对应的目录 → 用 Deployment 中名为dev-sftp的配置，且它的Deployment path是/var/www/dev，Web path是/ - 你想用 Xdebug 调试
dev.example.com请求 → 在PHP → Servers里必须有一条叫dev-server的记录，Host是dev.example.com，Web path是/，且本地路径映射到同一项目目录
关键点：
-
Deployment path和PHP → Servers → Local path必须指向完全相同的本地目录（绝对路径） -
Deployment → Web path和PHP → Servers → Web path必须一致 —— 否则 PhpStorm 无法把浏览器 URL、服务器文件路径、本地文件三者串起来 - 不勾选
Use path mappings在任一位置，整个映射链就断了
SFTP 配置里的 Root path 和 Deployment path 别搞反
这是最常踩的坑：SFTP 连接设置里的 Root path 是你登录后看到的起始目录（比如 /var/www），而 Deployment → Mappings → Deployment path 是你本地项目要映射到这个起始目录下的哪个子路径（比如 /dev）。
错误示例：
- SFTP
Root path填了/var/www/dev，Deployment path 却又填/dev→ 实际上传到/var/www/dev/dev - SFTP
Root path是/，Deployment path 填/var/www/dev→ 上传路径变成//var/www/dev，部分 SFTP 服务会拒绝
正确做法：
- 先确认 SFTP 用户登录后的默认工作目录（
pwd），设为Root path -
Deployment path只填相对这个Root path的子路径，比如Root path是/var/www，项目要放/var/www/dev，那这里就填/dev - 如果 SFTP 用户权限受限，只能访问
/home/user/web，那你得把项目部署结构也调整到这个层级下，而不是硬改路径
多域名切换时别依赖“Default server”，手动选更可靠
PhpStorm 不支持基于当前打开文件或 URL 自动切 Deployment 或 Server 配置。所谓 Default server 只影响右键菜单里高亮哪一项，并不改变底层行为。
容易被忽略的地方：
- 你上传前没手动选目标服务器，右键 →
Upload to …里默认高亮的是上次用的那个，可能传错环境 - 调试时没在
Run → Debug配置里指定正确的Server，导致 Xdebug 找不到匹配的Web path - 宝塔/Nginx/Apache 里开了泛域名或通配符证书，但 PhpStorm 的
Host仍必须填具体域名（dev.example.com），不能填*.example.com
建议操作：
- 给每个 Deployment 和 Server 都起带环境标识的名字：
dev-sftp/dev-server、prod-sftp/prod-server - 上传前右键 →
Deployment → Upload to …，从列表里明确选一个 - 调试前检查运行配置里的
Server下拉框是否选对，不要只看绿色三角图标
