sftp插件连不上或同步失败的根本原因是其依赖本地ssh命令和密钥认证链路，而windows默认无openssh，macos/linux则易受自定义ssh配置或非默认密钥路径干扰。
为什么 SFTP 插件在 Sublime 上经常连不上或同步失败
根本原因不是插件本身坏了，而是 SFTP 插件依赖本地 ssh 命令和密钥认证链路，而 Windows 默认没装 OpenSSH 客户端，macOS / Linux 虽有但常被自定义 ~/.ssh/config 或非默认密钥路径干扰。常见报错如 Connection refused、Permission denied (publickey)、Failed to upload file，基本都卡在这层连接初始化上。
- Windows 用户必须确认系统 PATH 中存在
ssh可执行文件（推荐安装 Git for Windows 并勾选 “Add Git to PATH”） - 所有平台都要检查私钥权限：Linux/macOS 下运行
chmod 600 ~/.ssh/id_rsa，否则 OpenSSH 会直接拒绝加载 - 如果用了
~/.ssh/config，确保其中的Host别名与 SFTP 配置里的host字段完全一致（区分大小写）
如何正确生成并配置 sftp-config.json 文件
Sublime 的 SFTP 插件不读取全局 SSH 配置，必须为每个项目单独建 sftp-config.json。该文件需放在项目根目录（即 Sublime 左侧边栏显示的最顶层文件夹），且文件名必须全小写、带短横线、带 .json 后缀——拼错一个字符都会导致插件静默忽略配置。
{
"type": "sftp",
"sync_down_on_open": false,
"sync_same_age": true,
"confirm_downloads": false,
"upload_on_save": true,
"connect_timeout": 30,
"host": "example.com",
"user": "deploy",
"port": 22,
"remote_path": "/var/www/myapp/",
"ignore_regexes": [".git", ".DS_Store", "node_modules/"],
"ssh_key_file": "~/.ssh/deploy_key"
}
-
remote_path必须以/结尾，否则上传路径会拼接错误 -
ssh_key_file支持~展开，但不支持环境变量（如$HOME） - 若服务器禁用密码登录，必须提供
ssh_key_file；若用密码，删掉该字段并加上"password": "xxx" - 修改保存后，右键文件 →
SFTP→Reconnect才会重载配置，不是自动生效
上传失败时怎么快速定位是路径、权限还是编码问题
同步失败不一定代表连接断了，更可能是远程目录不可写、文件名含 Unicode 字符、或服务器 umask 导致新建文件无执行权限。SFTP 插件日志藏得深，但能直接调出：
- 按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入SFTP: Show Console回车，所有底层 ssh/sftp 命令和错误输出都会实时打印 - 如果看到
Permission denied: /var/www/myapp/config.php，先 SSH 登上去执行ls -ld /var/www/myapp，确认用户对目录有w权限 - 如果文件名是
测试.py上传后变成???.py，说明服务器 locale 不支持 UTF-8，在sftp-config.json加上"encoding": "utf-8" - 如果大文件上传中途断开，调高
"connect_timeout"和加"keepalive": 60
多人协作时如何避免本地修改覆盖线上配置
默认 upload_on_save 是危险开关，尤其当多人共用同一台服务器时。它不会做任何 diff 或冲突提示，保存即覆盖。
- 开发阶段建议设为
false，改完后手动右键 →SFTP→Upload File，只传当前文件 - 上线前用
SFTP: Browse Server打开远程目录，左键点击文件可直接在 Sublime 中打开只读副本，方便比对 - 真正需要自动同步的场景（如静态资源），用
sync_down_on_open: true+confirm_downloads: true，确保每次打开都拉最新版并弹窗确认 - 永远不要在
remote_path指向/etc或/root这类敏感路径下启用upload_on_save
最麻烦的从来不是配通，而是配通之后忘了关自动上传，结果把本地调试用的数据库密码直接发到生产环境。多看一眼 console 输出，比重装插件省半小时。
