vscode 用 sftp 远程改代码本质是“本地编辑+自动同步”，需配置 .vscode/sftp.json 且 uploadonsave 设为 true；推荐安装 natizyskunk 版 sftp 插件，功能稳定、响应快、行为直观。
VSCode 用 SFTP 远程改代码，本质不是“远程编辑”，而是“本地编辑 + 自动同步”——所以必须配对 sftp.json，且 uploadOnSave 要设为 true，否则 Ctrl+S 没反应。
装哪个 SFTP 插件才靠谱
VSCode 扩展市场里搜 SFTP，会出现多个同名插件。真正稳定、持续更新、支持 watcher 和多 profile 的只有两个作者的版本：Natizyskunk 和 liximomo。二者功能几乎一致，但 Natizyskunk 版本在 2026 年更活跃，issue 响应快，uploadOnSave 行为更符合直觉。
别装 Nebula-Dev 或 NTVDM 的“SFTP”——它们要么已停更，要么把 uploadOnSave 默认关掉还不提示，保存后没上传还以为是网络问题。
- 安装后不用重启 VSCode，但首次使用前建议关闭再打开项目文件夹，避免缓存未加载配置
- 侧边栏出现云朵图标 ≠ 插件就绪，得等你生成并保存了
.vscode/sftp.json后才真正激活 - 如果命令面板里搜不到
SFTP: Config，说明插件没装对，删掉重装 Natizyskunk 版
sftp.json 必填字段和易错点
配置文件必须放在项目根目录下的 .vscode/sftp.json，不能叫 .sftp.json（少个 vscode 文件夹）也不能放错位置。内容不是自由格式，漏掉 host 或 remotePath 会导致连接失败且错误提示极模糊（只报 “Cannot read property ‘host’ of undefined”）。
-
remotePath必须是远程绝对路径，末尾不加斜杠，比如/home/ubuntu/project，写成/home/ubuntu/project/会同步到子目录下 -
password和privateKeyPath二选一；用密钥时，privateKeyPath要写本地完整路径（Windows 用正斜杠或双反斜杠，如C:/Users/name/.ssh/id_rsa），不能用~ -
uploadOnSave必须是布尔值true，写成"true"（字符串）或1都无效 - 如果远程路径权限不够（比如
www-data用户写的目录，你用ubuntu登录），上传会静默失败——此时要检查远程ls -ld /your/remotePath
为什么保存后没上传？常见断点排查
最常卡在这一步：配置写了，也保存了 sftp.json，但 Ctrl+S 完全没动静。不是插件坏了，大概率是下面几个环节断了：
- 没在正确的文件夹里打开项目——必须用
File → Open Folder打开含.vscode的那个根目录，而不是单个文件 -
uploadOnSave是全局开关，但它只对remotePath下能映射到的路径生效；比如你在src/main.py改代码，但remotePath设的是/var/www/html，那它根本不知道该往哪传 - 文件被
ignore规则拦住了，比如你加了"**/__pycache__/**"，但忘了**/*.pyc也会被忽略，导致 .py 文件没传——检查ignore是否误伤了源码扩展名 - 网络不通或 SSH 端口被墙，但插件不会弹红字错误，只会卡在“connecting…”；可手动运行
SFTP: List命令看能否列出远程文件来验证连通性
想实时监听改动？别只靠 uploadOnSave
uploadOnSave 只响应保存动作，不响应文件系统级变更（比如 git checkout、脚本生成文件）。真要接近“实时”，得开 watcher：
在 sftp.json 顶层加一段：
{
"watcher": {
"files": "**/*",
"autoUpload": true,
"autoDelete": true
}
}
注意：watcher 不是默认开启的，也不随 uploadOnSave 自动启用；而且它依赖本地文件系统 inotify（Linux/macOS OK，Windows WSL2 可用，纯 Windows 需要额外装 chokidar 且不稳定）。
另外，watcher 会监控整个项目，如果你的 node_modules 在项目内又没加进 ignore，它可能每秒触发几十次上传请求，直接拖垮 VSCode。务必配合 ignore 使用。
