Sublime Text 必须按版本装对应 SFTP 插件：ST3（Build 3xxx）装 wbond 版 SFTP，ST4（Build 41xx）装 SFTP-Next，否则报 ImportError 或菜单消失；必须用 Package Control 安装并重启；sftp-config.json 必须通过右键“Map to Remote…”生成于项目根目录，且 host、user、remote_path 缺一不可；upload_on_save 仅对绑定项目内文件生效；认证冲突或私钥权限错误会导致静默失败。
确认 Sublime Text 版本再装插件
ST4（Build 41xx）必须装 SFTP-Next，ST3（Build 3xxx）只能装作者为 wbond 的原版 SFTP。装错直接报 ImportError: No module named 'urllib3' 或菜单消失。打开 Help → About Sublime Text 看 Build 号，别凭感觉猜。
必须用 Package Control 安装，手动解压无效
插件有隐式依赖和初始化逻辑，拖 zip 进 Packages 目录大概率白装——右键没 SFTP/FTP 菜单、Project 里不显示选项。正确流程是：
- 按
Ctrl+Shift+P（Mac 用Cmd+Shift+P），输入Install Package Control确保已装 - 再按
Ctrl+Shift+P→ 输入Package Control: Install Package→ 等列表加载完 → 搜SFTP - ST3 选
SFTP（作者 wbond）；ST4 选SFTP-Next - 装完必须重启 Sublime Text，否则所有 SFTP 功能都不生效
sftp-config.json 必须由右键生成，不能手建
插件只认「右键项目根目录 → SFTP/FTP → Map to Remote…」这一步触发的配置文件。手动新建一个 sftp-config.json，哪怕内容完全正确，也会被静默忽略。注意：
- 先通过
Project → Add Folder to Project把本地项目加进侧边栏，确保它是顶层文件夹 - 右键这个文件夹图标本身（不是里面某个文件），选
Map to Remote… - 文件名必须是
sftp-config.json（全小写、带连字符、.json 小写） - 必须放在你右键的那个文件夹根目录下，不能在子目录
-
host、user、remote_path缺一不可；remote_path必须以/开头，结尾建议也加/（如"/var/www/html/"）
upload_on_save 不生效？检查项目绑定和路径范围
upload_on_save 只对映射目录内文件生效，且依赖隐性上下文：它不看当前打开的文件路径，只看你是否在“已绑定 SFTP 配置的项目”里编辑。常见失效原因：
- 没通过右键
Map to Remote…绑定项目，或没保存过.sublime-project文件 - 当前编辑的文件不在该配置的
local_path范围内（比如配置了"local_path": "/project"，但你在/project/src/js/app.js编辑，没问题；若在/tmp/test.js编辑，就不会上传） - 认证字段冲突：同时写了
password和private_key（ST3）或ssh_key_file（ST4），SSH 层直接拒绝连接，错误信息只有Authentication failed - 私钥权限不对：Linux/macOS 下必须
chmod 600 ~/.ssh/id_rsa，Windows 路径用正斜杠或双反斜杠（C:/Users/You/.ssh/id_rsa）
