VSCode Remote-SSH连接树莓派：远程开发配置实战指南

做嵌入式开发或者折腾树莓派的人，一定都经历过这样的尴尬：把SD卡拔下来插到电脑上改文件，改完再插回派上，来回折腾半天，效率极低。如果树莓派连着显示器，体验还能好一点，但真正干活的时候，尤其是写Python或者编译C++，在树莓派上装个桌面版VSCode，跑起来那个卡顿感，说实话有点影响心情。

后来我彻底切换到VSCode Remote-SSH这条路上，才真正把树莓派当成一台“远程服务器”来用。本地的VSCode界面依然流畅，代码却是在树莓派上实时运行，编辑文件、跑脚本、看日志、调试程序全部在一个窗口里完成。这篇文章就把我实际配置的过程、踩过的坑、以及一些优化技巧完整整理出来，希望能帮你少走弯路。

1. 准备工作：软件、硬件与网络环境

1.1 VSCode与Remote-SSH扩展的安装

远程开发的第一步，是在本地电脑上装好VSCode。无论你是Windows、macOS还是Linux，VSCode都有对应的安装包，直接在官网下载对应版本，一路默认安装即可。如果已经装过旧版本，建议升级到最新版本，因为Remote-SSH这类扩展对VSCode版本有隐性的兼容要求，版本过旧容易出现一些莫名其妙的报错。

安装完成后，左侧扩展商店搜索“Remote - SSH”，那个微软官方发布的扩展就是我们要的东西。安装完成后，VSCode左下角会出现一个绿色的连接图标，这个图标就是整个远程开发的入口。值得一提的是，这个扩展其实是一个扩展包，它会自动安装配套的Remote - SSH: Editing Configuration Files等辅助扩展，所以不需要手动一个一个装。

VSCode安装之后的界面语言问题也顺便说一下，如果你习惯中文界面，可以在商店搜索“Chinese Language Pack”安装，然后重启VSCode。不过对于后续的终端操作和配置文件，建议还是保留英文习惯，日志和报错信息用英文排查起来会准确很多。

1.2 树莓派系统烧录与初始化

树莓派端，我推荐使用Raspberry Pi OS，也就是以前的Raspbian。官网提供了Raspberry Pi Imager烧录工具，把系统镜像写入SD卡。这里有一个非常重要的细节：烧录系统时，Imager工具会弹出高级设置选项，在这个界面里最好提前做好三件事。

第一，开启SSH服务。如果不提前开启，树莓派首次启动后默认不会运行SSH服务，无屏模式（Headless）下你就没辙了。第二，设置用户名和密码。默认用户是“pi”，密码是“raspberry”，这个默认组合太危险了，尤其当你的树莓派暴露在局域网内，别人扫到SSH端口就能尝试登录。第三，配置Wi-Fi。把你要连接的Wi-Fi名称和密码提前填进去，树莓派启动后就会自动联网，省掉插网线的麻烦。

如果你是老手，手头已经有一块跑着其他系统的树莓派SD卡，也可以用另一种方式开启SSH：在SD卡的boot分区（Windows下能直接读到的那个小分区）里新建一个名为“ssh”的空文件，系统启动后检测到该文件就会自动启用SSH服务。这个方法在早期的树莓派系统上非常管用。

1.3 记录树莓派的IP地址

连接树莓派之前，得先知道它的IP。最省事的方法是在路由器后台查看DHCP客户端列表，找到主机名类似“raspberrypi”的设备。如果路由器后台看不到，也可以先接上显示器进系统，在终端执行hostname -I查看IP，这种方式最直白。

还有一种办法是用手机App扫描局域网设备，比如iOS上的一些网络扫描工具，能列出局域网上所有活跃设备的IP和MAC地址，配合树莓派的MAC地址前缀（树莓派板载网卡对应的是BCM的厂商前缀）能快速找到。总之，找到IP之后，建议自己在路由器后台把它固定下来，或者后面通过配置文件固定，因为动态IP一旦变化，SSH配置里就要反复修改，远程开发效率大打折扣。

2. 树莓派端SSH的开启、优化与登录准备

2.1 确认SSH服务运行状态

树莓派系统烧录并启动完成后，先验证SSH服务是否正常。本地电脑打开终端（Windows可以用PowerShell或Windows Terminal），执行：

