必须用SFTP协议而非FTP，因主流插件已停更FTP功能，云服务器默认关闭FTP端口且不支持明文传输；启用protocol:"ftp"会导致连接失败或静默无响应。
能用，但必须用 SFTP 协议，不能用 FTP；FTP 在现代 VSCode 环境下基本不可靠，且不安全。
为什么不能直接填 ftp:// 或启用 protocol: "ftp"
VSCode 的主流 SFTP 插件（如 liximomo.sftp 或 Natizyskunk.sftp）名义上支持 protocol: "ftp"，但实际已多年未维护 FTP 功能。启用后常见现象是：Connection refused、Authentication failed 或保存后无响应。根本原因是：FTP 依赖明文传输 + 主动/被动模式协商，而云服务器（阿里云、腾讯云、AutoDL 等）默认关闭 FTP 服务，且防火墙通常只放行 SSH（端口 22），不开放 FTP 的 21 端口及随机数据端口。
- 不要尝试在
sftp.json中写"protocol": "ftp"—— 它不会工作，只会浪费排查时间 - 如果你的服务器确实只开了 FTP（极少见），请改用 FileZilla 或
lftp命令行，而非 VSCode 插件 - 真正可用的协议只有
sftp（走 SSH 通道），它天然加密、无需额外端口、兼容所有标准 Linux 服务器
uploadOnSave 为 true 却不上传？检查这三处
这是最常被忽略的配置断点。插件不会上传，往往不是连接失败，而是“上传动作被静默跳过”。
-
remotePath必须是绝对路径，且末尾不能加斜杠（如"/home/user/project"✅，"/home/user/project/"❌）—— 否则插件内部路径拼接会出错，日志显示Remote path not found - 当前编辑的文件路径必须在项目根目录下，且其相对路径需能被
remotePath映射。例如本地打开的是/a/b/c/project/，但remotePath设为/var/www/html，那么保存src/main.py时，插件会试图上传到/var/www/html/src/main.py—— 如果该远程路径不存在，上传失败且无明确报错 -
ignore规则匹配优先级高于上传。若你写了"**/*.py"，那所有 Python 文件都会被跳过。建议先设为[]测试，再逐步加规则
密钥登录失败：权限与路径是两大雷区
比密码登录更安全，但配置稍复杂。失败时极少是密钥本身问题，多是环境细节没对齐。
- Windows 下
privateKeyPath必须用正斜杠或双反斜杠："C:/Users/name/.ssh/id_rsa"✅，"C:\Users\name\.ssh\id_rsa"❌（JSON 解析会把\s当转义） - Linux/macOS 上私钥文件权限必须是
600：chmod 600 ~/.ssh/id_rsa，否则 OpenSSH 拒绝读取，报错Permission denied (publickey) - 如果私钥设置了 passphrase，必须在配置中显式填写：
"passphrase": "your-passphrase"；留null或空字符串会导致认证中断 - 不要混用
password和privateKeyPath—— 插件会优先尝试密钥，失败后不会 fallback 到密码
多个服务器怎么切？别手动改 sftp.json
硬编码单个连接容易误操作，也难协作。正确做法是用 profiles + 命令面板快速切换。
- 在
sftp.json里定义profiles字段，每个 profile 是独立连接配置（含不同host、remotePath、username） - 按
Ctrl+Shift+P→ 输入SFTP: Connect to Server→ 选择目标 profile，插件会临时覆盖当前连接上下文 - 切换后，
uploadOnSave自动生效于新 profile 的remotePath，无需重启 VSCode - 注意：
profiles不支持嵌套或变量，所有路径和字段都得写死；团队共用时，把sftp.json加入.gitignore，只提交模板
真正的难点不在配置语法，而在路径映射是否精确、权限是否收紧、profile 是否隔离。同步一旦出问题，90% 都卡在这三步里，而不是插件本身。
