Sublime Text安装SFTP插件并配置远程服务器连接教程

如何正确选择 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 插件，或在配置密钥路径时使用了相对路径。这些疏漏一旦发生，整个连接流程便会在无声无息中中断，导致问题排查困难。