Sublime Text 本身不支持 SFTP 远程同步，必须依赖 SFTP 插件实现；90% 失败源于项目未绑定、sftp-config.json 位置或命名错误、SSH 认证被绕过，需通过 Project → Add Folder to Project 添加目录、右键文件夹选 Map to Remote 自动生成配置、确保 upload_on_save 置于根层级且路径匹配 remote_path。
Sublime Text 本身不支持 SFTP 远程同步，必须靠插件实现；但装完插件 ≠ 能用，90% 的失败源于项目未绑定、配置文件位置错误或 SSH 认证被插件绕过。
右键没出现 SFTP 菜单？先确认项目和文件夹是否“被识别”
插件只在特定上下文中激活：它不响应单个文件、桌面打开的文件、或“打开文件夹”这种临时视图。
- 必须通过
Project → Add Folder to Project把本地目录加进项目，且该目录要出现在侧边栏最顶层 - 右键对象只能是那个文件夹图标本身，不是里面某个
.js文件，也不是侧边栏空白处 - 装完插件后务必重启 Sublime Text，否则
Project菜单里都看不到 SFTP 项 - 确保安装的是作者为
wbond的SFTP（别选sftp-client或FTPSync）
sftp-config.json 必须放在项目根目录，且名字/路径/内容一个都不能错
这个文件不是全局配置，也不接受手动创建——插件只读取通过右键 Map to Remote… 在项目根目录自动生成的 sftp-config.json。错一个字符就静默失效。
- 文件名必须严格为
sftp-config.json（全小写、带短横线、.json 扩展名），SFTP-config.json、sftp_config.json都不行 -
remote_path必须以/开头，结尾建议也加/（如"/var/www/html/"），否则路径拼接会偏移 - 用密钥登录时，
password字段必须彻底删除；留空字符串（"password": ""）也会触发密码认证并失败 -
ssh_key_file支持~展开（如"~/.ssh/id_rsa"），但不识别$HOME或其他环境变量
upload_on_save 不生效？检查这四个隐性前提
这个开关只是触发器，真正决定是否上传的是路径匹配逻辑和项目上下文。
-
upload_on_save必须设为true，且放在sftp-config.json的根层级，不能嵌套在files或sync_down_on_open下面 - 当前文件必须属于已保存的项目（即存在
.sublime-project文件），且该文件路径需能被remote_path规则覆盖（比如配了"/var/www/html/"，但你在/src/index.js编辑，就不会上传） - 网络抖动或服务器响应慢时，默认 3 秒超时会导致静默失败；可在配置中加
"timeout": 10提高容错 - 首次连接会弹出主机指纹确认框，必须点“是”，否则后续所有同步都静默失败
上传后远程权限变成 600？补上 default_permissions
SFTP 插件默认用用户主目录权限掩码上传，web 目录通常需要 644（文件）或 755（目录）。
- 在
sftp-config.json根层级添加"default_permissions": "644"（文件）或"default_permissions": "755"（目录） - 注意：这个值是字符串，不是数字，写成
644会报错 - 如果同时启用
sync_down_on_open，远程文件被其他人改过（比如git pull），插件不会自动刷新，得手动右键Download
最常被忽略的一点：SFTP 插件不复用终端里的 ssh-agent，每次都是全新握手。即使你本地 ssh user@host 能免密登录，插件仍可能卡在认证环节——看 Ctrl+Shift+P → SFTP: Show Console 才能看到真实错误。
