企业官网建设流程全解析

把树莓派接上显示器、插上键鼠，在桌面环境里敲代码的日子，我过了很久。直到改用了 VS Code Remote-SSH 连上那台塞在角落里的树莓派，我突然明白远程开发并不只是“能连上而已”，而是把整个研发体验搬到了本地。这篇文章就来完整复盘一下，在 Ubuntu 22.04 的树莓派上，如何把 VS Code Remote-SSH 用成日常开发主力，包括安装、离线配置、调试，以及我踩过的那些坑。

无论你是做毕业设计、嵌入式比赛，还是想把手头的树莓派改造成家庭服务器、摄像头识别节点、ADS-B 接收装置，这套流程都能让你从“在树莓派上装 IDE 慢慢卡”切换到“本地编辑、远程编译调试”的舒服节奏。适合的人群很明确：已经有树莓派和 Ubuntu 22.04 系统，卡在 SSH 连接、VS Code 远程初始化失败、或者明明连上了却总觉得“不够顺手”的开发者。

1. 为什么要用 VS Code Remote-SSH 开发树莓派

1.1 传统开发方式的痛点

最早玩树莓派的时候，我是直接在树莓派上接显示器、连键盘鼠标，然后安装完整桌面版系统，再打开一个轻量级编辑器硬写。这种方式对付几百行的小脚本没问题，可一旦开始做项目，比如跑 YOLOv5 推理、解析 ADS-B 信号、控制摄像头模块，代码量上来之后，树莓派的性能就完全不够看了。打开一个大文件、装一堆 Python 插件、开着终端和浏览器查资料，板子很快就开始卡。另外一种常见做法是在 PC 上用编辑器写好代码，通过 U 盘或 scp 拷贝到树莓派上执行，再通过命令行看输出，调试全靠 print。一旦代码需要频繁改参数，这个“改代码-传文件-跑程序”的循环会让人怀疑人生。

其实远程开发并不是新鲜事，Vim over SSH、PyCharm Remote、VS Code Remote-SSH 都是成熟方案。但我最常用的还是 VS Code Remote-SSH，原因是它在“类 IDE 体验”和“资源占用”之间取得了很好的平衡：VS Code 的界面、快捷键、插件体系都在本地跑，树莓派上只需要一个轻量的 server 进程负责编译、运行和文件 IO，远程写代码和本地写代码几乎没有区别。

1.2 Remote-SSH 到底做了什么

第一次接触 VS Code Remote-SSH 时，我以为它只是简单的“在服务器上安装一个代理，然后通过 SSH 转发 IDE 输入输出”。实际上它的工作流程更彻底：本地 VS Code 通过 SSH 连接远端后，会在远端自动下载并启动一个vscode-server服务端进程，这个服务端负责文件索引、代码分析、终端会话、调试适配器等等。你本地看到的编辑器、侧边栏、插件面板，其实是连接着远端的“遥控界面”。本地安装的 VS Code 插件会自动分类，有些插件只需要在本地运行，比如主题、快捷键；而 Python、C/C++、Git 这类需要访问文件系统和运行环境的插件，会实际安装在远端 server 上。

理解这一点很重要。很多人遇到“远程连接成功但 Python 解释器还是本地的”问题，根源就在插件安装位置搞错了。在 Remote-SSH 场景里，插件栏会区分两个分类：本地 - SSH: 树莓派和SSH: 树莓派 - 已安装。需要操作远程代码的插件，必须安装在远端端，而不是本地。

另外，Remote-SSH 并不强制要求双方系统一致。我只负责树莓派的 Ubuntu 22.04 连接过，也试过连接云上的 Ubuntu 服务器、家里的旧 Windows 台式机，只要目标机器开启 SSH 服务，VS Code 就有办法在上面跑起 server。树莓派作为 ARM 架构的设备一样支持，唯一要留意的是远端 server 包的架构必须匹配，这也是后面离线安装时会踩坑的地方。

1.3 什么时候真的建议用 Remote-SSH

我建议把 Remote-SSH 作为树莓派开发的默认方式，尤其在下面几种场景：

