代码星辰

外观

使用VSCode连接SSH服务器完整指南

约 2876 字大约 10 分钟

VSCodeSSH远程开发开发工具

2025-11-23

VSCode（Visual Studio Code）是微软开发的免费代码编辑器，通过 Remote-SSH 扩展，可以直接连接到远程服务器进行开发，就像在本地编辑代码一样。本文将详细介绍如何使用 VSCode 连接 SSH 服务器。

为什么使用 VSCode Remote-SSH？

✅ 无缝远程开发：直接在远程服务器上编辑、运行和调试代码
✅ 本地体验：享受 VSCode 的所有功能和扩展
✅ 多服务器管理：轻松管理多个远程服务器连接
✅ 文件同步：自动同步文件，无需手动上传下载
✅ 终端集成：内置终端直接连接到远程服务器

前置条件

在开始之前，确保你已经具备：

  • ✅ VSCode 已安装（下载地址）
  • ✅ 远程服务器的 SSH 访问权限
  • ✅ 服务器的 IP 地址、用户名和端口（如果需要）
  • ✅ SSH 密钥或密码（推荐使用密钥认证）

步骤一：安装 Remote-SSH 扩展

方法1：通过扩展市场安装（推荐）

  1. 打开 VSCode
  2. 点击左侧边栏的 扩展 图标（或按 Cmd+Shift+X / Ctrl+Shift+X）
  3. 在搜索框中输入 Remote - SSH
  4. 找到 Remote - SSH（作者：Microsoft），点击 安装

方法2：通过命令行安装

# 使用 VSCode 命令行工具安装
code --install-extension ms-vscode-remote.remote-ssh

方法3：通过远程窗口自动安装

  1. 打开 VSCode
  2. 点击左下角的 打开远程窗口 图标（绿色 >< 图标）
  3. 在弹出的菜单中选择 Connect to Host... 或 New Window...
  4. 选择 SSH 选项
  5. VSCode 会自动检测并提示安装 Remote-SSH 扩展
  6. 点击 安装 即可自动完成安装

这种方式最便捷，当你需要连接远程服务器时，VSCode 会自动引导你安装必要的扩展。

安装相关扩展（可选但推荐）

为了获得更好的远程开发体验，建议同时安装：

  • Remote - SSH: Editing Configuration Files：方便编辑 SSH 配置文件
  • Remote Development：完整的远程开发扩展包（包含 Remote-SSH）

步骤二：配置 SSH 连接

方法1：使用 SSH Config 文件（推荐）

这是最推荐的方式，可以统一管理所有 SSH 连接配置。

创建或编辑 SSH Config 文件

macOS/Linux：

# 编辑 SSH 配置文件
nano ~/.ssh/config
# 或
vim ~/.ssh/config

Windows：

# 在 PowerShell 或 CMD 中
notepad C:\Users\YourUsername\.ssh\config

SSH Config 配置示例

# 基础配置示例
Host myserver
    HostName 192.168.1.100
    User ubuntu
    Port 22
    IdentityFile ~/.ssh/id_rsa

# 使用自定义端口的服务器
Host production
    HostName example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/production_key

# 使用密码认证（不推荐，但支持）
Host testserver
    HostName 192.168.1.200
    User root
    Port 22
    # 不指定 IdentityFile，将使用密码认证

# 使用 .pem 文件的服务器（如 AWS EC2）
Host aws-server
    HostName ec2-xx-xx-xx-xx.compute-1.amazonaws.com
    User ec2-user
    IdentityFile ~/.ssh/aws-key.pem
    IdentitiesOnly yes

配置参数说明：

  • Host：服务器别名（在 VSCode 中显示的名称）
  • HostName：服务器的 IP 地址或域名
  • User：SSH 用户名
  • Port：SSH 端口（默认 22）
  • IdentityFile：私钥文件路径
  • IdentitiesOnly yes：只使用指定的私钥，不尝试其他密钥

设置正确的文件权限（重要！）

macOS/Linux：

# SSH Config 文件权限必须是 600
chmod 600 ~/.ssh/config

# 私钥文件权限必须是 600
chmod 600 ~/.ssh/id_rsa
chmod 600 ~/.ssh/aws-key.pem

# .ssh 目录权限必须是 700
chmod 700 ~/.ssh

Windows： Windows 通常不需要手动设置权限，但确保文件不在共享目录中。

方法2：直接输入连接信息

