deployment path 填服务器绝对路径（如 /myapp），web path 填浏览器 url 前缀（如 /myapp）；二者必须与 sftp 根路径、web 服务器 documentroot 子路径严格一致，否则导致 404、断点失效、request_uri 错乱。

Deployment path 和 Web path 到底填什么？

填错这两个字段，上传成功但页面 404、断点不触发、$_SERVER['REQUEST_URI'] 错乱——问题不是没传上去，而是 PhpStorm 根本不知道“文件该放在哪”和“浏览器该从哪访问”。

Deployment path 是服务器上的**绝对路径**，必须和你 SFTP 登录后看到的完整路径一致。比如 SFTP Root path 填的是 /var/www/html/myapp，那这里就填 /myapp（映射子目录）或 /（映射整个 root）。填错 → 文件传到 /var/www/html/otherplace，ls -l /var/www/html/myapp 看不到你的代码。

Web path on server 是浏览器 URL 的**前缀**，必须以 / 开头，且严格匹配 Web 服务器的 DocumentRoot 子路径。Apache 的 DocumentRoot 是 /var/www/html，项目实际在 /var/www/html/myapp，这里就必须填 /myapp。填成 /、/myapp/（末尾斜杠）、myapp（缺开头斜杠）都会导致重写规则失效、路由解析错误。

• Web path 必须和 $_SERVER['DOCUMENT_ROOT'] 下的相对位置完全一致
• 如果用了宝塔面板，直接看「网站」列表里对应站点的「根目录」和「运行目录」字段
• 改完 Mapping 后，务必右键项目 → Deployment → Upload to … 手动试一次，别只信自动上传

多个环境（测试/预发/生产）怎么切不乱？

PhpStorm 不支持 ${ENV} 这类变量插值，所谓“一套配置打天下”是假命题。真正在用的方案是：每个环境建独立服务器条目，靠手动切换 + 默认标记控制流向。

操作上，在 File → Settings → Build, Execution, Deployment → Deployment 里点 + 新建多个条目，名字带环境标识，例如：staging-sftp、prod-sftp。每个条目的 Deployment path 和 Web path 单独配准，比如：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• staging-sftp：Deployment path = /var/www/staging/myapp，Web path = /myapp
• prod-sftp：Deployment path = /var/www/live/myapp，Web path = /myapp

上传时右键文件 → Deployment → Upload to …，菜单里会列出所有已配置的服务器名，选哪个就传到哪。想设默认目标？在 Deployment 主页选中它，勾上 Default server ——但注意：这不会同步切换 PHP 解释器、Xdebug 配置或数据库连接，那些得另外在 PHP → Servers 或 PHP → Debug 里单独配。

为什么改了 Mappings 就是不生效？

常见三类静默失败，没有报错提示，但上传行为完全退化为“瞎猜”：

• 没勾选 Use path mappings：这个开关在 Deployment 主页最上面，不勾它，Mappings tab 里的所有设置全被忽略
• Local path 没对齐：Mappings 里的 Local path 必须指向你当前打开的项目根目录。如果项目是 /Users/me/project，但这里填了 /Users/me/project/src，上传时只会同步 src 下的文件
• 路径末尾多了斜杠：比如 Deployment path 填了 /var/www/html/myapp/（结尾多斜杠），SFTP 实际会尝试创建 myapp//index.php，部分服务器拒绝这种路径

验证是否生效最直接的办法：在项目里新建一个空文件 test-upload.php，右键 → Upload to …，然后立刻登录服务器执行 ls -l /your/deployment/path/test-upload.php。看不到文件？问题一定出在 Mapping 配置或 Use path mappings 开关上。

自动上传（On explicit save）踩坑点

启用 Automatic upload 很方便，但容易掩盖路径配置问题，尤其当你同时开着多个服务器配置时。

• 自动上传只作用于当前激活的 Default server，不是“所有服务器都同步”
• 如果本地文件保存后没反应，先检查右下角状态栏有没有 “Uploading…” 提示；没有的话，大概率是 Use path mappings 没开，或 Local path 和当前项目不匹配
• 慎用 On file change：编辑器临时文件（如 .php~）也可能被上传，污染远程服务器
• 上传大文件（如 vendor）时，建议关掉自动上传，改用手动 Upload to … 或用 Sync with Deployed to …，避免卡死 IDE

真正关键的不是“怎么让它动起来”，而是“怎么确认它动到了对的地方”。每次换环境、改路径，都要拿一个最小可验证文件（比如 echo 'ok';）跑一遍上传 + 浏览器访问 + 服务器 ls 三连，少跳这一步，后面调试全是冤枉路。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！