ping 192.168.1.100

IP地址替换成你树莓派的实际地址。能ping通说明网络层没问题。接下来测试SSH端口是否开放：

ssh pi@192.168.1.100

如果之前烧录时配置了用户名和密码，就用对应的账号登录。第一次连接会提示确认主机指纹，输入yes回车，然后输入密码。如果能成功进到树莓派的命令行界面，说明SSH已通，整体链路没问题。

如果提示Connection refused，大概率是SSH服务没开；如果提示Operation timed out，就要先查网络和防火墙了。排查顺序很重要：先ping，再telnet端口，最后才试SSH登录。跳步排查会浪费很多时间。

2.2 固定IP：让远程连接更稳定

DHCP分配的动态IP迟早会换来换去，谁也不想某天开箱后发现连接不上，然后跑到路由器后台查IP。固定IP有几种做法，推荐最稳定的方式：修改树莓派系统里的dhcpcd.conf文件。

sudo nano /etc/dhcpcd.conf

在文件末尾追加下面几行：

interface wlan0 static ip_address=192.168.1.100/24 static routers=192.168.1.1 static domain_name_servers=192.168.1.1 8.8.8.8

wlan0是Wi-Fi接口，如果你用网线就改成eth0。static ip_address是你要固定的IP，static routers是网关地址，一般就是路由器管理页面那个IP。保存退出后重启网络服务，或者干脆重启树莓派。注意/24这个掩码必须写，很多新手漏了就上不了网。

如果一时不想改系统文件，也可以先在路由器后台做MAC地址与IP的绑定，效果类似但管理上更集中。两种情况都很稳妥，选择自己习惯的即可。

2.3 安全加固：修改默认密码与禁用密码登录

树莓派默认用户pi在局域网里太显眼了。虽然家用路由器通常不会暴露公网，但局域网内一旦有恶意设备扫描，弱口令就是活靶子。我的建议是至少做两件事：改掉默认密码，或者创建一个自己名字的普通用户并加入sudo组。

创建新用户的命令如下：

sudo adduser yourname sudo usermod -aG sudo yourname

之后退出SSH，用新用户重新登录测试。确认没问题后，可以把默认用户保留但不使用，不建议直接删除pi用户，因为有些教程和脚本默认以pi用户为前缀写路径，删了会影响历史项目的运行。

远程开发用的机器，还建议把SSH密钥登录配好。这个在后面的章节会详细展开，配好之后不仅更方便，安全性也上一个台阶。密码只能在前期临时使用，长期使用密码登录，总有一种裸奔的错觉。

3. VSCode Remote-SSH连接配置实操

3.1 配置SSH Config：一劳永逸的连接方式

VSCode Remote-SSH底层的连接机制，实际上就是调用本机的OpenSSH客户端。你可以不配置任何文件，每次连接都手动输入完整命令，也可以像我一样把常用连接写进配置文件，一键直连。

VSCode左下角点绿色的连接图标，选择“Connect to Host”，再选“Configure SSH Hosts”，指定配置文件路径（Windows系统通常是C:\Users\你的用户名\.ssh\config，macOS/Linux是~/.ssh/config）。把下面的内容加进去：

Host pi HostName 192.168.1.100 User pi Port 22 IdentityFile ~/.ssh/id_ed25519

• Host是别名，想叫什么就叫什么，后续连的时候只输这个别名。
• HostName是树莓派的IP地址或域名。
• User是登录用户名。
• Port是SSH端口，默认22，如果你改过端口就填实际值。
• IdentityFile是私钥路径，如果还没配密钥，这行可以先不写，后续配好密钥再补上。

保存文件后再次点击绿色图标，选“Connect to Host”，你应该能看到pi这个别名出现在列表里。点它，VSCode就会开始SSH连接。

3.2 首次连接：安装VSCode Server的过程

第一次连接成功之后，VSCode右侧或底部会弹出进度条，显示正在远程主机上安装VSCode Server。这个过程是把VSCode的服务端组件下载到树莓派的用户目录下，服务端负责文件监听、语言服务、终端等相关工作，本地界面只是客户端。