如果不想配置 SSH Config，也可以直接输入连接信息：

  1. 在 VSCode 中按 F1 或 Cmd+Shift+P / Ctrl+Shift+P
  2. 输入 Remote-SSH: Connect to Host
  3. 选择 + Add New SSH Host...
  4. 输入 SSH 连接命令，例如：
    ssh ubuntu@192.168.1.100
    或
    ssh -i ~/.ssh/key.pem ubuntu@192.168.1.100
  5. 选择保存位置（通常选择第一个：~/.ssh/config）

步骤三：连接到远程服务器

连接步骤

  1. 打开远程连接面板

    • 点击 VSCode 左下角的 绿色连接图标（><）
    • 或按 F1 / Cmd+Shift+P / Ctrl+Shift+P，输入 Remote-SSH: Connect to Host

  2. 选择服务器

    • 如果已配置 SSH Config，会显示所有配置的服务器别名
    • 选择要连接的服务器

  3. 选择平台

    • 首次连接时，VSCode 会询问远程服务器的操作系统类型
    • 选择 Linux、macOS 或 Windows

  4. 输入密码（如果使用密码认证）

    • 如果使用密钥认证且密钥有密码，会提示输入密钥密码
    • 如果使用密码认证，会提示输入服务器密码

  5. 等待连接

    • VSCode 会在远程服务器上安装 VS Code Server
    • 首次连接可能需要几分钟，后续连接会更快

  6. 连接成功

    • 连接成功后，VSCode 左下角会显示远程服务器信息
    • 状态栏会显示 SSH: 服务器别名

连接状态指示

  • 左下角绿色图标：已连接到远程服务器
  • 状态栏显示：SSH: 服务器别名
  • 新窗口标题：显示 [SSH: 服务器别名]

步骤四：在远程服务器上工作

打开远程文件夹

连接成功后：

  1. 点击 文件 → 打开文件夹...（或 Cmd+O / Ctrl+O）
  2. 输入远程服务器上的路径，例如：
    /home/ubuntu/project
/var/www/html
/opt/app
  3. 点击 确定

