VSCode SFTP插件实现本地代码与远程服务器同步

在日常开发中，我们经常需要在本地编写代码，然后将代码同步到远程服务器进行测试或部署。传统的方式是使用 FileZilla、WinSCP 等第三方工具手动上传文件，这种方式不仅繁琐，而且容易出错。VSCode 的 SFTP 插件可以帮助我们实现本地代码与远程服务器的自动同步，大大提高开发效率。

应用场景

SFTP 插件适用于以下场景：

本地开发，远程调试：在本地编写代码，保存后自动同步到远程服务器，无需手动上传
快速部署：本地测试通过后，一键同步到生产环境服务器
多服务器管理：同时管理多个远程服务器，快速切换上传目标
团队协作：统一开发环境，确保代码在服务器端运行一致

安装插件

打开 VSCode，按下快捷键 Ctrl + Shift + X 打开扩展商店，搜索 sftp，找到名为 SFTP 的插件（作者：Natizyskunk），这是安装量最高、最受欢迎的 SFTP 插件。点击安装即可。

Responsive Image

安装完成后，VSCode 会在侧边栏显示 SFTP 图标，表示插件已成功安装。

配置插件

生成配置文件

插件安装完成后，我们需要为当前项目创建配置文件。有两种方式：

方式一：使用命令面板

按下快捷键 Ctrl + Shift + P 打开命令面板
输入 SFTP: Config 并回车
VSCode 会在当前工作区的 .vscode 文件夹下自动生成 sftp.json 配置文件

方式二：右键菜单

在 VSCode 资源管理器中，右键点击项目文件夹
选择 SFTP: Config
同样会生成 sftp.json 配置文件

基础配置示例

打开生成的 sftp.json 文件，你会看到一个默认的配置模板。下面是一个基础配置示例：

{
    "name": "我的服务器",
    "host": "192.168.1.100",
    "protocol": "sftp",
    "port": 22,
    "username": "root",
    "password": "your_password",
    "remotePath": "/var/www/project",
    "uploadOnSave": true,
    "useTempFile": false,
    "openSsh": false
}

完整配置示例

下面是一个包含更多选项的完整配置示例：

{
    "name": "生产环境服务器",
    "host": "192.168.1.100",
    "protocol": "sftp",
    "port": 22,
    "username": "deployer",
    "password": "your_password",
    "remotePath": "/home/deployer/project",
    "context": "./",
    "uploadOnSave": true,
    "useTempFile": false,
    "openSsh": false,
    "downloadOnOpen": false,
    "ignore": [
        ".vscode",
        ".git",
        ".DS_Store",
        "node_modules",
        "*.log",
        "*.tmp"
    ],
    "watcher": {
        "files": "**/*",
        "autoUpload": true,
        "autoDelete": false
    },
    "syncOption": {
        "delete": false,
        "skipCreate": false,
        "ignoreExisting": false,
        "update": true
    },
    "sshConfigPath": null,
    "concurrency": 4
}

配置参数详解

连接配置参数

参数	类型	说明	示例
`name`	String	配置名称，用于区分多个服务器配置	`"生产环境"`
`host`	String	服务器 IP 地址或域名（必填）	`"192.168.1.100"`
`port`	Number	端口号，SFTP 默认 22，FTP 默认 21	`22`
`protocol`	String	传输协议，可选 `sftp` 或 `ftp`	`"sftp"`
`username`	String	登录用户名（必填）	`"root"`
`password`	String	登录密码	`"your_password"`

认证方式参数

SFTP 插件支持三种认证方式：

1. 密码认证（最简单）

{
    "username": "root",
    "password": "your_password"
}

2. 密钥认证（推荐）

{
    "username": "root",
    "privateKeyPath": "C:\\Users\\YourName\\.ssh\\id_rsa",
    "passphrase": "密钥密码（如果有的话）"
}

密钥文件路径说明：

