sublime text 4 用户必须安装 sftp-next 插件，st3 用户可安装原版 sftp；配置文件 sftp-config.json 必须通过右键项目根目录生成，置于项目根目录下，且 host、user、remote_path 为必填项，upload_on_save 需设为 true（布尔值）才启用自动上传。
Sublime Text 4 用户不能用原版 SFTP 插件，必须改用 SFTP-Next；Sublime Text 3 用户可装原版，但不重启、不保存项目、不放对配置文件位置，90% 的“连不上”都是这三处卡住。
怎么确认自己该装哪个 SFTP 插件
打开 Help → About Sublime Text：
- 显示 Build 41xx（比如 Build 4143）→ 是 ST4，只能装 SFTP-Next
- 显示 Build 3xxx（比如 Build 3211）→ 是 ST3，可装原版 SFTP（作者 wbond）
- 如果 Package Control 搜索不到 SFTP，或装完右键没菜单，大概率是版本错配或没重启
装错的典型报错：ImportError: No module named 'urllib3'（ST4 强行装 ST3 插件）、菜单完全不出现（没重启）、命令面板搜不到 SFTP（Package Control 本身没装好）
sftp-config.json 必须放在哪、怎么生成
配置文件名必须是 sftp-config.json，且必须放在当前 Sublime 项目的根目录下——不是用户目录，不是插件目录，也不是桌面随便一个文件夹。
正确做法：
- 先通过 Project → Add Folder to Project 把本地项目文件夹加进侧边栏（确保它出现在顶层）
- 右键这个侧边栏里的文件夹图标 → SFTP/FTP → Map to Remote
- 自动生成 sftp-config.json，此时才真正绑定路径映射
常见错误：
- 直接新建一个空文件叫 sftp-config.json 手动写 → 插件静默忽略（不报错，也不连）
- 放在子目录里，或文件名多一个空格、大小写不对（如 SFTP-config.json）→ 失效
- 用单个文件打开 Sublime（没项目）→ 配置无效，upload_on_save 不触发
关键字段填什么、哪些不能漏
host、user、remote_path 是硬性必填项；漏任一都会提示 Connection failed: Invalid config。其他字段按需补充：
认证方式二选一：
- 密码登录：填 password 字段（不推荐，易泄露）
- 密钥登录：填 private_key（ST3/ST4 均支持），值必须是绝对路径，如 /Users/me/.ssh/id_rsa 或 C:/Users/me/.ssh/id_rsa；相对路径、权限非 600、路径不存在 → 静默失败，只报 Authentication failed
路径与同步控制：
- remote_path 必须以 / 开头，结尾不加 /（如 /var/www/html）
- upload_on_save 设为 true（布尔值，不是 "true" 字符串）才启用自动上传
- 该设置只对“当前文件所在文件夹及其子目录”生效；打开桌面一个 .js 文件，即使有配置也不同步
上传失败时去哪查原因
SFTP 插件没有图形化日志面板，所有线索都在 Sublime 控制台里：按 Ctrl+`（反引号）呼出，然后操作上传/保存，实时看输出。
典型线索：
- Permission denied → 远程目录权限不足（如 www-data 用户无写权），不是密码错
- ssh: handshake failed → 网络不通、端口被拦、sshd_config 关了 PasswordAuthentication
- 控制台没输出，右下角状态栏闪一下 Upload failed → 很可能是 remote_path 写错，或本地文件根本不在已映射目录下
注意：upload_on_save 开启后，如果远程路径权限不够，Sublime 不弹窗，只在控制台卡几秒后报错，容易以为“没反应”。
