根本原因是Deployment未启用自动上传或文件不在映射路径内；需检查Options中“Upload changed files automatically”是否勾选、Default server是否正确，并确认Mappings中Local path与Deployment path（相对Root path）配置准确无误。

为什么修改文件后 SFTP 没自动上传？

很多开发者都遇到过这个困扰：明明保存了文件，远程服务器上却纹丝不动。问题根源通常就两点：要么是Deployment配置里的“自动上传”开关没打开，要么就是你正在编辑的文件，根本不在PhpStorm认定的“管辖范围”内。这里有个关键认知：PhpStorm并不会监听你整个项目文件夹的所有变动，它只对那些在Deployment > Configuration > Mappings中明确建立了映射关系的目录“负责”。

典型的错误现象有两种：一是通过File > Upload to...菜单可以手动上传成功，但保存文件时自动触发不了；二是只有部分文件夹（比如src/）的文件能自动同步，而像vendor/或dist/这类目录却被漏掉了。

• 首先，打开Settings > Build, Execution, Deployment > Deployment > Options面板。重点确认两件事：Upload changed files automatically to the default server这个选项是否被勾选，以及下方的下拉菜单里，选中的是不是你配置好的那个目标服务器名称。
• 其次，确保你当前正在编辑的文件的完整路径，至少能与Mappings列表中的某一条规则匹配上。虽然这里支持通配符，但为了避免意外，更推荐使用具体、明确的路径进行配置。
• 最后，如果你配置了多个服务器，请务必检查Default server是否设置正确。这个默认服务器选项，直接决定了自动上传功能的目标是谁，一旦设错，整个自动上传逻辑就会被直接跳过。

如何正确设置 SFTP 连接和路径映射？

连接失败或者文件上传到了莫名其妙的目录？90%的问题都出在这一步。其实SFTP配置的核心，就是理清“谁去连接谁、连接到哪、文件放到哪”这三个环节，环环相扣，缺一不可。

• 在Deployment > Configuration > Connection标签页下，SSH configuration部分推荐使用密钥登录，安全性更高。你需要准确填写Host（主机地址）、Port（端口，通常是22）、User name（用户名）。然后点击旁边的...按钮，选择Key pair来指定你的私钥文件——这里千万注意，要选的是私钥（例如id_rsa），而不是那个以.pub结尾的公钥文件。
• Root path这个字段非常关键，它指的是远程服务器上，为你所配置用户设定的绝对路径起点，例如/var/www/html。切记不要图省事填写~（用户家目录）或者留空，否则后续的路径计算会全部出错。
• 切换到Mappings标签页，这里的逻辑需要理解清楚：Local path填写的是你本地项目根目录下的相对路径（比如.代表整个项目，src/代表src目录）；而Deployment path填写的是相对于上面那个Root path的路径（比如/代表直接放到根路径下，/app代表放到根路径下的app文件夹里）。两者最终会拼接起来，构成文件上传的完整目标地址。

保存即上传但报错“Permission denied”怎么办？

遇到权限被拒绝的提示，这通常不是PhpStorm本身的问题，而是远程服务器的文件权限或用户身份不匹配导致的。SFTP上传操作使用的是你在配置中指定的SSH用户，这个用户必须对目标目录拥有写入权限。

立即学习“PHP免费学习笔记（深入）”；

• 第一步，通过SSH登录到你的远程服务器，执行命令ls -ld /var/www/html（请将路径替换为你实际设置的Root path）。查看输出结果，确认目录权限中包含drwxr-xr-x这类允许写入的标志（重点看属主用户的权限），并且目录的属主或属组是你配置中使用的那个用户名。
• 如果目录属主是www-data这类系统用户，而你配置的SSH用户是deploy这样的普通用户，那么就需要将deploy用户加入到www-data用户组中。可以执行sudo usermod -a -G www-data deploy命令，完成后可能需要重启sshd服务，或者直接使用www-data用户来配置SSH连接（但后者通常不推荐，因为涉及较高的安全风险）。
• 另外需要注意，某些共享主机（shared hosting）环境可能会禁用chmod或chown命令。在这种情况下，即使文件上传成功，也可能因为权限不足而无法被Web服务器执行。因此，上传完成后，务必手动访问一下页面或者输出phpinfo()来验证一切是否正常。

自动上传时忽略 node_modules、.git 等目录

默认情况下，PhpStorm的自动上传功能会同步所有发生改动的文件，这当然也包括node_modules、.git这类体积庞大且完全没必要同步的依赖目录，既拖慢速度又浪费资源。所以，我们必须明确地告诉它哪些路径需要被排除。

• 配置位置不在终端设置里。正确的路径是：Deployment > Options标签页，往下拉，找到Excluded Paths输入框。
• 在这里，你可以逐行添加需要跳过的路径模式，并且支持通配符。常见的排除项包括：node_modules/**、.git/**、composer.lock、dist/**等。记住，每行只能写一个模式，不能用逗号分隔。
• 需要了解的是，这里设置的排除规则仅对“自动上传”生效，不会影响你通过Upload to...进行的手动上传，也不会影响Sync with Deployed to...这类远程同步操作。因此，在测试阶段，一个稳妥的做法是先关闭自动上传，通过“手动上传”配合“远程同步”来验证你的排除逻辑是否按预期工作了。

总结来说，自动上传功能看似是“一键开启”，但实际上它稳定运行依赖于三个条件同时成立：稳定的连接、准确的路径映射、以及合理的远程权限。其中最容易踩坑的一点，就是很多人误以为Mappings中的Deployment path要填绝对路径，结果填成了/var/www/html，导致文件最终被上传到了类似/var/www/html/var/www/html/xxx这种嵌套的错误路径里——切记，那里填的是相对于Root path的相对路径。