Windows: C:\\Users\\YourName\\.ssh\\id_rsa 或 ~/.ssh/id_rsa
Linux/Mac: ~/.ssh/id_rsa
支持 OpenSSH 格式和 PPK 格式的密钥

3. SSH Config 配置（高级）

如果你已经配置了 SSH config 文件，可以直接引用：

{
    "sshConfigPath": "~/.ssh/config",
    "host": "myserver"
}

对应的 SSH config 文件内容：

Host myserver
    HostName 192.168.1.100
    User deployer
    Port 22
    IdentityFile ~/.ssh/id_rsa

路径配置参数

参数	类型	说明	示例
`remotePath`	String	远程服务器的目标路径（必填）	`"/var/www/project"`
`context`	String	本地项目的相对路径，默认为 `./`	`"./src"`

路径配置说明：

假设本地项目结构如下：

project/
├── src/
│   ├── index.js
│   └── utils.js
├── tests/
└── .vscode/
    └── sftp.json

如果 context 为 "./" 且 remotePath 为 "/var/www/project"，则 src/index.js 会上传到 /var/www/project/src/index.js
如果 context 为 "./src" 且 remotePath 为 "/var/www/project"，则 src/index.js 会上传到 /var/www/project/index.js

自动同步参数

参数	类型	说明	默认值
`uploadOnSave`	Boolean	保存文件时自动上传	`false`
`downloadOnOpen`	Boolean	打开文件时自动下载最新版本	`false`
`useTempFile`	Boolean	上传时使用临时文件（避免覆盖）	`false`

最佳实践建议：

开发环境：设置 uploadOnSave: true，方便快速同步
生产环境：设置 uploadOnSave: false，避免误操作

忽略文件配置

ignore 参数用于指定哪些文件或文件夹不需要同步，支持 glob 模式：

{
    "ignore": [
        "**/.vscode/**",
        "**/.git/**",
        "**/.DS_Store",
        "**/node_modules/**",
        "**/*.log",
        "**/*.tmp",
        "**/dist/**",
        "**/coverage/**"
    ]
}

常用忽略模式：

**/.git/**：忽略 Git 版本控制文件
**/node_modules/**：忽略 Node.js 依赖包
**/*.log：忽略所有日志文件
**/dist/**：忽略构建输出目录

监听器配置（Watcher）

监听器可以监控文件变化并自动执行同步操作：

{
    "watcher": {
        "files": "**/*",
        "autoUpload": true,
        "autoDelete": false
    }
}

参数	类型	说明	默认值
`files`	String	监听的文件模式（glob）	`false`
`autoUpload`	Boolean	文件变化时自动上传	`false`
`autoDelete`	Boolean	本地删除文件时自动删除远程文件	`false`

注意事项：

autoDelete: true 可能导致误删除，请谨慎使用
监听器会持续运行，可能影响性能，建议按需启用

同步选项（Sync Option）

syncOption 用于配置手动同步时的行为：

{
    "syncOption": {
        "delete": false,
        "skipCreate": false,
        "ignoreExisting": false,
        "update": true
    }
}

参数	类型	说明
`delete`	Boolean	删除远程服务器上多余的文件
`skipCreate`	Boolean	跳过创建新文件
`ignoreExisting`	Boolean	忽略已存在的文件
`update`	Boolean	更新已修改的文件

性能优化参数

参数	类型	说明	默认值
`concurrency`	Number	并发上传的文件数量	`4`
`connectTimeout`	Number	连接超时时间（毫秒）	`10000`
`keepalive`	Number	保持连接的间隔时间（毫秒）	`10000`

{
    "concurrency": 8,
    "connectTimeout": 15000,
    "keepalive": 5000
}

性能优化建议：

网络环境好时，可以增加 concurrency 提高上传速度
网络不稳定时，增加 connectTimeout 避免连接超时
频繁操作时，减小 keepalive 保持连接活跃

插件使用

常用操作

安装并配置好插件后，可以通过以下方式使用：

1. 上传文件或文件夹

方式一：右键菜单

