webstorm deployment本质是sftp客户端，仅单向搬运文件，不执行ssh命令；connection中host、user name、root path填错将导致连接失败或404；mappings中deployment path必须以/开头且相对于root path；推荐启用on explicit save action自动上传，首次部署需手动上传完整目录并验证路径与服务状态。
WebStorm 内置的 Deployment 功能本质是 SFTP 客户端，不是 SSH 终端；它不执行 ssh 命令或运行远程 shell，只做文件搬运。想用“内置 SSH 工具上传包”，实际走的是 SFTP 协议 —— 这没问题，但必须按 SFTP 路径规则配置，否则传上去也访问不到。
Connection 里 Host/User name/Root path 填错就白忙
这三个字段直接决定能否连上、文件传到哪、网页能不能打开：
-
Host必须填云服务器公网 IP 或可解析域名（比如139.196.123.45或prod.myapp.com），不能填localhost、127.0.0.1或内网地址 -
User name是 SSH 登录用户名，常见为root、ubuntu、deploy—— 不是你在阿里云/腾讯云控制台注册的邮箱账号 -
Root path是服务器上项目实际运行的绝对路径，比如 Nginx 静态服务填/var/www/html，Tomcat 填/opt/tomcat/webapps/myapp；填错会导致文件上传成功但浏览器返回 404 - 端口默认是
22，改过 SSH 端口的必须手动输；密钥认证时，Key pair必须指向私钥文件（如~/.ssh/id_rsa），不是.pub文件
配置前，先在终端执行 ssh user@host -p port 验证连通性 —— 这比 WebStorm 的 Test Connection 更可靠。
Mappings 中 Deployment path 必须以 / 开头且相对 Root path
这不是“映射”，而是“本地目录 → 服务器子路径”的单向搬运规则：
-
Local path通常选项目根目录（./），如果只部署dist，就明确设为./dist -
Deployment path是相对于Root path的路径，**必须以/开头**：比如Root path是/var/www，那Deployment path应填/my-project，而不是my-project - 如果项目要跑在子路径下（如
https://example.com/admin），Deployment path必须和Web server URL末尾一致，即填/admin - 多模块部署（如前端 + API）可点
Add another mapping单独配：src/api→/api
自动上传选 “On explicit save action” 更稳妥
选 Always 会把未保存的草稿、临时编辑内容也推上去，导致服务器跑着半截代码：
- 推荐勾选
Upload changed files automatically to the default server，再选On explicit save action（即 Ctrl+S 或 Cmd+S 时触发） - 首次部署必须手动右键项目根目录 →
Deploy to …，否则服务器上没基础结构 -
Excluded paths标签页加/node_modules、/.git、/dist（如果本地不直接传 dist）—— 注意都用正斜杠，Windows 也一样 - 自动上传是单向推送，不拉取远程变更，也不校验一致性；多人共用测试机时，容易覆盖别人刚改的配置
真正容易被忽略的是：Root path 和 Deployment path 共同决定了文件最终落盘位置，而 WebStorm 从不报错提示你填错了 —— 它只会“静默成功”，然后你刷新页面看到 404。验证方式只有两个：登录服务器用 ls -l 看真实路径，以及用 curl -I http://your-ip/ 检查响应头。