• 你是学生党，在宿舍用笔记本连接实验室或房间角落里的树莓派，不想天天插拔 SD 卡。
• 你的项目用到 USB 摄像头、GPIO 或串口外设，树莓派必须固定在某个物理位置，你希望像操作本地文件一样改脚本并立即运行。
• 你需要在树莓派上跑训练好的 YOLOv5、TensorFlow Lite 模型，但想在本地用熟悉的编辑器调试代码。
• 每次升级系统后不想重新安装一堆开发工具，用远程方式让树莓派保持“最小安装”，只负责运行。
• 团队协作时，可以通过 SSH 转发把 5000、8080 等端口暴露给多人访问。

当然，Remote-SSH 并不适合所有情况。如果你的网络环境非常不稳定，SSH 频繁断连，或者你只是偶尔跑一下命令行命令，那直接用系统自带的终端即可，没必要为了“远程开发”而远程开发。远程连接本身需要服务端一直在线，断电、休眠、路由器重启都会让你的开发中断，这也是后面我们会在树莓派上做“开机自启 SSH、设置静态 IP、配置 keepAlive”的原因。

2. 动手前准备：树莓派端 Ubuntu 22.04 环境基础

2.1 硬件和系统版本的选择

建议使用树莓派 4B 或 5，内存至少 4GB。树莓派 Zero 2 虽然也能安装 Ubuntu 22.04，但跑 VS Code Server 会明显吃力，不推荐作为日常远程开发目标。系统镜像推荐 Ubuntu Server 22.04 LTS，而不是桌面版。桌面版虽然自带图形界面，但会占用大量内存，而且远程开发场景下桌面对我们来说基本没用。当然如果你需要用树莓派桌面做其他事情，也可以选择 desktop 版，只要开启 SSH 服务即可，Remote-SSH 并不在意远端有没有桌面环境。

烧录镜像我习惯用 Raspberry Pi Imager。在 Imager 里选择操作系统时，要注意树莓派 4B/5 都是 64 位 CPU，选择 64-bit 版本的 Ubuntu Server 22.04，而不是 32 位。烧录完成后，先把 SD 卡装上，开机后默认用户是ubuntu，默认密码是ubuntu，首次登录会强制要求修改密码。这里有个经验：如果你不想在树莓派上插显示器和键盘完成首次配置，就提前在 Imager 的“设置”里启用 SSH、配置好 Wi-Fi 和密码，这样开机后就能直接通过局域网找到树莓派。

如果你已经刷好了系统但忘了配置用户名和 Wi-Fi，也可以用串口连接来修改，或者插回到读卡器重新设置。具体的首次开机配置和 SSH 开启方式比较基础，网上一搜一大把，我更想强调的是一定要进入系统后立刻执行一次系统更新和换源，否则后面装依赖包时会被网络问题卡很久。

2.2 Ubuntu 22.04 换源：树莓派必须用 ports 源

Ubuntu 在 x86 架构上官方源是archive.ubuntu.com，而树莓派这类 ARM 设备使用的是ports.ubuntu.com。很多人在树莓派上换源时，直接照着网上的教程把archive.ubuntu.com替换成国内镜像的ubuntu/路径，结果 apt update 时一堆 404，不仅没有加速，反而破坏了源。在 Ubuntu 22.04 中，源配置默认在/etc/apt/sources.list文件里，可以这样操作：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i 's|http://ports.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports|g' /etc/apt/sources.list sudo apt update

如果你用的是树莓派官方系统，要注意它不是 Ubuntu，源目录格式也不一样。这篇文章限定在 Ubuntu 22.04 环境，所以上面的替换命令就是最直接的。如果使用阿里云镜像，把mirrors.tuna.tsinghua.edu.cn/ubuntu-ports换成mirrors.aliyun.com/ubuntu-ports即可。我做项目时更常用清华源，因为稳定性比较好，更新也及时。

换源完成后，建议安装一些基础工具：

sudo apt update sudo apt upgrade -y sudo apt install -y build-essential git curl wget net-tools openssh-server

build-essential包含 gcc、g++、make 等编译工具，很多树莓派项目会依赖它们。curl和wget用于下载文件。如果你后面要离线安装 VS Code Server，也没有强制要求安装它们，但scp是 OpenSSH 客户端自带的功能，本地 Windows/Mac 也需要有 SSH 客户端才行。

2.3 配置 SSH 服务并设置固定地址

Ubuntu Server 安装后默认会安装openssh-server，但为了保险还是要确认一下：