这个下载有时候会很慢，因为VSCode Server是从微软的CDN下载的，树莓派的网络质量决定了整个体验。如果你发现进度条卡住，或者报了下载失败的错误，可以在本地手动下载对应的vscode-server-linux-armhf.tar.gz包（树莓派4B及其之前的版本是armhf架构，树莓派5如果是64位系统就用aarch64版本），然后手动上传到树莓派的~/.vscode-server/bin/目录下解压。

需要特别强调架构的问题：树莓派4B上如果安装的是官方默认的32位系统，架构是armv7l，VSCode Server对应版本是linux-armhf；如果装的是64位系统，架构是aarch64，对应版本是linux-arm64。只盯着Linux对不对是不行的，架构不对怎么装都跑不起来。查看树莓派架构可以用：

uname -m

拿到架构之后，后续下载VSCode Server就不会选错。这个坑我至少见过五六次，全是架构不匹配导致连接不上。

3.3 配置SSH密钥登录：免密与安全兼得

远程开发每天要输密码太烦了，而且每次连接都要输入密码，安全感上也差点意思。配置SSH密钥登录，本质上是把你的公钥放在树莓派的~/.ssh/authorized_keys文件里，之后SSH连接时客户端用自己的私钥签名，服务端用公钥验签，不需要再输入密码。

本地生成密钥对：

ssh-keygen -t ed25519 -C "your_email"

一路回车即可，生成的公钥在~/.ssh/id_ed25519.pub。然后把公钥拷贝到树莓派上：

ssh-copy-id -i ~/.ssh/id_ed25519.pub pi@192.168.1.100

如果没有ssh-copy-id（Windows自带的OpenSSH一般没有这个命令），就手动追加：

cat ~/.ssh/id_ed25519.pub | ssh pi@192.168.1.100 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

这段命令的作用是：在树莓派上创建.ssh目录（权限700），把公钥内容追加到authorized_keys（权限600），配置文件的权限必须严格限制，否则OpenSSH会直接拒绝使用它。很多人配了密钥却登录不了，十有八九就是.ssh目录或authorized_keys文件的权限不对。

密钥登录验证通过后，可以进一步编辑树莓派的/etc/ssh/sshd_config，把PasswordAuthentication改成no，彻底禁用密码登录。改之前一定要确认密钥登录稳定可用，避免把自己锁在门外。

3.4 在VSCode中打开远程项目

连接成功后，VSCode会打开一个全新的远程窗口，左下角不再显示“SSH: pi”这种状态，就说明你已经在远程环境里了。这时打开文件夹的入口是“打开文件夹”（Open Folder），不是“打开文件”，因为VSCode Server需要在远程工作区初始化文件监听和索引。

建议直接把树莓派上的一个专用工作目录，比如/home/pi/workspace/project1作为开发目录，用VSCode打开后，左侧资源管理器会显示树莓派上的文件列表。新建文件、编辑、删除、重命名，所有操作都直接作用在树莓派的文件系统上，和纯本地操作没有区别。而我通常会把代码放在树莓派的~/workspace下，把项目单独建一个目录，方便备份和权限管理。

如果你有多个项目，可以分别放在不同目录，VSCode的“打开文件夹”每次只能打开一个目录，但你可以通过“File -> Add Folder to Workspace”把多个目录加进同一个工作区，适合做微服务或多模块开发。

4. 远程开发体验优化与日常使用技巧

4.1 安装扩展：本地与远程分开选

VSCode的扩展机制在远程模式下有个显著特点：扩展分为本地扩展和远程扩展两类。界面主题、快捷键、本地文件格式化这类跟界面相关的扩展，在本地端安装；而Python、C++、GitLens这类跟代码逻辑、运行环境相关的扩展，必须安装到远程端。

怎么区分？打开扩展面板，搜索要装的扩展，如果当前处于远程会话中，按钮上会显示“在SSH: pi中安装”。比如Python扩展，在远程会话中安装，它才会使用树莓派上的Python解释器、虚拟环境、代码分析器。如果误装到本地，VSCode会提示你代码环境不匹配，找不到对应的解释器。

扩展安装原则就一句话：与代码运行、调试、语法分析相关的，往远程装；只影响编辑器外观和本地操作的，留在本地装。这个原则想明白了，很多“为什么我的Python扩展不生效”的疑问都会迎刃而解。

