Sublime Text 作为一款广受欢迎的本地代码编辑器，其远程文件编辑功能需要通过插件来实现。许多用户在配置过程中会遇到连接失败的问题，这通常并非插件本身存在缺陷，而是几个关键配置环节出现了疏漏。根据常见问题统计，绝大多数连接失败都源于插件版本选择错误、编辑器未重启，或配置文件存放位置不正确。
如何正确选择 SFTP 或 SFTP-Next 插件
首要步骤是确认您使用的 Sublime Text 版本。请点击菜单栏的 帮助 → 关于 Sublime Text，查看 Build 版本号：
- 若版本号为 Build 41xx（例如 4143），则您使用的是 ST4。此版本必须安装
SFTP-Next插件。若错误安装了原版SFTP，通常会提示ImportError: No module named 'urllib3'这类导入错误。 - 若版本号为 Build 3xxx（例如 3211），则您使用的是 ST3。此版本安装原版
SFTP（作者为 wbond）即可，请注意区分名称相似的sftp-client或FTPSync等插件。 - 如果在命令面板中搜索不到
SFTP相关选项？很可能是因为尚未安装 Package Control 包管理器。请先按Ctrl+Shift+P，输入Install Package Control进行安装。
sftp-config.json 配置文件必须由插件生成并正确放置
sftp-config.json 配置文件的生成方式至关重要。手动创建同名文件，即使参数完全正确，插件也可能无法识别。它只认可通过特定菜单操作生成的配置文件。
- 首先，通过菜单 项目 → 将文件夹添加到项目，将您的本地项目文件夹添加至侧边栏（确保其为顶层文件夹）。
- 接着，在侧边栏右键单击该文件夹，选择
SFTP/FTP → 映射到远程…。此操作将自动生成sftp-config.json文件，并完成本地目录与远程服务器路径的关联。 - 此配置文件必须存放在项目的根目录下。若置于子目录、文件名大小写错误（如
SFTP-config.json）或文件名包含空格，都将导致配置失效。 - 另一个常见误区是：如果您未打开项目，而是单独编辑桌面上的某个文件，则配置完全无效，
upload_on_sa ve等自动保存功能也不会触发。
host、user、remote_path 为必填项，认证方式需正确选择
配置文件中的几个核心字段缺一不可。若遗漏 host、user 或 remote_path，将直接导致 Connection failed: Invalid config 错误。但更隐蔽的问题往往出现在认证方式的冲突上：
- 若服务器禁用了密码登录（SSH配置中设置了
PasswordAuthentication no），则配置文件中不能填写password字段，必须使用private_key指定密钥文件的绝对路径。例如：Linux/macOS 系统为/home/用户名/.ssh/id_rsa，Windows 系统为C:/Users/用户名/.ssh/id_rsa。 - 在 Linux/macOS 系统下，若
private_key文件的权限不是 600（可通过chmod 600 ~/.ssh/id_rsa命令修改），同样会导致认证失败，错误信息通常仅为模糊的Authentication failed。 remote_path字段的格式有严格要求：必须以/开头，结尾不加/（例如/var/www/html），否则会导致上传的文件路径错乱。- 若同时填写了
password和private_key两个字段，SSH 层会因认证冲突而拒绝连接，且通常不会给出具体原因。
upload_on_sa ve 自动上传功能的生效条件
设置了 "upload_on_sa ve": true 却未实现保存自动上传？这通常不是插件故障，而是某些隐性条件未满足：
- 首先，该字段的值必须是布尔值
true，而非字符串"true"。同时，它应置于配置的根层级，而非嵌套在files或sync_down_on_open等字段之下。 - 其次，您当前编辑的文件必须位于已通过
映射到远程…操作关联的本地项目目录内。即使桌面上存在同名同内容的文件，也不会触发同步。 - 若远程目录对您的 SSH 用户没有写入权限（例如，服务以 www-data 用户运行），上传会卡顿数秒后报错
Permission denied。Sublime Text 可能不会弹出明显提示，需查看编辑器右下角状态栏，或按Ctrl+`打开控制台查看详细输出。 - 遇到网络不稳定或服务器响应缓慢？可在配置中添加
"timeout": 10字段，适当提高连接超时容忍度。
总结而言，最容易出错的环节往往是：未通过右键项目根目录执行 映射到远程… 来生成配置，而是选择了手动编写。最容易被忽略的细节则是：ST4 用户错误安装了原版 SFTP 插件，或在配置密钥路径时使用了相对路径。这些疏漏一旦发生，整个连接流程便会在无声无息中中断，导致问题排查困难。