sudo systemctl status ssh

如果没有安装，执行：

sudo apt install openssh-server -y sudo systemctl enable ssh --now

然后查看 IP 地址：

ip addr

局域网内通常会拿到一个例如192.168.1.100的地址。不过树莓派默认的情况下不会开启 mDNS 解析，为了以后不用天天查 IP，我强烈建议设置静态 IP，或者在路由器后台把 MAC 地址固定分配一个 IP。树莓派上修改静态 IP 的一般做法是编辑 netplan 配置：

sudo nano /etc/netplan/01-netcfg.yaml

常见配置如下（根据你的网络网段调整）：

network: version: 2 ethernets: eth0: dhcp4: no addresses: - 192.168.1.100/24 routes: - to: default via: 192.168.1.1 nameservers: addresses: [223.5.5.5, 114.114.114.114] wifis: wlan0: dhcp4: no access-points: "你的WiFi名": password: "你的密码" addresses: - 192.168.1.100/24 routes: - to: default via: 192.168.1.1 nameservers: addresses: [223.5.5.5, 114.114.114.114]

然后执行：

sudo netplan apply

如果你用 Raspberry Pi Imager 配置了 WiFi，有些版本默认用 NetworkManager，netplan 就不是默认方案。判断方法很简单：先看/etc/netplan/下有没有 yaml 文件，没有的话就用nmcli修改。工程上稳定优先，如果树莓派插着网线，我建议优先用有线连接，干扰少、延迟低、调试体验更好。

修改完网络后，重启以下 SSH 服务，确保配置生效：

sudo systemctl restart ssh

现在从电脑上测试一下：

ssh ubuntu@192.168.1.100

能登录就说明基础环境已经通了。

2.4 免密登录：把密钥对配置好

树莓派上如果每次用密码登录，Remote-SSH 每次连接都可能要你输密码，虽然能记住会话，但终归不痛快。而且后续实现更高效的自动化部署时，密钥登录几乎是必须的。在电脑上生成密钥对：

ssh-keygen -t ed25519 -C "raspberry-pi-remote"

一路回车会生成~/.ssh/id_ed25519和~/.ssh/id_ed25519.pub。然后复制公钥到树莓派：

ssh-copy-id ubuntu@192.168.1.100

没有ssh-copy-id的 Windows 用户也可以手动把公钥内容追加到树莓派的~/.ssh/authorized_keys文件里。注意文件权限：

chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys

之后再用ssh ubuntu@192.168.1.100登录，就不再需要密码了。这一步做完，Remote-SSH 的体验会瞬间提升，因为 VS Code 每次重连都不会再卡在密码输入框。

3. VS Code Remote-SSH 配置全流程

3.1 本地 VS Code 和远程开发扩展包

本地 VS Code 可以在官网直接下载对应操作系统的安装包，Windows、macOS、Linux 都支持。装好后打开扩展市场，搜索“Remote Development”，安装 Microsoft 官方出的这个扩展包，也就是我们常说的 Remote-SSH 全家桶。它会自动带上 SSH、WSL、Containers 三个扩展，虽然通常我们只会用到 SSH 这一个。

安装完成后，左侧边栏会出现“远程资源管理器”，之前配置好的 SSH 主机可能会自动识别，也可能需要手动添加。这里有两个选择：一是直接点击界面上的“连接主机”，输入ubuntu@192.168.1.100；二是把主机信息写入本地 SSH 配置文件，这样以后能明确命名，多台树莓派也能同时管理。我建议用后者，步骤是：打开命令面板（F1），输入Remote-SSH: Open SSH Configuration File，选择用户级别的~/.ssh/config文件进行编辑。

以我的树莓派为例，SSH config 内容如下：

Host raspberrypi HostName 192.168.1.100 User ubuntu IdentityFile ~/.ssh/id_ed25519 ServerAliveInterval 30 ServerAliveCountMax 3

Host是别名，可以随便起，比如pi4、adsb-pi。IdentityFile指定私钥路径。ServerAliveInterval和ServerAliveCountMax这两条很重要，能避免因为一段时间没操作而被服务器断开连接。如果你用的是树莓派 5，可以在 HostName 后面继续加Port 22（如果修改过 SSH 端口就填对应端口）。配置好后再打开远程资源管理器，选择raspberrypi主机，VS Code 会开一个新窗口，并建立 SSH 连接。

