Sublime Text 4 用户必须安装 SFTP-Next 插件，ST3 用户可安装原版 SFTP；配置文件 sftp-config.json 必须通过右键项目根目录生成，置于项目根目录下，且 host、user、remote_path 为必填项，upload_on_sa ve 需设为 true（布尔值）才启用自动上传。
给Sublime Text配置SFTP同步，看似简单，实则暗藏玄机。先说一个核心区别：Sublime Text 4的用户，千万别装原版SFTP插件，必须改用SFTP-Next；而Sublime Text 3的用户，则可以放心使用原版。但无论哪个版本，如果没重启编辑器、没正确保存项目、或者配置文件放错了位置，那么90%的“连接失败”问题，都逃不出这三个原因。
怎么确认自己该装哪个 SFTP 插件
第一步，先搞清楚你的Sublime Text版本。打开菜单栏的 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_sa ve 这类功能也不会触发。
关键字段填什么、哪些不能漏
配置文件里，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_sa ve 必须设为 true（注意是布尔值，不是带引号的 "true" 字符串）才能启用保存自动上传。
- 这个自动上传功能，只对“当前文件所在的、已映射的文件夹及其子目录”生效。如果你直接从桌面打开一个 .js 文件，即使有配置文件，它也不会同步。
上传失败时去哪查原因
SFTP插件没有图形化的日志窗口，所有线索都藏在Sublime的控制台里。按 Ctrl+`（反引号键）呼出控制台，然后尝试上传或保存文件，就能看到实时输出。
控制台里的信息是关键的破案线索：
- 出现 Permission denied？这通常意味着远程目录的权限不足（比如用 www-data 用户身份没有写入权限），而不一定是密码错误。
- 出现 ssh: handshake failed？这可能指向网络不通、端口被防火墙拦截、或者服务器 sshd_config 里关闭了 PasswordAuthentication。
- 如果控制台一片空白，只有右下角状态栏闪了一下 Upload failed？那很可能是 remote_path 写错了，或者你当前编辑的本地文件，根本不在之前映射的那个项目目录下。
需要警惕的是：当 upload_on_sa ve 开启后，如果因为远程路径权限不够导致上传失败，Sublime通常不会弹窗提示，只会在控制台里卡顿几秒然后报错，很容易让人误以为是“插件没反应”。