使用集成终端

  • 打开终端：`Ctrl+``（反引号）或 终端 → 新建终端
  • 终端会自动连接到远程服务器
  • 可以执行所有 Linux 命令

安装扩展

在远程服务器上工作时，某些扩展需要在远程服务器上安装：

  1. 点击扩展图标
  2. 搜索需要的扩展
  3. 点击 在 SSH: 服务器别名 中安装

注意：有些扩展需要在本地和远程都安装，VSCode 会自动提示。

编辑文件

  • 直接在编辑器中打开和编辑远程文件
  • 保存文件会自动同步到远程服务器
  • 支持所有 VSCode 的编辑功能（语法高亮、自动补全、代码格式化等）

常见问题解决

1. 连接超时或失败

问题： 无法连接到服务器，显示超时错误

解决方法：

# 1. 检查网络连接
ping server_ip

# 2. 检查 SSH 服务是否运行
ssh -v username@server_ip

# 3. 检查防火墙设置
# 确保服务器防火墙允许 SSH 端口（默认 22）

# 4. 检查 SSH Config 配置是否正确
cat ~/.ssh/config

# 5. 尝试手动 SSH 连接测试
ssh -i ~/.ssh/key.pem username@server_ip

2. 权限问题（Permission denied）

问题： 连接时提示权限被拒绝

解决方法：

# 1. 检查私钥文件权限（必须是 600）
chmod 600 ~/.ssh/id_rsa
chmod 600 ~/.ssh/config

# 2. 检查 .ssh 目录权限（必须是 700）
chmod 700 ~/.ssh

# 3. 检查服务器上的 authorized_keys 权限
# 在服务器上执行：
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

3. VS Code Server 安装失败

问题： 连接时 VS Code Server 安装失败或很慢

解决方法：

# 1. 检查远程服务器磁盘空间
df -h

# 2. 检查网络连接
# 如果服务器在中国，可能需要配置代理

# 3. 手动下载 VS Code Server
# VSCode 会尝试从 GitHub 下载，如果网络问题可以：
# - 配置代理
# - 使用镜像源
# - 手动下载并上传到服务器

4. 扩展无法在远程使用

问题： 某些扩展在远程服务器上无法使用

解决方法：

  • 某些扩展只支持本地使用（如某些 UI 主题）
  • 检查扩展说明，确认是否支持远程开发
  • 尝试在远程服务器上重新安装扩展

5. 文件同步问题

问题： 文件修改后没有同步到远程服务器

解决方法：

  • VSCode 会自动保存，但可以手动保存：Cmd+S / Ctrl+S
  • 检查文件权限，确保有写入权限
  • 检查磁盘空间是否充足

6. 连接断开频繁

问题： 连接经常断开

解决方法：

在 SSH Config 中添加保持连接的配置：

Host myserver
    HostName 192.168.1.100
    User ubuntu
    ServerAliveInterval 60
    ServerAliveCountMax 3

参数说明：

  • ServerAliveInterval 60：每 60 秒发送一次心跳包
  • ServerAliveCountMax 3：最多发送 3 次心跳包无响应后断开

7. 使用代理连接

如果服务器需要通过代理访问，可以在 SSH Config 中配置：

Host myserver
    HostName 192.168.1.100
    User ubuntu
    ProxyCommand ssh -W %h:%p proxy_server

或使用 HTTP 代理：

Host myserver
    HostName 192.168.1.100
    User ubuntu
    ProxyCommand nc -X 5 -x proxy_host:proxy_port %h %p

实用技巧

1. 多服务器管理

在 SSH Config 中配置多个服务器，可以快速切换：

Host dev
    HostName dev.example.com
    User developer
    IdentityFile ~/.ssh/dev_key

Host staging
    HostName staging.example.com
    User deploy
    IdentityFile ~/.ssh/staging_key

Host production
    HostName prod.example.com
    User deploy
    IdentityFile ~/.ssh/prod_key
    Port 2222

2. 使用跳板机（Bastion Host）

如果需要通过跳板机连接内网服务器：

# 跳板机配置
Host jumpbox
    HostName jumpbox.example.com
    User admin
    IdentityFile ~/.ssh/jumpbox_key

# 内网服务器配置（通过跳板机）
Host internal-server
    HostName 10.0.0.100
    User ubuntu
    IdentityFile ~/.ssh/internal_key
    ProxyJump jumpbox

3. 端口转发

在 SSH Config 中配置本地端口转发：

Host myserver
    HostName 192.168.1.100
    User ubuntu
    LocalForward 8080 localhost:8080
    LocalForward 3306 localhost:3306

这样可以通过 localhost:8080 访问远程服务器的 8080 端口。

4. 使用 VSCode 设置同步

在远程服务器上工作时，可以同步 VSCode 设置：

  1. 安装 Settings Sync 扩展
  2. 登录 GitHub 或 Microsoft 账户
  3. 设置会自动同步到远程服务器

5. 远程调试

VSCode 支持远程调试，可以：

  1. 在远程服务器上运行应用
  2. 在本地 VSCode 中设置断点
  3. 使用调试功能进行远程调试

6. 使用 Git

在远程服务器上可以直接使用 Git：

# 在远程终端中
git clone https://github.com/user/repo.git
git pull
git push

VSCode 的 Git 扩展也会在远程服务器上工作。

7. 快速切换连接

  • 使用 F1 → Remote-SSH: Connect to Host 快速切换服务器
  • 使用 F1 → Remote-SSH: Kill VS Code Server on Host 断开连接

安全建议

🔒 使用密钥认证：避免使用密码认证，使用 SSH 密钥更安全

🔒 保护私钥：确保私钥文件权限正确（600），不要分享私钥

🔒 使用强密码：如果密钥设置了密码，使用强密码

🔒 定期更新：定期更新 VSCode 和 Remote-SSH 扩展

🔒 限制访问：在服务器上配置防火墙，只允许必要的 IP 访问

🔒 使用跳板机：对于生产环境，使用跳板机增加安全层

性能优化

1. 排除不必要的文件

在 VSCode 设置中配置 files.exclude，排除不需要同步的文件：

{
  "files.exclude": {
    "**/node_modules": true,
    "**/.git": true,
    "**/dist": true,
    "**/build": true
  }
}

2. 使用 .vscodeignore

在项目根目录创建 .vscodeignore 文件，排除大文件或临时文件。

3. 优化网络连接

  • 使用稳定的网络连接
  • 如果可能，使用有线网络而不是 Wi-Fi
  • 配置 SSH 连接保持活跃（见上文）

总结

使用 VSCode Remote-SSH 可以极大地提升远程开发体验：

  1. ✅ 安装 Remote-SSH 扩展
  2. ✅ 配置 SSH Config 文件
  3. ✅ 连接到远程服务器
  4. ✅ 在远程服务器上编辑和调试代码
  5. ✅ 使用集成终端执行命令
  6. ✅ 享受本地开发的所有便利

掌握了这些方法，你就可以像在本地一样高效地开发远程项目了！

相关资源：

贡献者

ntzw

更新日志

2025/11/23 20:49
查看所有更新日志
  • e10a0-docs(blog): 添加VSCode连接SSH服务器完整指南于

版权归属：ntzw

许可证：CC0 1.0 通用 (CC0)