upload_on_save设为true却不上传，根本原因是三个硬性前提未满足：项目未绑定、sftp-config.json位置或格式错误、ssh认证链路不通；文件必须在映射目录内，配置须在json根层级，且sublime版本与sftp插件兼容。
upload_on_save 设为 true 后，文件仍不上传？不是插件没装好，而是三个硬性条件缺一不可：项目已绑定、配置文件位置/格式正确、SSH 认证链路通。其他插件（如 FTPSync、sftp3）根本不会响应保存事件，别白费时间调。
为什么 upload_on_save 开关写了却没反应
这不是“开关失灵”，而是触发前提没满足。SFTP 插件只在特定上下文里监听 on_post_save_async 事件，以下任一不成立，就静默跳过：
- 当前编辑的文件**不在右键映射过的项目目录内**——打开桌面一个
index.html，哪怕同级有sftp-config.json，也不会上传 -
sftp-config.json不在项目根目录，或名字写成SFTP-config.json、sftp_config.json、sftp-config.json.bak -
"upload_on_save": true写在了files或sync_down_on_open对象里，而不是 JSON 根层级 - Sublime Text 版本低于
4.4107，或装的是旧版 SFTP（报ImportError: No module named 'urllib2'），实际进程根本没跑起来
sftp-config.json 必须填对的字段和常见错法
右键项目文件夹 → SFTP: Setup Server 自动生成的配置最可靠，但生成后必须人工核对：
-
"host"：只填"example.com"或"192.168.1.100"，不能带sftp://、ssh://，端口走单独的"port": 22 -
"remote_path"：必须是绝对路径，以/开头，结尾加不加/都行（"/var/www/html"✅，"www"❌） -
"ssh_key_file"（ST3）或"private_key"（ST4）：路径写"~/.ssh/id_rsa"即可，但 Linux/macOS 下必须执行chmod 600 ~/.ssh/id_rsa，否则 OpenSSH 拒绝读取 -
"type"：必须是"sftp"，不是"ftp"或"scp"；SFTP 协议走 SSH 端口，FTP 协议走 21 端口，配错就连接超时
上传失败时去哪查真实错误
弹窗提示“Upload failed”太笼统，真正线索藏在输出面板里：
- 按
Ctrl+Shift+P（Mac 为Cmd+Shift+P），输入SFTP: Show Output打开图形化日志面板 - 常见错误原文：
Permission denied (publickey)→ 私钥权限不对或服务器未启用密钥认证；No such file→remote_path目录不存在；Connection timed out→ 默认 3 秒超时太短，加"timeout": 10到配置根层级 - 如果面板空白，说明插件压根没触发上传——回看上一条，检查项目绑定和配置位置
- 想看更底层日志，按
Ctrl+`打开 Sublime 控制台，搜索sftp或error
上传成功但网页打不开？权限和路径拼接是隐形坑
文件传上去了，不代表能被 Web 服务读取。两个常被忽略的点：
- 默认上传权限是
600（仅属主可读写），Nginx/Apache 需要644（文件）或755（目录）。加这一行到配置根层级："default_permissions": "644" - 路径拼接依赖
local_path和remote_path的相对关系。例如："local_path": "src"+"remote_path": "/var/www/html"，改src/js/app.js就会传到/var/www/html/js/app.js。如果没设local_path，则以项目根为基准 - Windows 用户注意：
remote_path用正斜杠/，别用反斜杠\，否则路径解析错位
SFTP: Show Output 面板、确认权限、检查路径、验证 SSH 连通性。
