必须根据sublime text版本选择插件：build 41xx（如4143）为st4，须装sftp-next，否则报importerror；build 3xxx（如3211）为st3，只能装wbond原版sftp；确认方式是help → about sublime text查看build号。
怎么确认该装 SFTP 还是 SFTP-Next
Sublime Text 4（Build 41xx）必须装 SFTP-Next，装原版 SFTP 会直接报错 ImportError: No module named 'urllib3'；Sublime Text 3（Build 3xxx）只能装原版 SFTP（作者 wbond）。打开 Help → About Sublime Text 看 Build 号就能定死——别猜，别试错。装错插件后菜单不出现、命令面板搜不到 SFTP，基本就是版本错配。
sftp-config.json 必须由右键生成，不能手写
配置文件名必须是 sftp-config.json，且必须放在项目根目录下——不是随便一个文件夹，也不是用户目录或插件目录。关键动作只有一条：先通过 Project → Add Folder to Project 把本地项目加进侧边栏顶层，再右键这个文件夹图标 → SFTP/FTP → Map to Remote…。这时插件才会自动生成合法配置。手动新建文件、改名、放错位置，插件一律静默忽略，不报错也不连。
-
host、user、remote_path是硬性必填项，漏一个就提示Connection failed: Invalid config -
remote_path必须以/开头，结尾建议也加/（如/var/www/html/），否则路径拼接可能错位 -
upload_on_save必须是布尔值true，不是字符串"true"，且必须放在配置文件最外层，不能嵌套在files或sync_down_on_open下面
密钥登录比密码更稳，但路径和权限不能错
服务器禁用密码登录（PasswordAuthentication no）时，填 password 字段完全无效，只会报模糊的 Authentication failed。此时必须用 private_key 字段，值为绝对路径：
- macOS/Linux：
"/Users/you/.ssh/id_rsa" - Windows：
"C:/Users/you/.ssh/id_rsa"（正斜杠或双反斜杠都行，单反斜杠不行） - 路径必须存在，且私钥文件权限必须是
600（chmod 600 ~/.ssh/id_rsa），否则 SSH 层拒绝读取 - 不支持
$HOME或环境变量，但支持~展开（如"~/.ssh/id_rsa"）
upload_on_save 不生效？先看这四件事
设了 "upload_on_save": true 却没反应，90% 是上下文缺失：
- 当前文件不属于已保存的项目（即没有
.sublime-project文件，或没通过Project → Add Folder to Project加入） - 编辑的文件路径不在
remote_path覆盖范围内（比如配的是/var/www/html/，你却在/src/js/app.js编辑） - 网络抖动或服务器响应慢，默认 3 秒超时导致静默失败，可加
"timeout": 10提高容错 - 插件没重启——装完
SFTP或SFTP-Next后必须重启 Sublime，否则右键菜单、命令面板全都不见
真正起作用的从来不是“开关开了”，而是项目绑定、路径匹配、认证成功、超时容忍这四者同时成立。少一个，上传就卡在无声里。