4.2 集成终端：把SSH窗口省掉

VSCode远程连接后，按Ctrl + \``快捷键（macOS是Control + `）会打开集成终端，这个终端默认就是SSH通道连接树莓派的Shell。你可以直接在里面执行python3跑脚本、systemctl查看服务状态、gpio`控制引脚，它和在树莓派本地终端操作完全等价。

集成终端最大的优势是可以和编辑器联动。比如你点击代码文件里的某个变量定义，终端里的grep命令结果就能在右侧面板显示；或者你用VSCode的搜索框全局搜索关键字，结果就是树莓派文件系统上的搜索，不需要自己再开一个SSH客户端跑来跑去。

如果觉得同一时间只有一个终端不够用，VSCode右上角有个“+”号可以新建多个终端会话，每个会话都是独立的SSH连接。我经常一边开一个终端跑Flask服务，另一边开一个终端看日志，效率比单终端高太多。

4.3 端口转发：让远程服务在本地可访问

这是Remote-SSH一个很实用但很多人没注意的功能。假设你在树莓派上启动了一个Web服务，监听端口是5000，在本地浏览器访问http://树莓派IP:5000也能打开。但如果你不想暴露树莓派的IP，或者某次服务只监听了127.0.0.1，本地就无法直接访问了。

VSCode的端口转发功能可以解决这个问题。远程会话中，进入“端口”（Ports）面板，点击“转发端口”，输入5000，VSCode会在本地电脑上开一个对应的端口映射，指向树莓派的5000端口。之后本地浏览器直接访问http://localhost:5000即可，数据经过SSH加密通道传输，相当于给服务加了一层SSH隧道。

这个功能对调试Web应用尤其方便。我自己经常把树莓派上写的Flask或FastAPI服务跑起来，然后端口转发到本地，用Postman或者浏览器直接调接口调试，和本机开发体验几乎一致。相比单独配置frp或者Ngrok这类内网穿透工具，VSCode内置的方案零配置、随用随关，干净利落。

4.4 大文件与性能问题的处理

树莓派毕竟是ARM架构的小主机，性能没法跟PC比。远程开发最常见的卡顿点是：打开超大单文件、VSCode实时索引大量文件、以及保存时触发格式化。我的经验是，尽可能避免在VSCode中直接打开树莓派上的大日志文件，可以用tail -f在终端里看，或者用less加载。

另外，如果项目目录里包含很多二进制文件或者node_modules这类依赖目录，建议在工作区根目录添加.gitignore的同时，也在VSCode的搜索设置里把排除目录配置好，减少文件监听的负担。

有一个设置项也值得改：files.watcherExclude，它决定哪些目录不参与文件变化监听。在远程开发场景下，把**/node_modules、**/.git、**/__pycache__加入排除列表，能显著降低CPU占用和文件同步的卡顿感。具体操作是Ctrl + Shift + P打开命令面板，输入Preferences: Open Settings (JSON)，然后添加：

"files.watcherExclude": { "**/.git/objects/**": true, "**/node_modules/**": true, "**/__pycache__/**": true }

4.5 其他提升效率的小配置

• 远程会话中，VSCode的settings.json是独立于本地的，你可以针对远程环境单独配置。比如树莓派的屏幕字体、默认编辑器缩进等。
• SSH连接如果长时间没有操作，可能因为超时掉线。可以在本地的~/.ssh/config里为树莓派主机配置：

Host pi ServerAliveInterval 30 ServerAliveCountMax 3

每隔30秒发送一个保活包，避免闲置断开。

• 如果你同时管理多台树莓派，可以用Host rasp*的通配符把公共配置统一起来，每个主机只写名称和IP，省事不少。

5. 常见问题与排查技巧实录

5.1 问题速查表

下面是这类远程开发配置中最常遇到的问题对照表，我结合自己的实操经验和周边的反馈整理出来的，按出现频率排序。遇到问题时，先按这张表快速排查，大多数情况都能解决。

5.2 排查案例：VSCode Server总是下载失败

这是一个特别常见的问题，展开讲一下。某次我帮朋友配置树莓派4B的远程开发，他的系统是64位的Raspberry Pi OS，VSCode连接时报Error: Missing vscode-server，进度条一直卡在0%。看了日志，发现是wget下载VSCode Server时网络超时。

