VS Code 远程 SSH 连接树莓派实操指南（附常见问题解决方案）

原创于 2026-03-28 21:03:33 发布 · 756 阅读

15 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#ssh #运维

本文基于实际实操，详细介绍 VS Code 通过 SSH 远程连接树莓派的完整流程，包含前期准备、核心操作步骤、连接后实用操作，同时梳理实操过程中出现的常见问题及解决方案，适用于树莓派远程开发入门人员，可直接作为实操参考手册。

实操环境说明，确保操作兼容性：

树莓派：树莓派4B，搭载 Raspbian 11 系统，已完成网络配置及基础初始化
电脑端：Windows 10 及以上操作系统，VS Code 为最新稳定版（已提前安装）
网络环境：树莓派与电脑需处于同一局域网（关键前提，直接影响连接成功率）

一、前期准备（必做步骤）

远程 SSH 连接前，需完成树莓派端 SSH 服务配置及电脑端 VS Code 插件安装，二者缺一不可，否则会导致连接失败。

1. 树莓派端：SSH 服务开启与 IP 地址查询

树莓派默认关闭 SSH 服务，需手动开启，以下提供两种实操可行的开启方式，可根据硬件条件选择。

方式1：命令行开启（适用于已外接显示器/远程桌面的场景）

通过树莓派终端输入以下命令，完成 SSH 服务的开机自启与立即启动（注意命令权限，需添加 sudo 前缀）：

# 设为开机自启 SSH 服务

sudo systemctl enable ssh

# 立即启动 SSH 服务

sudo systemctl start ssh

SSH 服务启动后，输入ifconfig 命令查询树莓派局域网 IP 地址，定位 wlan0 字段下 inet 后的IP地址，记录备用（后续连接需频繁使用）。

ifconfig

方式2：无显示器开启（适用于无外接显示设备的场景）

该方式通过 SD 卡配置实现 SSH 自动开启，具体步骤如下：

将树莓派 SD 卡插入电脑，打开 SD 卡根目录（boot 分区）；
在根目录下新建空白文件，命名为 ssh（无后缀，后缀错误会导致配置失效）；
将 SD 卡插回树莓派并启动，SSH 服务将自动开启；
通过路由器管理后台，查询树莓派对应的局域网 IP 地址。

2. 电脑端：VS Code 及 SSH 插件安装

若电脑未安装 VS Code，需先访问官方网站（https://code.visualstudio.com/）下载最新稳定版，安装过程默认下一步即可，无需额外配置。

VS Code 安装完成后，安装 SSH 远程连接插件，具体步骤如下：

打开 VS Code，点击左侧「扩展」图标（快捷键：Ctrl+Shift+X）；
在搜索框输入 Remote - SSH（两个都要下载），选择微软官方插件（图标为双电脑+箭头），避免安装非官方插件导致功能异常；
点击「安装」，安装完成后重启 VS Code，确保插件生效。

插件生效后，VS Code 左侧将出现「远程资源管理器」图标（电脑屏幕样式），作为后续 SSH 连接的入口。

二、VS Code 远程 SSH 连接树莓派（核心步骤）

前期准备完成后，按照以下步骤完成 SSH 远程连接，操作流程简洁，需注意参数输入的准确性。

步骤1：添加 SSH 主机

打开 VS Code，点击左侧「远程资源管理器」；
点击顶部「+」号（添加 SSH 主机），弹出命令输入框；
输入 SSH 连接命令，格式为：pi@树莓派IP地址（pi 为树莓派默认用户名，默认密码为 raspberry）；
示例：pi@192.168.0.7，输入完成后按回车确认。

步骤2：选择配置文件保存路径

输入连接命令后，弹出配置文件保存路径选择窗口，建议选择默认路径（C:\Users\用户名\.ssh\config），点击「确定」即可，该路径用于保存树莓派连接信息，便于后续快速连接。

配置文件保存后，后续再次连接时，无需重复输入 IP 地址，直接在远程资源管理器中选择对应主机即可。

步骤3：建立 SSH 远程连接

远程资源管理器中显示已添加的 SSH 主机（格式：pi@IP地址）；
右键点击该主机，选择「连接到主机」（或点击主机右侧「→」箭头）（无线连接需先开启树莓派，等待较长时间）；
弹出新的 VS Code 窗口，提示输入树莓派密码（默认密码 raspberry，输入时不显示明文，输入完成后按回车）；
等待 1-2 秒，VS Code 底部显示「SSH: 树莓派IP地址」，即为连接成功。

三、连接成功后实用操作

SSH 连接成功后，可通过 VS Code 直接对树莓派进行远程操作，以下为常用实操功能，满足日常开发需求。

1. 远程终端操作

点击 VS Code 顶部「终端」→「新建终端」，自动打开树莓派远程终端，输入 Linux 命令即可执行对应操作（如 ls 查看目录、sudo apt update 更新软件源），与直接操作树莓派终端效果一致。

2. 远程文件编辑

点击 VS Code 顶部「文件」→「打开文件夹」，选择树莓派上的目标文件夹（如 /home/pi 目录），即可直接在 VS Code 中新建、编辑文件，无需通过 U 盘等设备进行文件传输，提升开发效率。

示例：新建 test.py 文件，编写 Python 代码后，在远程终端输入 python3 test.py 即可运行，实现远程开发与调试。

3. 断开 SSH 连接

断开连接操作简单：点击 VS Code 底部「SSH: 树莓派IP地址」，在弹出的菜单中选择「关闭远程连接」即可，下次连接可直接调用保存的主机配置。

四、常见问题及解决方案（实操实测）

结合实操过程中出现的问题，梳理4类高频报错及对应解决方案，均经过实测验证，可直接用于问题排查。

问题1：连接超时（报错：Connection timed out）

核心原因：树莓派与电脑未处于同一局域网，或 IP 地址输入错误。

解决方案：

确认树莓派与电脑连接同一 WiFi/路由器，确保网络环境一致；
重新通过 ifconfig 命令查询树莓派 IP，核对输入的 IP 地址，避免位数错误。

问题2：权限拒绝（报错：Permission denied）

核心原因：树莓派密码输入错误，或密码区分大小写错误。

解决方案：

树莓派默认密码为 raspberry，输入时注意区分大小写，避免输入错误；
若已修改 pi 用户密码，需输入修改后的密码进行连接。

问题3：无法找到 Remote - SSH 插件

核心原因：VS Code 版本过低，或插件搜索关键词输入错误。

解决方案：

将 VS Code 更新至最新稳定版，确保插件兼容性；
搜索时输入完整关键词「Remote - SSH」，注意中间空格，避免输入错误。

问题4：SSH 服务开启后仍无法连接

核心原因：树莓派防火墙拦截 SSH 默认端口（22端口）。

解决方案：在树莓派终端输入以下命令，开放 22 端口，开放后重启 SSH 服务即可正常连接：

sudo ufw allow 22

五、实操总结

VS Code 远程 SSH 连接树莓派的核心流程为：开启树莓派 SSH 服务 → 安装 VS Code Remote - SSH 插件 → 配置 SSH 主机并建立连接，整个流程操作简洁，关键在于确保网络环境一致、命令及参数输入准确。

通过远程连接，可实现树莓派无外接显示器、键盘的远程开发，大幅提升开发便捷性，适用于各类树莓派远程开发场景。本文梳理的常见问题及解决方案，可有效规避实操中的各类报错，助力快速完成连接配置。

后续可基于该远程连接，开展树莓派相关进阶操作（如 Ollama 模型部署等），相关实操将持续更新。若在操作过程中遇到其他问题，可通过评论区交流排查。