webstorm deployment 功能支持代码自动上传，但仅为单向推送，不拉取远程变更、不校验一致性；connection 中 host、user name、root path 填错将导致连接失败或 404；mappings 中 deployment path 必须以 / 开头且相对于 root path；推荐启用 on explicit save action 自动上传模式，首次部署需手动上传完整目录并验证路径与服务状态。
WebStorm 的 Deployment 功能能实现代码同步，但「自动上传 ≠ 安全同步」——它只单向推本地变更，不拉取远程改动，也不校验文件一致性。开错选项或填错路径，轻则 404，重则覆盖系统文件。
Connection 里 Host/User name/Root path 填错就白配
这三个字段是连接成败和部署可见性的核心，WebStorm 不会明确报错，但会导致 Test Connection 失败，或上传后访问 404：
-
Host必须是服务器可直连的 IP 或域名（比如192.168.2.100或prod.example.com），不能写localhost或内网地址（如10.0.0.x） -
User name是 SSH 登录用户名（如root、ubuntu、deploy），不是云控制台账号名 -
Root path是服务器上项目实际运行的绝对路径（如/var/www/html、/opt/tomcat/webapps/myapp），填错会导致文件传到错误位置，Nginx/Apache 找不到资源 - 端口默认是
22，改过 SSH 端口的必须手动填；密钥认证时，Key pair必须指向私钥文件（如~/.ssh/id_rsa），不是.pub文件 - 配置前建议先在终端执行
ssh user@host -p port验证连通性，这是最可靠的前置检查
Mappings 中 Local path 和 Deployment path 的路径规则
这两个字段定义「本地哪→服务器哪」，不是映射关系，而是源-目标搬运路径，斜杠方向和相对性极易出错：
-
Local path通常选项目根目录（如/Users/me/project），也可精确到dist目录（如/Users/me/project/dist） -
Deployment path是相对于Root path的路径，**必须以/开头**（如Root path是/var/www，那Deployment path应填/my-app，而不是my-app） - 如果项目需部署为子路径（如
https://example.com/admin），Deployment path必须与Web server URL末尾一致（即填/admin） - 多模块部署（如前端 + API）可用
Add another mapping单独配：本地src/api→ 远程/api - 不想传
node_modules或.git？切到Excluded paths标签，加/node_modules、/.git（注意是正斜杠，Windows 也一样）
Upload changed files 自动上传模式怎么选
自动上传有三个选项，行为差异直接影响开发稳定性：
-
Never：纯手动，右键选Upload to...才触发，适合只在发布前批量推送 -
Always：只要文件内容变更（哪怕还没保存），就立刻上传——会把编辑中未保存的草稿、临时文件（如正在重命名的index.js~）也推上去，风险高 -
On explicit save action（推荐）：仅当你按下Ctrl+S（macOS 是Cmd+S）时上传，可控性强，避免半截代码上线 - ⚠️ 注意：无论选哪个，WebStorm 都不会自动下载远程变更。多人共用测试机时，若别人改了配置又没提交 Git，你开自动上传可能直接覆盖掉
首次部署和日常维护的几个关键动作
配置完不等于能用，这几个操作常被跳过，却决定是否真正跑起来：
- 首次使用前，务必右键项目根目录 →
Deployment→Upload to...手动上传一次完整目录，确保服务器有基础结构 - 上传后访问 404？先确认 Nginx/Apache 是否已重启，再检查
Root path和Deployment path拼出来的最终路径是否真有文件（可用Tools→Deployment→Browse Remote Host查看） - 想验证文件一致性？在
Remote Host工具窗口中右键文件 →Compare with Local，比对内容差异 - 误传错文件？右键远程文件 →
Download from...拉回来，或直接删掉重传 - 长期运行的 Node.js 服务关终端就停？别依赖 WebStorm 启动，用
screen -S myapp或pm2 start守护进程
路径开头的斜杠、Root path 与真实运行路径的一致性、以及「上传不等于同步」这个前提，是绝大多数同步失败的根本原因。配置时盯着这三点，比反复点 Test Connection 更有效。
