必须按版本选插件：st4（build 41xx）装sftp-next，st3（build 3xxx）装wbond原版sftp；装错报importerror或菜单消失；装完须重启；sftp-config.json必须通过右键项目根目录→sftp/ftp→map to remote生成，不可手建，且须置于项目根目录下，host、user、remote_path为硬性必填项。
Sublime Text 本身不能直接连接服务器编辑文件，必须装 SFTP 插件，且必须按版本选对插件（ST4 用 SFTP-Next，ST3 用 wbond 原版 SFTP），装错或不重启就完全没反应。
怎么确认该装 SFTP 还是 SFTP-Next
打开 Help → About Sublime Text，看 Build 号：
- Build 41xx（如
4143）→ 是 ST4，必须装SFTP-Next；装原版会报ImportError: No module named 'urllib3'，菜单直接消失 - Build 3xxx（如
3211）→ 是 ST3，只能装作者为wbond的原版SFTP；搜到sftp-client或FTPSync都是错的
装完必须重启 Sublime Text，否则 Project 菜单里看不到 SFTP，右键也无响应。
sftp-config.json 必须由右键生成，不能手建
插件只认「右键项目根目录 → SFTP/FTP → Map to Remote…」这一步触发的配置文件。手动新建一个 sftp-config.json，哪怕内容完全正确，也会被静默忽略：
- 先通过
Project → Add Folder to Project把本地项目加进侧边栏（确保它是顶层文件夹） - 右键这个文件夹图标本身 →
SFTP/FTP → Map to Remote…，自动生成配置并绑定路径 - 文件名必须是
sftp-config.json（全小写、带连字符、.json小写），不能是SFTP-config.json或sftp_config.json - 必须放在你右键的那个文件夹根目录下，不能在子目录、不能放错位置
认证字段冲突会导致连接静默失败
host/user/remote_path 缺一不可，漏掉直接报 Connection failed: Invalid config；但更隐蔽的问题出在认证字段共存：
- 服务器禁密码登录（
PasswordAuthentication no）？那就不能填password，必须用private_key（ST4）或ssh_key_file（ST3），值必须是绝对路径：/home/you/.ssh/id_rsa或C:/Users/You/.ssh/id_rsa -
private_key或ssh_key_file文件权限不是600（Linux/macOS 下执行chmod 600 ~/.ssh/id_rsa）→ 认证失败，但错误信息只显示Authentication failed - 同时写了
password和private_key→ SSH 层直接拒绝连接，不会提示具体原因 -
remote_path必须以/开头，结尾建议也加/（如"/var/www/html/"），否则路径拼接会偏移
upload_on_save 不生效？检查项目绑定和路径范围
upload_on_save 仅对映射目录内文件生效，且依赖隐性上下文：
- 必须是通过右键「Map to Remote…」绑定的项目，不是随便打开的文件夹
- 只对该项目根目录及其子目录下的文件生效；在项目外打开的同名文件不会上传
- 没有失败回滚机制：上传失败时只弹小提示，文件已保存但远程未更新，容易误以为同步成功
- 如果想打开远程文件时自动下载最新版，要额外开启
sync_down_on_open: true
最常被忽略的是：配置文件存在、SSH 能通、甚至能手动上传，但 upload_on_save 就是不动——八成是项目没绑定，或者文件不在映射路径下。
