使用 VSCode 远程连接 Linux 服务器：详尽教程
在本地用 VSCode 编辑、调试并运行远程 Linux 服务器上的项目，能大幅提升开发效率。本文将手把手教你如何配置并使用 VSCode 的 Remote – SSH 插件，做到像操作本地项目一样流畅地管理远程代码。
一、为什么用 Remote – SSH？
- 统一 IDE：不必在终端和编辑器之间切换，所有操作都在 VSCode 中完成。
- 完整功能：支持语法高亮、智能补全、断点调试、Git 集成、终端、文件搜索等。
- 零延迟编辑：通过 SSH 隧道直接读写远程文件，感受就像本地一样。
二、环境准备
-
本地环境
- 安装最新版本的 Visual Studio Code。
- 在 Windows 上，打开“控制面板”→“程序和功能”→“启用或关闭 Windows 功能”，勾选 OpenSSH 客户端。macOS/Linux 通常已自带 SSH。
-
远程服务器
- 一台可通过 SSH 登录的 Linux 机器（如云服务器或公司内网主机）。
- 确保能从本地用
ssh 用户名@公网IP方式登录。
Tip：推荐给远程主机配置基于密钥的免密登录，省去每次输密码的麻烦。
三、配置免密 SSH 登录（可选但推荐）
-
本地生成密钥对（如果已有可跳过）：
ssh-keygen -t rsa -b 4096回车接受默认路径（~/.ssh/id_rsa）。
-
将公钥上传到服务器：
ssh-copy-id 用户名@远程IP如果没有
ssh-copy-id，可手动追加：cat ~/.ssh/id_rsa.pub | ssh 用户名@远程IP "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys" -
测试：
ssh 用户名@远程IP若无需输入密码即登录，说明配置成功。
四、本地 SSH 配置文件（~/.ssh/config）
为方便管理多台主机，建议在本地 ~/.ssh/config 添加条目，启动 VSCode 时可一键连接：
Host my-remote
HostName 远程IP # 服务器公网 IP 或域名
User 用户名 # 服务器登录用户名
IdentityFile ~/.ssh/id_rsa # 私钥路径
StrictHostKeyChecking no # 首次连接自动信任
UserKnownHostsFile /dev/null # 不在 known_hosts 记录（可选）
保存后，在任意终端执行
ssh my-remote，等同于ssh 用户名@远程IP。
五、安装 VSCode Remote – SSH 插件
- 打开 VSCode 左侧扩展商店（Extensions），搜索并安装 Remote – SSH。
- 安装完成后，左下角会出现一个绿色的 “><” 图标。
六、通过 VSCode 连接远程主机
- 点击左下角的 “><”，选择 Remote-SSH: Connect to Host…。
- 在弹出的主机列表中，选择刚才在
~/.ssh/config中配置的my-remote。 - VSCode 会自动在远程安装并启动一个 VS Code Server，首次连接时会弹出终端显示安装进度。
- 安装完成后，左下角状态栏会切换为
SSH: my-remote，侧边栏展示远程文件系统。
排查技巧
- 如果卡在 “Installing VS Code Server”，可手动登录服务器删掉
~/.vscode-server目录后重试。- 如果出现
garbage at end of line，检查~/.ssh/config是否有多余字符。
七、打开并管理远程项目
-
在 VSCode 菜单栏选择 File → Open Folder…，输入远程路径（如
/home/用户名/project）。 -
选择文件夹后，侧边栏会加载该目录树，支持文件新建、重命名、删除等操作。
-
按 `Ctrl+``（反引号）打开集成终端，直接在远程执行命令：
# 启动后端服务 cd /home/用户名/project/backend go run main.go # 启动前端开发模式 cd /home/用户名/project/web npm install # 一次性安装依赖 npm run dev -- --host 0.0.0.0 --disable-host-check -
远程终端内的所有操作均在服务器上进行，无需额外 SSH 窗口。
八、常见问题及解决
| 问题 | 解决方法 |
|---|---|
无法连接Connection timed out | - 确认服务器公网 IP/端口（默认 22）是否正确- 检查本地和服务器防火墙/安全组是否放通 SSH |
| VS Code Server 安装失败 | - 删除远程 ~/.vscode-server 目录，再重连- 提升 sshd 日志等级，排查错误原因 |
| 侧边栏不显示文件只能看到空白欢迎页 | - 确认已“Open Folder”打开远程项目目录- 在命令面板（F1）运行 Remote-SSH: Refresh Explorer |
前端热更新断开控制台出现 ERR_CONNECTION_TIMED_OUT | - npm run dev 时加上 --host 0.0.0.0，允许外部访问- 检查安全组/防火墙是否放通对应端口（如 9528） |
九、进阶用法
-
SSH 跳板
Host jump HostName 跳板机IP User username IdentityFile ~/.ssh/id_rsa Host my-remote HostName 内网IP User username ProxyJump jump -
端口转发
在~/.ssh/config中添加：Host my-remote LocalForward 9528 localhost:9528 # 本地9528转发至远程9528 -
自定义 Remote – SSH 设置
在 VSCode 设置（settings.json）中添加：{ "remote.SSH.remotePlatform": { "my-remote": "linux" }, "remote.SSH.showLoginTerminal": true }
十、总结
通过本教程，你可以轻松搭建：
- 免密 SSH：更安全、更便捷。
- VSCode Remote – SSH：一键连接、自动部署服务端组件。
- 无缝开发：在本地 IDE 中完成编辑、调试、运行，项目文件实时同步到远程。
掌握了这一整套流程，不论是 Web、Go、Python 还是 Docker 项目，都能在 VSCode 中像本地一样高效开发。希望本文能帮你快速上手远程开发，摆脱“在终端里写代码”的束缚！
— End.
