外观
使用VSCode连接SSH服务器完整指南
VSCode(Visual Studio Code)是微软开发的免费代码编辑器,通过 Remote-SSH 扩展,可以直接连接到远程服务器进行开发,就像在本地编辑代码一样。本文将详细介绍如何使用 VSCode 连接 SSH 服务器。
为什么使用 VSCode Remote-SSH?
✅ 无缝远程开发:直接在远程服务器上编辑、运行和调试代码
✅ 本地体验:享受 VSCode 的所有功能和扩展
✅ 多服务器管理:轻松管理多个远程服务器连接
✅ 文件同步:自动同步文件,无需手动上传下载
✅ 终端集成:内置终端直接连接到远程服务器
前置条件
在开始之前,确保你已经具备:
- ✅ VSCode 已安装(下载地址)
- ✅ 远程服务器的 SSH 访问权限
- ✅ 服务器的 IP 地址、用户名和端口(如果需要)
- ✅ SSH 密钥或密码(推荐使用密钥认证)
步骤一:安装 Remote-SSH 扩展
方法1:通过扩展市场安装(推荐)
- 打开 VSCode
- 点击左侧边栏的 扩展 图标(或按
Cmd+Shift+X/Ctrl+Shift+X) - 在搜索框中输入
Remote - SSH - 找到 Remote - SSH(作者:Microsoft),点击 安装
方法2:通过命令行安装
# 使用 VSCode 命令行工具安装
code --install-extension ms-vscode-remote.remote-ssh方法3:通过远程窗口自动安装
- 打开 VSCode
- 点击左下角的 打开远程窗口 图标(绿色
><图标) - 在弹出的菜单中选择 Connect to Host... 或 New Window...
- 选择 SSH 选项
- VSCode 会自动检测并提示安装 Remote-SSH 扩展
- 点击 安装 即可自动完成安装
这种方式最便捷,当你需要连接远程服务器时,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/configWindows:
# 在 PowerShell 或 CMD 中
notepad C:\Users\YourUsername\.ssh\configSSH 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 ~/.sshWindows: Windows 通常不需要手动设置权限,但确保文件不在共享目录中。
方法2:直接输入连接信息
如果不想配置 SSH Config,也可以直接输入连接信息:
- 在 VSCode 中按
F1或Cmd+Shift+P/Ctrl+Shift+P - 输入
Remote-SSH: Connect to Host - 选择
+ Add New SSH Host... - 输入 SSH 连接命令,例如:或
ssh ubuntu@192.168.1.100ssh -i ~/.ssh/key.pem ubuntu@192.168.1.100 - 选择保存位置(通常选择第一个:
~/.ssh/config)
步骤三:连接到远程服务器
连接步骤
打开远程连接面板
- 点击 VSCode 左下角的 绿色连接图标(
><) - 或按
F1/Cmd+Shift+P/Ctrl+Shift+P,输入Remote-SSH: Connect to Host
- 点击 VSCode 左下角的 绿色连接图标(
选择服务器
- 如果已配置 SSH Config,会显示所有配置的服务器别名
- 选择要连接的服务器
选择平台
- 首次连接时,VSCode 会询问远程服务器的操作系统类型
- 选择
Linux、macOS或Windows
输入密码(如果使用密码认证)
- 如果使用密钥认证且密钥有密码,会提示输入密钥密码
- 如果使用密码认证,会提示输入服务器密码
等待连接
- VSCode 会在远程服务器上安装 VS Code Server
- 首次连接可能需要几分钟,后续连接会更快
连接成功
- 连接成功后,VSCode 左下角会显示远程服务器信息
- 状态栏会显示
SSH: 服务器别名
连接状态指示
- 左下角绿色图标:已连接到远程服务器
- 状态栏显示:
SSH: 服务器别名 - 新窗口标题:显示
[SSH: 服务器别名]
步骤四:在远程服务器上工作
打开远程文件夹
连接成功后:
- 点击 文件 → 打开文件夹...(或
Cmd+O/Ctrl+O) - 输入远程服务器上的路径,例如:
/home/ubuntu/project /var/www/html /opt/app - 点击 确定
使用集成终端
- 打开终端:`Ctrl+``(反引号)或 终端 → 新建终端
- 终端会自动连接到远程服务器
- 可以执行所有 Linux 命令
安装扩展
在远程服务器上工作时,某些扩展需要在远程服务器上安装:
- 点击扩展图标
- 搜索需要的扩展
- 点击 在 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_ip2. 权限问题(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 ~/.ssh3. 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 22222. 使用跳板机(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 jumpbox3. 端口转发
在 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 设置:
- 安装 Settings Sync 扩展
- 登录 GitHub 或 Microsoft 账户
- 设置会自动同步到远程服务器
5. 远程调试
VSCode 支持远程调试,可以:
- 在远程服务器上运行应用
- 在本地 VSCode 中设置断点
- 使用调试功能进行远程调试
6. 使用 Git
在远程服务器上可以直接使用 Git:
# 在远程终端中
git clone https://github.com/user/repo.git
git pull
git pushVSCode 的 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 可以极大地提升远程开发体验:
- ✅ 安装 Remote-SSH 扩展
- ✅ 配置 SSH Config 文件
- ✅ 连接到远程服务器
- ✅ 在远程服务器上编辑和调试代码
- ✅ 使用集成终端执行命令
- ✅ 享受本地开发的所有便利
掌握了这些方法,你就可以像在本地一样高效地开发远程项目了!
相关资源:
贡献者
更新日志
2025/11/23 20:49
查看所有更新日志
e10a0-docs(blog): 添加VSCode连接SSH服务器完整指南于
版权所有
版权归属:ntzw
许可证:CC0 1.0 通用 (CC0)
