Deployment映射必须以项目根为Local path，否则路径裁剪错乱；远程路径需匹配Web服务器DocumentRoot，且权限、用户组、SELinux等隐性依赖须同步验证。
Deployment 映射里填了绝对路径，但上传后文件位置错乱
本地路径写成 /Users/you/project/src、远程路径写成 /var/www/html，看着很合理，但 PhpStorm 实际部署时会把本地路径“当作根”去裁剪，再拼到远程路径上。一旦本地路径和项目根不一致，或你用的是子模块/符号链接，裁剪就失效。
常见错误现象：本地 /Users/you/project/src/index.php 传到远程变成 /var/www/html/src/index.php（多了一层 src），而不是预期的 /var/www/html/index.php。
- 始终用项目根为基准：在 Deployment → Mappings 中，
Local path必须是整个项目的根目录（如$ProjectFileDir$），不是某个子目录 - 远程路径要对应 Web 服务器 DocumentRoot，比如 Apache 的
/var/www/html或 Nginx 的/srv/www - 如果必须只部署子目录（如
public/），就设Local path为$ProjectFileDir$/public，Deployment path为/var/www/html—— 这样裁剪才干净
右键 Upload 后提示“Connection refused”或“Permission denied”
这不是路径本身错，而是路径背后的身份和权限没对齐。Deployment 配置里的 Host、Port、Username 看似填对了，但实际连接时可能被 SSH key、防火墙、SELinux 或远程用户家目录权限卡住。
常见错误现象：Test SFTP Connection 成功，但 Upload 失败；或者 Upload 到 /tmp 成功，到 /var/www 失败。
立即学习“PHP免费学习笔记（深入）”；
- 先手动 SSH 登录验证：运行
ssh user@host 'ls -ld /var/www/html'，确认目录存在且用户有写权限 - 检查远程用户是否在
www-data或apache组里（Linux）；Windows IIS 场景则确认 IUSR 或应用池用户有 NTFS 写权限 - SFTP 连接成功 ≠ 能写目标目录。很多服务器默认限制 SFTP 用户只能在其家目录操作，需在
/etc/ssh/sshd_config中配置ChrootDirectory或改用普通 SSH + rsync 方式
本地改了文件，Upload 却没同步，或同步了但远程没生效
根本原因常是 PhpStorm 没识别出文件变更，或上传后 Web 服务缓存/OPcache 没刷新。
常见错误现象：“Upload to xxx” 右键菜单灰掉；或上传成功但浏览器访问仍是旧内容。
- 检查文件是否被标记为 “Excluded”：右键文件 → Mark as → Cancel Exclusion；或进
Settings → Directories确认没有误加 Exclude 规则 - 确认 PhpStorm 的 “Auto-upload” 开关没关：Deployment → Options → ✅
Upload changed files automatically to the default server - PHP OPcache 不会自动检测文件更新。远程执行
sudo systemctl reload php8.2-fpm或临时加opcache.revalidate_freq=0（仅开发环境）
Windows 本地路径含空格或中文，导致 Deployment 报错
PhpStorm 的 SFTP 客户端底层依赖 JSch 或 native SSH，对空格和非 ASCII 字符路径解析不稳定，尤其在 Windows 上用 C:\My Project\ 或 C:\项目\ 作 Local path 时容易截断或编码错误。
常见错误现象：上传失败并报 java.io.FileNotFoundException 或路径末尾出现乱码字符。
- 本地路径尽量用纯英文、无空格、无特殊符号（如括号、&、#）
- 若必须用中文路径，改用 WSL2 下的 Linux 子系统作为本地开发环境，路径统一为
/home/user/project - 避免将项目放在 OneDrive、iCloud 或 Dropbox 同步目录下——这些服务会锁文件，导致 PhpStorm 读取状态异常
