Sublime Text搭配SFTP插件实现外网同步提升代码修改效率

Sublime Text 编辑器本身不具备外网文件同步功能，实现这一需求必须借助 SFTP 插件。然而，一个关键点需要明确：“能够连接”与“能够稳定同步”是两个截然不同的概念。大多数外网同步失败的原因，并非服务器未开启 SFTP 服务，而是插件的 SSH 握手流程未能成功建立，或者本地与远程服务器的路径映射关系从一开始就配置错误。

右键菜单没有 SFTP 选项？首先确认项目与文件夹是否被正确识别

SFTP 插件并非在所有界面下都会激活。其菜单项仅对「已加载到项目中的目录」以及「侧边栏中实际显示的文件夹图标」生效。这不是界面错误，而是插件固有的设计逻辑。

• 必须通过项目菜单操作：务必使用 Project → Add Folder to Project 将本地目录加入项目。仅使用 File → Open Folder 打开文件夹是无效的。
• 正确的右键操作对象：右键点击的对象必须是侧边栏顶层的文件夹图标本身。对文件夹内的文件、编辑器空白区域或未保存的临时标签页右键，都不会出现 SFTP 菜单。
• 重启编辑器生效：通过 Package Control 安装 SFTP 插件后，必须重启 Sublime Text。因为 Package Control 不会热加载新的菜单项。
• 认准官方正版插件：确保安装的是作者为 wbond 的官方 SFTP 插件，避免误装名称相似的 sftp-client 或 FTPSync 等替代品。

sftp-config.json 配置文件：位置与字段必须准确，否则静默失效

此配置文件并非全局生效，它严格绑定在你右键映射的本地文件夹根目录下。文件名的大小写、存放路径、内容格式有任何错误，插件都会直接视其为不存在。

• 文件名必须精确无误：必须是全小写的 sftp-config.json（注意短横线，扩展名为.json）。写成 SFTP-config.json 或 sftp_config.json 都会导致配置无效。
• 存放位置必须正确：必须放在项目的根目录（即你右键映射的那个文件夹）下，不能放在其子目录或用户的全局配置目录中。
• 远程路径格式规范：remote_path 必须以 / 开头，结尾也建议加上 /（例如 "/var/www/html/"），否则在拼接文件路径时容易发生偏移。
• 密钥文件路径写法：ssh_key_file 字段支持使用 ~ 来表示用户主目录（如 "~/.ssh/id_rsa"），但它不识别 $HOME 这类环境变量。
• 密钥认证的关键步骤：当使用 SSH 密钥登录时，务必彻底删除配置中的 password 字段。即使将其留为空字符串（"password": ""），插件也会尝试进行密码认证，从而导致连接失败。

upload_on_save 设置了却不上传？检查三个隐性前提条件

upload_on_save 这个开关只是一个触发器，真正决定文件能否成功上传的，是背后一系列上下文匹配逻辑，而不仅仅是配置项本身。

• 配置项层级正确：upload_on_save 必须写在 sftp-config.json 配置文件的根对象层级，不能嵌套在 files、sync_down_on_open 或其他字段内部。
• 路径映射精确对齐：当前正在编辑的本地文件，其路径必须落在 local_path（或项目根目录）之下。并且，它的相对路径要能准确地与 remote_path 映射对齐。例如，remote_path 为 "/var/www/html/"，本地文件是 index.html，那么它就应该被上传到服务器的 /var/www/html/index.html。
• 网络超时设置调整：如果服务器响应较慢，插件默认的 3 秒连接超时可能不够。可以在配置中添加 "connect_timeout": 10 来提高容忍度。
• 注意认证方式独立性：即使你在系统终端里已经可以通过 ssh-agent 实现免密登录，SFTP 插件也不会复用这个认证。它每次发起连接时，都会重新调用系统的 ssh 命令。

外网同步失败时，别猜测，直接查看底层日志

当同步失败时，弹出的错误提示往往很模糊（例如只显示 Permission denied 或者干脆没反应），这是因为插件隐藏了底层的详细错误信息。真正的故障原因，都藏在控制台日志里。

• 调出控制台：按下 Ctrl+Shift+P（macOS 是 Cmd+Shift+P），打开命令面板，输入 SFTP: Show Console 并回车。
• 查看真实日志详情：所有底层的 ssh 和 sftp 命令、返回码以及具体的错误信息都会在这里实时打印出来。
• 常见问题排查：日志里经常暴露的问题包括：ssh_key_file 指定的密钥文件权限不是 600（在 Linux/macOS 下需执行 chmod 600 ~/.ssh/id_rsa）；远程服务器的 /etc/ssh/sshd_config 中关闭了 PubkeyAuthentication yes 选项；remote_path 指向的目录对当前 SSH 用户没有写入权限。
• 文件权限问题解决：如果上传后文件权限变成了 600 导致网页无法访问，可以在配置中添加 "default_permissions": "644" 来指定默认权限。

归根结底，实现 Sublime Text 外网同步最脆弱的环节从来不是配置文件的语法，而是 SSH 认证链条的完整性和路径映射的精确性。一旦涉及公网 IP、防火墙规则、非标准端口或 Web 目录权限，每一个环节都可能成为断点，而且往往没有明确的错误提示。因此，最有效的排错方法是：在反复修改 Sublime Text 配置之前，先在系统终端里使用命令 ssh -i ~/.ssh/yourkey user@host -p 22 测试 SSH 连接是否畅通。这比盲目调整 JSON 配置要直接和高效得多。