在资源管理器中右键点击文件或文件夹
选择 Upload 上传到服务器

方式二：命令面板

按 Ctrl + Shift + P 打开命令面板
输入 SFTP: Upload 并选择相应的命令

2. 下载文件或文件夹

右键点击文件或文件夹
选择 Download 从服务器下载

3. 同步操作

同步本地到远程：

命令面板输入 SFTP: Sync Local -> Remote
将本地所有文件同步到服务器

同步远程到本地：

命令面板输入 SFTP: Sync Remote -> Local
将服务器文件同步到本地

双向同步：

命令面板输入 SFTP: Sync Both Directions
根据文件修改时间自动判断同步方向

4. 对比文件差异

右键点击文件
选择 Diff with Remote
VSCode 会显示本地文件和远程文件的差异

5. 列出远程文件

命令面板输入 SFTP: List
可以浏览远程服务器的文件目录

完整命令列表

按 Ctrl + Shift + P 打开命令面板，输入 SFTP 可以看到所有可用命令：

命令	说明
`SFTP: Config`	创建或编辑配置文件
`SFTP: Upload`	上传当前文件
`SFTP: Upload Folder`	上传整个文件夹
`SFTP: Download`	下载当前文件
`SFTP: Download Folder`	下载整个文件夹
`SFTP: Sync Local -> Remote`	本地同步到远程
`SFTP: Sync Remote -> Local`	远程同步到本地
`SFTP: Sync Both Directions`	双向同步
`SFTP: Diff with Remote`	对比本地和远程文件
`SFTP: List`	列出远程目录
`SFTP: List All`	列出所有配置的服务器
`SFTP: Delete`	删除远程文件

多服务器配置

在实际开发中，我们可能需要同时管理开发环境、测试环境和生产环境多个服务器。SFTP 插件支持在一个配置文件中配置多个服务器。

配置多个服务器

在 sftp.json 中使用数组格式配置多个服务器：

[
    {
        "name": "开发环境",
        "host": "192.168.1.101",
        "port": 22,
        "username": "developer",
        "password": "dev_password",
        "protocol": "sftp",
        "remotePath": "/home/developer/project",
        "uploadOnSave": true,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**"
        ]
    },
    {
        "name": "测试环境",
        "host": "192.168.1.102",
        "port": 22,
        "username": "tester",
        "password": "test_password",
        "protocol": "sftp",
        "remotePath": "/var/www/test",
        "uploadOnSave": false,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**"
        ]
    },
    {
        "name": "生产环境",
        "host": "192.168.1.103",
        "port": 22,
        "username": "deployer",
        "privateKeyPath": "~/.ssh/production_key",
        "protocol": "sftp",
        "remotePath": "/var/www/production",
        "uploadOnSave": false,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**",
            "*.log"
        ]
    }
]

切换服务器

配置多个服务器后，每次执行上传、下载等操作时，VSCode 会弹出选择框，让你选择目标服务器。

也可以通过命令面板 SFTP: List All 查看所有配置的服务器。

最佳实践

1. 安全配置建议

不要将密码明文写入配置文件：

方案一：使用环境变量

{
    "username": "${env.SFTP_USER}",
    "password": "${env.SFTP_PASSWORD}"
}

方案二：使用密钥认证（推荐）

{
    "username": "deployer",
    "privateKeyPath": "~/.ssh/id_rsa"
}

将配置文件加入 .gitignore：

.vscode/sftp.json

如果需要团队共享配置，可以创建一个 sftp.json.example 模板文件，将敏感信息替换为占位符：

{
    "name": "示例配置",
    "host": "your_server_ip",
    "username": "your_username",
    "password": "your_password",
    "remotePath": "/path/to/project"
}

2. 工作流建议

开发阶段：

{
    "uploadOnSave": true,
    "downloadOnOpen": false,
    "watcher": {
        "autoUpload": true
    }
}

部署阶段：

{
    "uploadOnSave": false,
    "syncOption": {
        "update": true,
        "delete": false
    }
}

