SFTP上传失败的核心原因是SFTP子系统未启用、路径映射不准、私钥格式错误或时间戳未校准；需检查sshd_config中Subsystem配置、用户shell类型、Root path为绝对路径、Deployment path与Web path严格匹配Nginx root，并关闭timestamp比较或改用ssh-agent托管密钥。
能配通，但默认设置大概率上传失败或静默跳过——核心卡点不在密码或IP，而在SFTP子系统启用状态、路径映射精度、私钥格式和时间戳校准这四块。
Connection test 卡在 “Testing connection…” 怎么破
这不是网络不通，而是SSH服务没开SFTP通道，或用户被锁死在非交互shell里。
- 先终端执行
ssh -v user@host，看最后几行有没有debug1: Sending subsystem: sftp；没有就说明/etc/ssh/sshd_config缺少Subsystem sftp /usr/lib/openssh/sftp-server或被注释 - 检查该用户的shell：运行
getent passwd user | cut -d: -f7，结果不能是/bin/false或/usr/sbin/nologin，得是/bin/bash或/bin/sh - PhpStorm里填的
Root path必须是绝对路径（如/var/www/html），不能写~/public_html或留空
映射路径对了，文件却传到错目录或根本没覆盖
根本原因：Deployment path 和 Root path 混用，或Web path 和实际Nginx root不一致，导致“传对了，但访问不到”。
-
Root path是SFTP登录后看到的根（比如chroot到/var/www，那这里就得填/）；Deployment path on server是相对于这个根的子路径（如项目叫myapp，就填/myapp） -
Web path on server要跟Nginx/Apache配置的root指令完全对齐；比如Nginx里写的是root /var/www/html;，而你传到了/var/www/html/myapp，那这里就得填/myapp，否则预览链接会404 - 改完立刻验证：右键文件 →
Deployment → Browse Remote Host，看文件是否出现在预期位置，且时间戳已更新
上传显示成功，远程文件内容却没变
常见于跨时区部署、Docker容器挂载卷、NFS共享盘——文件系统不更新mtime，PhpStorm误判“远程更新”，跳过上传。
立即学习“PHP免费学习笔记（深入）”；
- 打开
Settings → Build, Execution, Deployment → Deployment → Options，取消勾选Compare timestamps - 注意副作用：关掉后每次上传会做内容比对（MD5），
vendor/大项目会卡顿；建议配合Excluded paths过滤掉node_modules,vendor,.git - 如果服务器是Docker，确认挂载方式：用
bind mount而非volume，后者在某些内核下mtime不可靠
私钥登录总报 Authentication failed
90%是PuTTY格式（.ppk）直接塞进PhpStorm，它只认OpenSSH原生格式。
- 用PuTTYgen打开你的.ppk →
Conversions → Export OpenSSH key→ 保存为id_rsa（无后缀）或id_rsa.key - 导出时务必清空
Key passphrase字段；PhpStorm对带密码的OpenSSH密钥支持不稳定，容易卡在连接阶段 - 如果服务器强制要求密钥密码，别硬扛——改用
ssh-agent托管：终端运行eval $(ssh-agent); ssh-add ~/.ssh/id_rsa，再启动PhpStorm
最易忽略的一点：PhpStorm默认静默失败。上传异常不弹窗，只记在 View → Tool Windows → Deployment → Log 里，且日志级别默认是“仅错误”。真出问题，先去那里翻 Permission denied 或 No such file —— 别猜，直接看日志。