3.2 连接过程与 VS Code Server 初始化

点击连接后，VS Code 会弹出一个新窗口，左下角显示“正在打开远程...”并带上连接地址。此时它正在尝试连接远端，并在树莓派的用户目录下创建~/.vscode-server目录，然后下载对应版本的vscode-server-linux-arm64.tar.gz并解压到其中。整个初始化过程取决于你的网络速度和树莓派性能，一般几十秒到几分钟不等。

如果一切顺利，新窗口左下角会变成SSH: raspberrypi，并且“文件-打开文件夹”能直接打开远端目录。这时你在本地新建一个 test.py，保存到远端文件系统，在终端里运行python3 test.py，你会看到输出在远端终端呈现，整个过程非常跟手。

但不少人在这一步会踩到同一个坑：VS Code 窗口一直提示“正在下载 VS Code Server”，过一会儿报错“未能下载 VS Code 服务器 (failed to fetch)”。原因通常有三个：要么树莓派无法访问微软的下载服务器，要么网络本身不通，要么~/.vscode-server目录下之前下载过损坏的文件导致校验失败。这时候就轮到离线安装方案出场了。

3.3 离线安装 VS Code Server 的完整流程

先说离线安装的思路：远端需要运行和本地 VS Code 完全一致的版本，所以我们要把对应版本的 server 包手动下载、上传、解压，放到指定的~/.vscode-server/bin/<commit>目录。关键是找到“版本对应关系”。

本地 VS Code 中按 F1，选择“帮助-关于”，或者直接点菜单栏的帮助 -> 关于，会看到版本号下方有一个 commit hash，比如e5a624b788d92b8d34d1392e4c4d9789406efe8f。这个 commit 就是 server 包下载路径的一部分。

树莓派是 arm64 架构，所以需要下载的是server-linux-arm64。手动下载 URL 格式如下：

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

实际上你也可以直接在本地浏览器打开这个地址，浏览器会自动下载server-linux-arm64.tar.gz。如果你在本地电脑上下载不了，也可以在有网络的电脑上下载，再拷贝到树莓派。下载完成后，通过 scp 上传到树莓派：

scp vscode-server-linux-arm64.tar.gz ubuntu@192.168.1.100:/tmp/

登录树莓派后，执行以下命令：

mkdir -p ~/.vscode-server/bin/e5a624b788d92b8d34d1392e4c4d9789406efe8f tar -xzf /tmp/vscode-server-linux-arm64.tar.gz -C ~/.vscode-server/bin/e5a624b788d92b8d34d1392e4c4d9789406efe8f --strip-components=1 rm /tmp/vscode-server-linux-arm64.tar.gz

注意 tar 解压时默认会多包一层目录，需要加--strip-components=1，否则 server 目录结构会不对。解压完成后，从本地 VS Code 再次点击连接，它检测到 commit 目录存在，就不会再尝试联网下载，而是直接启动 server 并完成握手。

如果连接后还提示“未找到已安装的 VS Code Server”或“正在下载最新版本”，可能是 commit 对不上。检查目录名是不是完全等于 VS Code 里显示的 commit hash，包括大小写和末尾有没有空格。另外建议把~/.vscode-server目录的属主设为当前用户：

sudo chown -R ubuntu:ubuntu ~/.vscode-server

这是权限问题最常见的修复方式。

3.4 远程插件与本地插件的配合

连接成功后，插件管理变得相对特殊。你可能会发现之前安装的插件在远程窗口中显示“已禁用”，点“在远程安装”后才会出现在远程端。一般我建议只在本地安装界面主题类、键盘快捷键类插件；所有语言支持（Python、C/C++、Git、Jupyter 等）都安装在远端。比如远程打开一个 Python 文件，VS Code 通常会提示安装 Python 扩展，直接点击“安装到 SSH: raspberrypi”即可。

安装完成后，按 Ctrl+Shift+P 输入Python: Select Interpreter，选择远端/usr/bin/python3或是在虚拟环境中的解释器。这一步千万别选错成本地解释器，否则代码提示和运行会非常混乱。那时你就会感受到 Remote-SSH 真正的便利：树莓派上的所有环境都是一手的，本地的 Python 包不用重复安装。

