1. 树莓派 4B 服务端预配置(无头模式)
在连接之前,必须确保树莓派已刷写系统并启用 SSH 服务。推荐使用 Raspberry Pi Imager 工具进行初始化,可避免手动修改配置文件的繁琐步骤 。
| 步骤 | 操作细节 | 关键配置项 |
|---|---|---|
| 系统烧录 | 下载 Raspberry Pi Imager,选择 OS (推荐 Ubuntu Server 或 Raspberry Pi OS) 和存储卡。 | 点击齿轮图标进入"高级选项" |
| 启用 SSH | 在高级选项中勾选"启用 SSH",设置用户名和密码(或导入公钥)。 | Enable SSH: true, Set username/password |
| 网络配置 | 配置 WiFi SSID 和密码,或选择有线网络;设置主机名(Hostname)。 | Configure wireless LAN, Set hostname (如 raspberrypi) |
| 首次启动验证 | 插入 SD 卡启动树莓派,在 Win11 终端使用 ping <hostname>.local 测试连通性。 |
依赖 mDNS 解析 .local 域名 |
若已通过显示器初始化,需手动开启 SSH 服务:
bash
# 在树莓派终端执行
sudo systemctl enable ssh
sudo systemctl start ssh
sudo ufw allow ssh # 若启用了防火墙
2. Windows 11 客户端环境准备
确保 Win11 已安装 OpenSSH 客户端(默认自带)及 VS Code。
- 检查 SSH 客户端 :在 PowerShell 中输入
ssh,若显示帮助信息则无需安装;若提示找不到命令,需在"设置 -> 应用 -> 可选功能"中安装"OpenSSH 客户端" 。 - 安装插件 :打开 VS Code,进入扩展商店(Ctrl+Shift+X),搜索并安装 Remote - SSH (Microsoft 出品) 。
3. VS Code Remote-SSH 连接流程
方案 A:密码认证连接(快速上手)
适用于初次连接或测试环境。
- 点击 VS Code 左下角绿色远程图标,选择 "Connect to Host..."。
- 输入连接命令:
ssh <username>@<hostname>.local(例如:ssh pi@raspberrypi.local)。 - 首次连接会提示指纹确认,选择 Continue。
- 输入树莓派用户密码。
- 选择目标平台为 Linux(VS Code 会自动检测,若未检测到需手动指定)。
- 等待服务端安装 VS Code Server 组件,完成后即可在左侧资源管理器中看到树莓派文件系统。
方案 B:密钥认证连接(推荐生产环境)
为提高安全性并实现免密登录,建议配置 SSH 密钥 。
Step 1: 生成密钥对(Win11 PowerShell)
powershell
# 生成 RSA 4096 位密钥,按提示保存路径(默认 ~/.ssh/id_rsa)
ssh-keygen -t rsa -b 4096 -C "win11_vscode_key"
Step 2: 复制公钥到树莓派
powershell
# 将公钥上传至树莓派 authorized_keys 文件
# 注意:若 mDNS 解析失败,请替换为树莓派实际 IP 地址
ssh-copy-id pi@raspberrypi.local
若 ssh-copy-id 不可用,可手动将 C:\Users\<你的用户名>\.ssh\id_rsa.pub 的内容追加到树莓派 ~/.ssh/authorized_keys 文件中 。
Step 3: 配置 SSH Config 文件
编辑 Win11 的 ~/.ssh/config 文件(可通过 VS Code 直接打开),添加以下配置以简化连接:
ssh
Host rpi4b
HostName raspberrypi.local
User pi
IdentityFile C:/Users/<你的用户名>/.ssh/id_rsa # 保持连接活跃,防止超时断开
ServerAliveInterval 60
# 启用压缩,提升低带宽下的传输效率
Compression yes
Step 4: 发起连接
在 VS Code 远程连接列表中选择 rpi4b,即可实现免密秒连。
4. 远程开发环境配置与调试
连接成功后,VS Code 的运行上下文已切换至树莓派。
- 解释器绑定 :打开 Python 项目,按下
Ctrl+Shift+P,选择 Python: Select Interpreter ,VS Code 会自动扫描树莓派上的 Python 路径(如/usr/bin/python3或虚拟环境路径)。 - 扩展同步:部分本地扩展(如 Pylance, C++)需在远程端重新安装。VS Code 会提示"Install extensions on SSH: rpi4b",点击确认即可 。
- 端口转发 :若需在浏览器访问树莓派运行的 Web 服务(如 ROS 节点、Flask 应用),在 VS Code 底部面板点击 Ports -> Forward a Port ,输入端口号(如
8080),即可通过localhost:8080在 Win11 浏览器访问 。
5. 常见问题排查
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| Connection timed out | mDNS 解析失败或 IP 变更 | 改用树莓派固定 IP 地址连接;或在路由器绑定 MAC 地址 。 |
| Permission denied (publickey) | 密钥权限错误或未授权 | 检查树莓派 ~/.ssh 目录权限应为 700,authorized_keys 为 600 。 |
| 中文乱码 | 字符集不匹配 | 在树莓派执行 sudo localectl setlocale LANG=zh_CN.UTF-8 并重启 。 |
| Known hosts 冲突 | 重装系统后指纹变化 | 在 Win11 终端执行 ssh-keygen -R raspberrypi.local 清除旧指纹 。 |