webstorm sftp 同步失败主因是 root path 填错、automatic upload 未设为 on explicit save action、rsync 与 sftp 混用；需精准配置路径映射、认证方式及上传触发时机。
WebStorm 用 SFTP 连接远程服务器并同步代码，关键不是“能不能连”，而是「Root path」填错、Automatic Upload 没开、或 rsync 和 SFTP 混用导致行为不一致——这三处出错，90% 的同步失败都卡在这儿。
填对 Root path 才能映射到真实项目目录
这个字段不是随便写个 /home/user 就行。它决定你本地文件上传后落在服务器的哪个位置，也影响「Browse Remote Host」看到的根目录范围。
- 如果你的目标是把
dist/推到 Nginx 的/var/www/html/，Root path必须填/var/www/html，不能填/var/www或留空 - 填错会导致：上传后文件出现在错误路径、
Web server root URL配置失效、甚至「Download from here」拉不到任何内容 - 推荐做法：先 SSH 登录服务器，
pwd进入目标目录，复制完整路径粘贴过去；别依赖自动检测，某些容器或受限 shell 下它会返回/
Automatic Upload 必须设为 On explicit save action
很多人以为勾上「Upload files automatically to the default server」就完事了，但默认是 On application startup 或 On frame deactivation，根本不会响应 Ctrl+S。
- 正确路径：
Tools → Deployment → Options → Upload changed files→ 改成On explicit save action - 这个选项只对「已映射目录」生效。如果某文件不在
Mappings表中定义的本地路径下，保存也不会触发上传 - 注意：启用后，每次保存都会发一次 SFTP 请求。大项目里频繁改
node_modules或日志文件？得靠Excluded paths过滤掉，否则卡顿明显
SFTP 连接失败常见原因和验证点
点 Test Connection 显示失败，别急着重配，先确认这三件事：
-
Authentication类型选错：SFTP 走 SSH 协议，如果服务器禁用了密码登录（只允许密钥），就必须选Key pair并指定.pem或id_rsa文件；选Password却填密钥路径，必然报Auth fail - 端口不是 22：有些云服务器（如腾讯云）安全组默认封 22，或你改过 SSH 端口，
Port字段就得手动填对应数字，不能依赖默认值 - 用户权限不足：连接成功但进不去目录？检查该用户对
Root path目录是否有读写权限，ls -ld /var/www/html看属主，必要时sudo chown -R $USER:$USER /var/www/html
最易被忽略的是路径映射的「相对性」：你在 Mappings 里设本地 ./dist → 远程 /，实际上传路径是 Root path + /，也就是 /var/www/html/ + / = /var/www/html/；但如果远程路径填成 html，就会变成 /var/www/html/html——这种嵌套一层的错误，日志里不报错，但浏览器死活刷不出页面。