另外，如果想要在远程终端中使用自己的 shell，比如 zsh，可以在树莓派上先安装好zsh，然后 VS Code 会自动使用登录 shell 启动远程终端，不需要额外配置。要是远程终端没有加载你的.bashrc或者source不生效，可以先sudo apt install zsh再chsh -s $(which zsh)，重新连接后生效。

4. 远程开发实战：从写代码到调试

4.1 用 Remote-SSH 管理完整项目：以 Flask 摄像头预览为例

为了演示整条链路，我们做一个最简单但特别有代表性的场景：在树莓派上写一个 Flask 服务，把树莓派接的摄像头画面实时传到浏览器。摄像头模块可以选择 OV5647 或者其他 USB 摄像头，但这里我不深入摄像头驱动，只是想用这个例子说明远程代码编辑、端口转发、运行调试是怎么串起来的。

在 VS Code 的远程窗口里，打开一个文件夹，比如/home/ubuntu/cam-demo，然后新建app.py：

import io import cv2 from flask import Flask, Response import threading app = Flask(__name__) camera = cv2.VideoCapture(0) def generate_frames(): while True: success, frame = camera.read() if not success: break ret, jpeg = cv2.imencode('.jpg', frame) if not ret: continue yield (b'--frame\r\n' b'Content-Type: image/jpeg\r\n\r\n' + jpeg.tobytes() + b'\r\n') @app.route('/video_feed') def video_feed(): return Response(generate_frames(), mimetype='multipart/x-mixed-replace; boundary=frame') @app.route('/') def index(): return '<h1>Remote-SSH Raspberry Pi Camera</h1><img src="/video_feed">' if __name__ == '__main__': app.run(host='0.0.0.0', port=5000, threaded=True)

然后在远程终端安装依赖：

cd /home/ubuntu/cam-demo pip install flask opencv-python-headless python app.py

如果树莓派上摄像头没有正常驱动，可能报错Could not open video device，这属于硬件环境问题，后面会说处理方法。这里核心是验证 Remote-SSH 的端口转发能力。

VS Code Remote-SSH 会自动转发远程的端口到本地，默认情况下只要远程服务监听在某个端口，VS Code 会在编辑器右下角弹出“检测到端口 5000 已转发”，然后本地浏览器打开http://localhost:5000就能访问树莓派上的服务，不需要再用ssh -L手动做端口映射。如果没自动弹出，也可以点击 VS Code 底部“端口”选项卡，手动输入 5000 端口并添加。这个能力在做 Web 服务、Jupyter Notebook、TensorBoard 时特别实用，省去了大量网络调试时间。

4.2 断点调试 C/C++ 项目与 Python 项目

Remote-SSH 下调试跟本地几乎一样。以 Python 为例，远程打开app.py，在左侧行号处点击设置断点，按 F5，选择“Python 调试器”，VS Code 会在远端启动 Python 进程并把调试 UI 连接到它。你可以在本地查看变量、调用栈、表达式，数据全部来自远端实时传递。这个调试能力在本地是理所当然的，但对树莓派开发来说却很难得，因为以前我只能靠 print 慢慢猜问题。

如果是 C/C++ 项目，可以安装 C/C++ 扩展并配置launch.json。假设你有一个简单的gpio_blink.c用到了树莓派的 GPIO 引脚，编译时用gcc -Wall -o gpio_blink gpio_blink.c -lwiringPi（如果安装了 wiringPi），调试时需要使用sudo gdb或添加sudo权限。比较麻烦的是树莓派的 GPIO 操作往往需要 root 权限，而 VS Code 远程调试默认以当前用户启动，会出现 “Operation not permitted”。解决办法是在 VS Code 的settings.json里加上"terminal.integrated.defaultProfile.linux"或直接调整目标用户的sudo权限，简单粗暴的方式是先执行sudo chmod 666 /dev/gpiomem，但不稳定。更稳妥的是创建一个可运行gdb的 setuid 包装脚本，不过这已经超出 Remote-SSH 的范畴，遇到时再查就行。

4.3 远程 Git 与 Genie/AI 插件扩展

