uploadonsave开关本身不保证自动上传成功，真正起作用的是配置字段是否匹配、路径是否合法、文件是否在同步范围内；常见失败原因包括remotepath未以/开头或结尾多斜杠、sftp.json位置错误、ignore规则拦截、文件未保存或不在工作区路径内。
uploadOnSave 开关本身不保证自动上传成功，真正起作用的是配置字段是否匹配、路径是否合法、文件是否在同步范围内——很多“连不上”“不上传”的问题，根本不是插件坏了，而是 sftp.json 里填错了一个斜杠或少了一个 /。
为什么 SFTP: Upload File 右键没反应
这不是插件没装好，而是 VSCode 没识别出当前工作区已配置 SFTP。常见原因有：
- 没打开文件夹（只打开了单个文件），
sftp.json必须放在项目根目录的.vscode/下，且该目录需被 VSCode 作为工作区加载 -
sftp.json文件名写成sftp.config.json或ftp.json——必须是.vscode/sftp.json - 扩展未激活：检查左下角状态栏是否有
SFTP图标；没有就按Ctrl+Shift+P→ 输入Developer: Reload Window重载 - 配置里漏了
host或remotePath，这两个字段缺失会导致右键菜单直接不显示
remotePath 必须以 / 开头，且不能结尾带 /
这是最常踩的路径坑。填错会静默上传到错误位置，比如：
-
"remotePath": "var/www/html"→ 实际传到/home/username/var/www/html（相对路径，拼在用户 home 下） -
"remotePath": "/var/www/html/"→ 末尾斜杠会让部分服务器解析异常，uploadOnSave可能失败 - 正确写法只有：
"remotePath": "/var/www/html" - Windows 用户写私钥路径时，也必须用正斜杠：
"privateKeyPath": "C:/Users/name/.ssh/id_rsa"，反斜杠\会解析失败
uploadOnSave 生效但文件没传上去？检查这三处
这个布尔值只是开关，真正决定“传不传”“传哪儿”的是运行时匹配逻辑：
- 只对已保存过的文件生效：新建文件未执行过
Ctrl+S，不会触发上传 - 受
ignore规则拦截：哪怕手动右键上传，如果文件匹配"*.log"或".env"，也会跳过 - 路径映射失效：本地文件路径不在
remotePath对应的子树内。例如remotePath是/var/www/app，你却在项目外编辑/tmp/test.js，它永远不会上传 - 软链接默认不跟随：如果项目用了
ln -s指向别处，得加"followSymlinks": true配置项
中文文件名乱码、ECONNREFUSED、权限 600 错误的本质原因
这些报错看着像客户端问题，其实 90% 出在服务端或网络层：
-
ECONNREFUSED：不是密码错，是 SSH 服务根本没起来，或云服务器安全组没放行port（比如阿里云默认关 22）；先在终端跑ssh user@host -p 22确认通路 - 中文名显示为
%E4%BD%A0：服务器locale未设 UTF-8，执行locale -a | grep utf8，缺就装locales并dpkg-reconfigure locales -
Permission denied (publickey)：私钥权限太宽松（Linux/macOS 要求600），运行chmod 600 ~/.ssh/id_rsa - 上传后文件不可执行：SFTP 插件默认不保留 chmod，如需保持权限，加
"preserveModTime": true和"useTempFile": false
sftp.json 定义的是一次性映射关系；所谓“同步”，其实是单向操作叠加人工判断——这点容易被忽略，但决定了你是否该把 config.php 加进 ignore，而不是指望插件自动保护它。