解决思路是先确认树莓派架构，执行uname -m得到aarch64，然后手动在本地电脑上下载对应版本的vscode-server-linux-arm64.tar.gz。服务器版本号怎么确认？VSCode左侧“关于”里能看到的版本号，例如Commit: 5437499f2d042b19c1d1b6b5b5f2f4d6a32c50c0，这个commit号就是服务器包的路径标识。拼接下载地址：

https://update.code.visualstudio.com/commit:COMMIT_ID/server-linux-arm64/stable

下载完成后，把文件传到树莓派上，解压到~/.vscode-server/bin/COMMIT_ID/目录，再重新连接VSCode，问题就解决了。这个操作看起来麻烦，但实际只花几分钟，比反复等超时强多了。

5.3 排查案例：VSCode连接后没有代码高亮

有次我连上树莓派后，打开Python文件完全没有语法高亮，F1命令面板里的Python相关命令也不见了。查了扩展列表，发现Python扩展标记为“已安装”，但实际是安装在本地。原因也很简单，我第一次装扩展的时候是在本地界面上装的，那时候还没建立远程会话。

解决方法是：断开远程连接，回到本地界面，在扩展面板里找到Python扩展，会看到已安装的信息；然后重新连接远程，确认远程会话激活后，再到扩展面板搜索Python，这次按钮显示“在SSH: pi中安装”，点击安装。装完后VSCode会自动重新加载，语法高亮和解释器选择就都出来了。

这个案例说明一个重要习惯：装扩展前先看好当前窗口左侧下方有没有显示“SSH: pi”。没显示就说明还在本地环境，这时候安装的位置就是本地。

5.4 排查案例：远程文件夹里无法保存文件

运行VSCode远程开发一段时间后，可能出现编辑文件后按保存报错“Failed to save”：提示没有写权限。这种情况多半是文件的属主不是当前登录用户。比如你用pi用户登录，但文件是之前用root权限创建的，或者从别处拷贝过来时属主没有变更。

最简单的解决方式：

sudo chown -R pi:pi /home/pi/workspace

把工作目录的属主递归修改为当前用户。如果不想改属主，也可以从终端用sudo保存，但这不符合远程开发的习惯，时间长了会乱。通常我建议从一开始就把工作目录放在自己的home目录下，避免跨用户操作带来的权限纠缠。

5.5 排查案例：多块树莓派切换时的身份错乱

如果你像我一样手头有几块树莓派，一块做智能家居网关，一块做开发测试机，还有一块跑着摄像头监控服务，那么SSH配置里每个主机最好定制不同的用户名和私钥。否则A机器的密钥配置到B机器上就会出现“Permission Denied (publickey)”的错误。

SSH配置文件支持独立指定私钥路径，所以可以一个机器一个密钥：

Host pi-dev HostName 192.168.1.101 User dev IdentityFile ~/.ssh/id_ed25519_dev Host pi-gateway HostName 192.168.1.102 User gw IdentityFile ~/.ssh/id_ed25519_gw

连接的时候分别用pi-dev和pi-gateway，VSCode的“Connect to Host”菜单里也会依次列出它们。配置里如果某个主机不需要密钥，把IdentityFile注释掉或删掉，回落到密码登录即可。

最后再分享一点实际体会

整套配置跑通之后，我最大的感受是“树莓派终于成了一台真正意义上的服务器”。以前总觉得树莓派性能弱，只能在上面跑些小脚本，但用Remote-SSH配合VSCode，写代码的体验和本地开发几乎无差别，而且树莓派上挂着的GPIO、串口、摄像头模块都能直接在远程环境里操作，这对于做物联网项目的开发者来说是实打实的效率提升。

尤其是做机器人控制或者传感器数据采集这类项目时，代码需要频繁调试硬件，如果每次都要蹲在树莓派面前用键盘鼠标操作，那会非常痛苦。现在我在笔记本前，打开VSCode，选一下主机，代码、终端、日志、串口监控全部在一个窗口里完成。这个工作流不仅适合树莓派，任何家里的旧电脑、云服务器、ARM开发板都能用同一套方法接进来，边际成本为零。