很多同学在树莓派上做毕设时会频繁使用 Git。Remote-SSH 连接后，VS Code 的源代码管理面板会直接读取远端的 Git 仓库。我的习惯是：在树莓派上初始化仓库，本地远程打开这个文件夹，就可以在侧边栏看到修改的文件、提交按钮、推送按钮，体验和本地仓库完全一致。要注意的是远端仓库建议把换行符配置为统一的LF，避免 Windows 本地编辑器把行尾改成 CRLF 导致 Git diff 巨乱，在树莓派的~/.gitconfig中加：

[core] autocrlf = input

热词里提到的 Claude Code、Codex、Gemini CLI 这类 AI 辅助工具，在 Remote-SSH 中也可以配置到远端终端使用。比如你想在树莓派上让 AI 直接读代码生成解释，只要把相应 CLI 工具安装到远端，然后在 VS Code 集成终端里运行即可。由于树莓派性能有限，我不建议在树莓派本地跑大型 AI 模型，更推荐把代码编辑和调用 AI 的操作放在本地，或者通过 Remote-SSH 的“转发端口”访问运行在服务端的模型服务。具体用哪个插件，看个人习惯，但核心是保证远端环境干净、依赖明确。

4.4 我对日常远程开发工作流的一个建议

用了一段时间后，我给自己定了一个规矩：树莓派上只保留项目代码和运行环境，所有重要的文档、笔记和配置文件都用 Git 管理，并且不随手创建“一坨”没有意义的临时文件。这样即使树莓派 SD 卡损坏，我重新烧录系统后，只需要几条命令就能恢复开发环境。Remote-SSH 让本来在物理上隔离的树莓派变成了一个随时可用、随时可扔的远端环境，我们应该充分利用这种特性，把服务器维护和项目开发分隔开。

我还会在树莓派上建一个~/projects目录，所有项目都放在里面，并用virtualenv或venv隔离 Python 环境。VS Code 的 Python 扩展能自动识别venv，选择解释器时一点就好。如果你需要在树莓派上跑 YOLOv5 这样的推理框架，依赖比较复杂，更建议用 Docker 容器。树莓派 5 上也能安装 Docker，通过 VS Code 的 Remote-Containers 扩展直接开发容器内部，但那是另一个话题，Remote-SSH 和 Docker 并不冲突，可以先连上整个树莓派，再在终端里进入容器。

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

5.1 “failed to fetch” 无法下载 VS Code Server 的排查顺序

这是大家问得最多的问题。连上 SSH 后 VS Code 一直尝试下载 server，但总是失败。从我的经验看，排查顺序应该是这样：

1. 先确认网络通不通：在树莓派终端curl -I https://update.code.visualstudio.com看看能不能返回 HTTP 状态码。如果完全超时，说明树莓派访问微软下载服务器有问题，那就直接走离线安装。
2. 再确认时间是否同步：date看看当前时间对不对，证书校验失败也可能导致下载失败。如果时间不对，sudo timedatectl set-ntp true同步一下。
3. 检查~/.vscode-server/bin下是否残留了同名目录，如果上次解压失败，VS Code 可能会认为已经存在而跳过重新下载，但启动 server 时又会报错。手动把bin下对应目录删掉再重新连接。
4. 查看 VS Code 窗口右下角的通知或输出面板，切换到“远程 - SSH”日志，里面有完整报错信息，很多问题比“failed to fetch”更具体。
5. 如果确认需要离线安装，就按前面 3.3 节操作，离线包下载地址的关键就是 commit hash。

5.2 SSH 权限问题：Bad owner or permissions

在本地配置好~/.ssh/config后，如果 SSH 提示Bad owner or permissions，基本上是因为 config 文件或私钥文件的权限太宽松。Windows 和 macOS 的 SSH 客户端都会检查权限，避免私钥被其他用户读取。在 Windows 上可以通过右键属性->安全里面去除继承权限，但更快的办法是在 PowerShell 里跑：

icacls "$env:USERPROFILE/.ssh/id_ed25519" /inheritance:r /grant:r "$env:USERNAME:F"

macOS/Linux 上：

chmod 600 ~/.ssh/id_ed25519 ~/.ssh/config chmod 700 ~/.ssh

处理完再试一次ssh raspberrypi。

5.3 连接上了但远程终端中文显示乱码或字体异常

树莓派默认 locale 可能是en_US.UTF-8，如果本地代码有中文，并且树莓派上没有安装中文字体或 locale，终端可能会显示乱码。可以在树莓派上安装语言包并重新生成 locale：

