保存后未上传，首要排查三硬性条件：.vscode/sftp.json必须位于项目根目录、uploadonsave必须为顶层布尔true、remotepath须为以/开头的绝对路径；任一不满足均导致静默失败。

uploadOnSave 必须设为 true，且配置文件必须是项目根目录下的 .vscode/sftp.json —— 其他位置、其他文件名、其他格式（如 sftp.json 或 .sftp.json）都不生效。

为什么保存后没上传？先确认这三处硬性条件

插件不会报错，但静默失败几乎都卡在这几个基础点上：

• .vscode/sftp.json 文件必须存在，且路径严格在当前工作区（即你用 VSCode「打开文件夹」的那个目录）下；开单个文件或放错位置（比如放在用户目录或 ~/.vscode）会导致插件完全不读配置
• remotePath 必须是以 / 开头的绝对路径，例如 "/var/www/html"；写成 "var/www/html" 或 "/var/www/html/"（末尾斜杠）都会导致路径拼接错误
• uploadOnSave 必须是顶层字段，值为布尔 true，不能嵌套在 config 或 profiles 里，也不能写成字符串 "true"

uploadOnSave 的实际行为边界在哪？

它不是“监听所有改动”，而是“仅对已保存过的、位于当前工作区内的文件生效”：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 新建文件未显式保存（Ctrl+S）前，改完直接关掉，不会触发上传
• 文件路径超出 remotePath 映射范围（比如你在 ../other-project/index.js 编辑），不会上传
• 被 ignore 规则匹配的文件（如 "**/*.log"）即使保存了也跳过，且不提示
• 不处理符号链接，默认不跟随；需手动加 "followSymlinks": true

密钥登录失败：常见私钥陷阱

报 Permission denied (publickey) 不一定是密码错了，大概率是私钥本身或路径配置出了问题：

• privateKeyPath 填的是本地绝对路径，~ 不展开，得写成 "/Users/you/.ssh/id_rsa" 或 "C:/Users/you/.ssh/id_rsa"
• 私钥文件权限必须是 600（macOS/Linux），Windows 上要检查文件属性 → 安全 → 当前用户有“读取”权限
• 如果填了 password 字段，插件会优先走密码认证；服务器禁用密码登录时，删掉 password 字段比留空更可靠
• 私钥必须是 OpenSSH 格式（-----BEGIN OPENSSH PRIVATE KEY-----），PuTTY 的 .ppk 不支持

上传成功但文件位置不对？重点看 remotePath 和工作区结构

路径映射逻辑很直白：本地文件相对于工作区根目录的路径，直接拼到 remotePath 后面。容易误判的点就在这里：

• 你打开的文件夹是 /Users/me/project，里面有个 src/main.js，remotePath: "/var/www/app" → 上传到 /var/www/app/src/main.js
• 如果你误把 src 文件夹单独拖进 VSCode，那工作区根目录就变成 /Users/me/project/src，此时 main.js 会传到 /var/www/app/main.js（丢失 src/ 层级）
• remotePath 必须提前在服务器上存在，插件不会自动创建目录；permission denied 很可能是目标目录属主不是你当前 username

真正麻烦的不是配置项数量，而是路径映射关系必须和你的工作区打开方式严丝合缝——差一个层级、少一个斜杠、多一个点，上传就会落到意料之外的位置。调试时别只看是否报错，一定要打开 SFTP: Open Log 看最后一行有没有 UPLOADED 和具体路径。