VS Code SFTP 插件用法

下面我按原理 → 基本配置 → 多服务器/多路径 → 切换方式 → 实战建议的顺序，系统讲清楚。

---

一、VS Code SFTP 插件的原理是什么？

1️⃣ 本质

VS Code 的 SFTP 插件本质是：

在本地文件系统和远程服务器之间，通过 SSH/SFTP 协议做文件同步

它并不是“远程开发”，而是：

• 本地：你在 VS Code 编辑文件
• 远程：插件自动或手动把文件 上传/下载
• 通信：通过 SSH（22端口） + SFTP 协议

2️⃣ 关键能力

• 利用 Node.js 的 ssh2 / sftp-client
• 维护一份：
  • 本地目录
  • 远程目录
  • 文件变更记录
• 支持：
  • 上传单个文件
  • 上传整个目录
  • 保存即上传
  • 对比差异（diff）

⚠️ 它不在服务器上运行 VS Code，也不挂载远程文件系统。

---

二、最基础的配置（单服务器）

1️⃣ 安装插件

搜索并安装：

SFTP  
作者：liximomo  

2️⃣ 生成配置文件

在项目根目录：

Ctrl + Shift + P  
→ SFTP: Config  

会生成：

.vscode/sftp.json  

3️⃣ 最简单示例

{  
  "name": "My Server",  
  "host": "1.2.3.4",  
  "protocol": "sftp",  
  "port": 22,  
  "username": "root",  
  "password": "123456",  
  "remotePath": "/var/www/html",  
  "uploadOnSave": true  
}  

✅ 含义说明：

字段	含义
name	服务器名称
host	服务器 IP 或域名
protocol	一般是 sftp
port	SSH 端口
username	SSH 用户
password	密码（推荐换成私钥）
remotePath	远程根目录
uploadOnSave	保存自动上传

---

三、使用 SSH 私钥（强烈推荐）

{  
  "name": "Prod Server",  
  "host": "1.2.3.4",  
  "protocol": "sftp",  
  "port": 22,  
  "username": "deploy",  
  "privateKeyPath": "~/.ssh/id_rsa",  
  "remotePath": "/data/www/project",  
  "uploadOnSave": true  
}  

✅ 更安全
✅ 不用每次输入密码

---

四、多个服务器怎么配置？

✅ 方法一（最常用）：sftp.json 中配置数组

{  
  "profiles": {  
    "dev": {  
      "name": "Dev Server",  
      "host": "10.0.0.10",  
      "username": "root",  
      "password": "dev123",  
      "remotePath": "/var/www/dev",  
      "uploadOnSave": false  
    },  
    "test": {  
      "name": "Test Server",  
      "host": "10.0.0.20",  
      "username": "root",  
      "password": "test123",  
      "remotePath": "/var/www/test",  
      "uploadOnSave": false  
    },  
    "prod": {  
      "name": "Prod Server",  
      "host": "1.2.3.4",  
      "username": "deploy",  
      "privateKeyPath": "~/.ssh/id_rsa",  
      "remotePath": "/data/www/prod",  
      "uploadOnSave": true  
    }  
  },  
  "defaultProfile": "dev"  
}  

---

五、多个不同路径怎么配置？

✅ 场景

• 同一个服务器
• 不同项目
• 不同目录

✅ 方法一：多个 profile 指向同一服务器，不同路径

{  
  "profiles": {  
    "admin": {  
      "host": "1.2.3.4",  
      "username": "root",  
      "remotePath": "/data/www/admin"  
    },  
    "api": {  
      "host": "1.2.3.4",  
      "username": "root",  
      "remotePath": "/data/www/api"  
    },  
    "h5": {  
      "host": "1.2.3.4",  
      "username": "root",  
      "remotePath": "/data/www/h5"  
    }  
  }  
}  

✅ 非常实用
✅ 一台服务器多个项目

---

✅ 方法二：一个项目映射多个远程路径（高级）

{  
  "name": "Multi Path",  
  "host": "1.2.3.4",  
  "username": "root",  
  "remotePath": "/data/www",  
  "context": "dist"  
}  

或者用 uploadConfig（不太常用）

---

六、如何在 VS Code 中切换服务器？

✅ 命令面板切换（最常用）

Ctrl + Shift + P  
→ SFTP: Set Profile  

选择：

dev / test / prod  

当前 profile 会被激活 ✅

---

✅ 查看当前使用的是哪个

• 右下角状态栏
• 会显示当前 SFTP profile 名称

---

七、常用命令（非常重要）

操作	命令
上传当前文件	SFTP: Upload File
上传整个项目	SFTP: Upload Folder
下载远程文件	SFTP: Download File
对比差异	SFTP: Diff with Remote
切换配置	SFTP: Set Profile

---

八、忽略文件（防止误传）

{  
  "ignore": [  
    ".vscode",  
    ".git",  
    "node_modules",  
    "*.log"  
  ]  
}  

✅ 强烈建议配置
✅ 防止误上传敏感文件

---

九、真实开发中的最佳实践 ✅

✅ 1️⃣ 本地 Git + SFTP

• Git 管版本
• SFTP 只负责部署

✅ 2️⃣ 生产环境慎用 uploadOnSave

"uploadOnSave": false  

生产环境建议手动上传

---

✅ 3️⃣ 多项目推荐结构

project-a/  
  .vscode/sftp.json  
project-b/  
  .vscode/sftp.json  

每个项目独立配置

---

十、什么时候不该用 SFTP？

场景	建议
大型项目	rsync / CI
需要远程调试	Remote-SSH
高并发生产	CI/CD

---