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 配置要直接和高效得多。