sudo apt install language-pack-zh-hans -y sudo update-locale LANG=zh_CN.UTF-8

改完后重新登录一次，再打开远程终端中文字符就正常了。VS Code 的集成终端默认继承远端 locale，如果远端是 zh_CN，字体渲染一般没问题。

5.4 远程终端能进但 VS Code 窗口一开就闪退

这种问题多出在 server 启动时依赖的 glibc、libstdc++ 版本不匹配。Ubuntu 22.04 的 glibc 比较新，正常不会出问题。如果你用的是 Ubuntu 20.04 或其他旧系统，可能就要手动安装新版本或直接升级系统。树莓派 4B 上我还碰到过一次磁盘空间不足，导致 server 解压失败，窗口反复闪退。排查方法也很简单：df -h看看/home磁盘占用情况，清掉没用的包和缓存。

5.5 摄像头、GPIO 等外设在远程会话中权限不足

远程开发时，树莓派的物理外设仍然通过内核驱动暴露。摄像头通常需要用户处于video群里，GPIO 则需要能访问/dev/gpiomem。如果你连接的是普通用户，可能在本地终端能正常使用的摄像头，到了 VS Code 远程终端里报Permission denied。

解法是把用户加入对应用户组并重新登录：

sudo usermod -aG video $(whoami) sudo usermod -aG dialout $(whoami) # 串口设备 sudo usermod -aG gpio $(whoami) # 部分树莓派定制环境

然后重新连接 SSH。注意树莓派官方系统里可能是gpio组，Ubuntu Server 则不一定存在，用groups命令查看即可。

5.6 树莓派内存不足：VS Code Server 被 OOM 杀掉

树莓派 4B 4GB 版本跑 VS Code Server 通常不会 OOM，但如果你同时编译大型 C++ 项目、开多个终端、跑 YOLOv5 推理，4GB 很快就顶不住了。此时树莓派会出现终端命令半天没反应、VS Code 远程窗口直接断连、dmesg里有很多killed process记录。最有效的临时手段是加 swap：

sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

要永久生效，还得把/swapfile none swap sw 0 0加进/etc/fstab。我建议树莓派开发机的 swap 至少给 2G，特别是跑视觉识别项目时，能减少很多莫名其妙的卡顿。

6. 踩坑之后的几点心得

用 VS Code Remote-SSH 开发树莓派，真正折磨人的不是代码本身，而是从“能 SSH 登录”到“能流畅远程开发”之间的这段距离。第一次配置离线 VS Code Server 时，我为了找对 commit 和 arm64 包，前前后后花了三个小时，后来发现只要把本地 VS Code 的版本信息截图保存好，每次装新机器都先查这个，步骤就固定下来了。

还有一个小技巧：就算你已经离线装好了 server，也最好把当时下载的 tar.gz 压缩包保存在本地或网盘一份。因为 VS Code 每次自动更新后，commit 都会变化，如果树莓派端不能访问下载地址，下次连接时还要再解压一次新版 server。遇到这种更新，我一般会先克制一点，不在本地 VS Code 频繁升级，否则远端也得跟着升级。

最后提醒一句，网上关于“Ubuntu 22.04 安装 NVIDIA 驱动”的教程非常火，但树莓派的 SoC 是 Broadcom，不是 NVIDIA 平台，千万不要照着 NVIDIA 驱动教程去折腾树莓派。如果你确实需要 GPU 加速，要看树莓派 GPU 对应的用户态驱动和加速库方案，跟 NVIDIA 驱动完全是两码事。树莓派上真正的价值是把 Remote-SSH 做成标准工作流，然后专注算法和业务逻辑，而不是把时间耗在“连接”上。

我个人现在的状态是：树莓派 5 放在阳台旁的弱电箱里，插着网线，根目录挂了一个 128G 的 USB 盘，代码、模型、日志全部在远端。工作日白天用笔记本在书房打开 VS Code，点击左下角 SSH: raspberrypi 就能继续昨天没写完的代码，笔记本没电了也不影响树莓派上的任务。这样的开发方式用了大半年，我再也没有怀念过给树莓派接显示器、敲命令行的日子。希望这篇文章能帮你少走点弯路，早日把树莓派变成你的“远程编译器”。