3. 团队协作建议

为团队创建统一的配置模板：

{
    "name": "团队开发服务器",
    "host": "${env.DEV_SERVER}",
    "username": "${env.DEV_USER}",
    "password": "${env.DEV_PASSWORD}",
    "remotePath": "/home/${env.DEV_USER}/project",
    "uploadOnSave": true,
    "ignore": [
        ".vscode/**",
        ".git/**",
        ".env",
        "node_modules/**",
        "*.log"
    ]
}

团队成员在本地创建 .env 文件配置自己的环境变量即可。

4. 性能优化建议

对于大型项目，建议优化以下配置：

{
    "concurrency": 8,
    "ignore": [
        "node_modules/**",
        "dist/**",
        "build/**",
        ".git/**",
        "**/*.log"
    ],
    "syncOption": {
        "update": true
    }
}

常见问题

1. 连接超时

**问题：**上传文件时提示连接超时。

解决方案：

检查服务器 IP 和端口是否正确
检查防火墙是否开放对应端口
增加 connectTimeout 参数：
```
{
    "connectTimeout": 30000
}
```

2. 权限不足

**问题：**上传文件提示 Permission denied。

解决方案：

确认登录用户对目标目录有写权限
在服务器上执行：chmod 755 /target/path
或切换到有权限的用户

3. 密钥认证失败

**问题：**使用密钥登录时提示认证失败。

解决方案：

确认密钥文件路径正确
确认密钥文件权限：chmod 600 ~/.ssh/id_rsa
如果密钥有密码，需要配置 passphrase
Windows 用户注意路径格式：C:\\Users\\Name\\.ssh\\id_rsa

4. 文件同步冲突

**问题：**本地和远程文件都被修改，不知道以哪个为准。

解决方案：

使用 Diff with Remote 对比差异
手动合并代码后再上传
使用版本控制工具如 Git 管理代码

5. 上传速度慢

**问题：**上传大量文件时速度很慢。

解决方案：

增加并发数："concurrency": 10
完善 ignore 配置，避免上传不必要的文件
使用 Sync Local -> Remote 而不是 Upload Folder

应用场景#

安装插件#

配置插件#

生成配置文件#

基础配置示例#

完整配置示例#

配置参数详解#

连接配置参数#

认证方式参数#

1. 密码认证（最简单）#

2. 密钥认证（推荐）#

3. SSH Config 配置（高级）#

路径配置参数#

自动同步参数#

忽略文件配置#

监听器配置（Watcher）#

同步选项（Sync Option）#

性能优化参数#

插件使用#

常用操作#

1. 上传文件或文件夹#

2. 下载文件或文件夹#

3. 同步操作#

4. 对比文件差异#

5. 列出远程文件#

完整命令列表#

多服务器配置#

配置多个服务器#

切换服务器#

最佳实践#

1. 安全配置建议#

2. 工作流建议#

3. 团队协作建议#

4. 性能优化建议#

常见问题#

1. 连接超时#

2. 权限不足#

3. 密钥认证失败#

4. 文件同步冲突#

5. 上传速度慢#

参考资料#

应用场景

安装插件

配置插件

生成配置文件

基础配置示例

完整配置示例

配置参数详解

连接配置参数

认证方式参数

1. 密码认证（最简单）

2. 密钥认证（推荐）

3. SSH Config 配置（高级）

路径配置参数

自动同步参数

忽略文件配置

监听器配置（Watcher）

同步选项（Sync Option）

性能优化参数

插件使用

常用操作

1. 上传文件或文件夹

2. 下载文件或文件夹

3. 同步操作

4. 对比文件差异

5. 列出远程文件

完整命令列表

多服务器配置

配置多个服务器

切换服务器

最佳实践

1. 安全配置建议

2. 工作流建议

3. 团队协作建议

4. 性能优化建议

常见问题

1. 连接超时

2. 权限不足

3. 密钥认证失败

4. 文件同步冲突

5. 上传速度慢

参考资料