2. 环境准备
在开始部署任何基于 Raspberry Pi 的视觉或边缘计算项目之前，环境准备的质量直接决定了后续排障工作的复杂度。很多“摄像头无法识别”“依赖安装失败”“系统卡顿”的问题，根源并非代码或硬件本身，而是初始环境搭建时埋下的隐患——例如使用了不兼容的镜像、供电不足、未正确开启 Camera 接口，或是软件源指向了无法访问的海外服务器。本章将围绕硬件选型、镜像烧录、系统初始化三个核心环节，建立一套可复现、可验证的标准操作流程，并针对常见误区进行深度拆解。
2.1 硬件型号选择与供电约束
Raspberry Pi 的硬件选型并非“越贵越好”，而是需要根据项目负载特性决定。对于涉及摄像头图像采集、轻量级推理（如 TensorFlow Lite、OpenCV 基础处理）的场景，Raspberry Pi 4B（4GB/8GB）是当前性价比最高的选择；若需要更强的并行计算能力或双摄像头输入，Raspberry Pi 5 提供了更快的 CPU 和 PCIe 接口，但其功耗和散热要求也显著提升。Compute Module 4（CM4）则适用于需要定制载板或工业级部署的场景，但其初始配置复杂度更高，不适合快速原型验证。
供电是 Raspberry Pi 部署中最容易被忽视的隐性故障源。Pi 4B 在满负载下（CPU 全速 + 摄像头 + Wi-Fi）电流需求可达 2.5A 以上，若使用劣质电源或过长的 USB 线缆，电压跌落会导致 SoC 进入欠压保护状态，表现为系统随机重启、USB 外设频繁断开、摄像头初始化失败。判断供电是否充足的最直接方法是查看 vcgencmd get_throttled 的输出：若返回值为 0x50000，说明曾发生过欠压或软限流。建议使用官方 5V/3A 电源，或至少选择带有 AWG 20 线径的 USB-C 线缆。
| 硬件型号 | RAM 选项 | 推荐场景 | 关键注意事项 |
|---|---|---|---|
| Pi 4B | 2/4/8 GB | 通用视觉项目、轻量推理 | 需主动散热片；8GB 版本对 32-bit 系统不友好 |
| Pi 5 | 4/8/16 GB | 多路摄像头、复杂模型推理 | 需 5V/5A 电源；首次启动需更新 EEPROM |
| CM4 | 1/2/4/8 GB | 工业嵌入、定制载板 | 需自行设计电源与接口电路，不适合初学者 |
2.2 操作系统镜像选择与烧录流程
操作系统镜像的选择直接影响依赖安装的兼容性。自 2023 年 10 月起，Raspberry Pi 官方推荐使用 Raspberry Pi OS (Bookworm)，其基于 Debian 12，默认使用 Python 3.11 和新的 libcamera 框架。对于摄像头项目，强烈建议选择 64-bit Lite 版本（无桌面环境），因为桌面环境会占用约 300MB 内存和大量 CPU 资源，且其自带的 GUI 工具在无头模式下毫无意义。若必须使用桌面版，请确保选择 64-bit 而非 32-bit，因为 32-bit 内核无法充分利用 4GB 以上内存，且部分现代 Python 包（如 TensorFlow）已停止提供 armhf 预编译轮子。
烧录工具首选 Raspberry Pi Imager（v1.7 以上版本）。它不仅能烧录镜像，还能在烧录前预配置 SSH、Wi-Fi、用户名和主机名，极大简化了无头部署流程。操作步骤如下：
- 下载并安装 Raspberry Pi Imager，插入 microSD 卡（建议 A2 级，容量 ≥ 32GB）。
- 选择镜像：Raspberry Pi OS → Other → Raspberry Pi OS Lite (64-bit)。
- 点击齿轮图标，预配置：启用 SSH（允许密码登录）、设置 Wi-Fi SSID 与密码、设置用户名和密码、可选设置时区为 Asia/Shanghai。
- 点击“烧录”，等待完成。烧录过程中不要拔出 SD 卡。
烧录完成后，建议在电脑上挂载 SD 卡的 bootfs 分区，检查是否生成了 ssh 文件和 userconf.txt（若使用 Imager 预配置则无需手动创建）。若需要手动启用 SSH，可在 bootfs 根目录创建空文件 ssh，并创建 userconf.txt 写入 用户名:加密密码（加密密码可通过 openssl passwd -6 生成）。
raspbian.raspberrypi.org，在国内网络环境下 apt 更新极慢甚至超时。烧录完成后，首次登录系统应立即执行换源。编辑 /etc/apt/sources.list，将 deb http://raspbian.raspberrypi.org/raspbian/ bookworm main 替换为清华镜像地址。同时编辑 /etc/apt/sources.list.d/raspi.list，将 archive.raspberrypi.org 替换为清华镜像。对于 pip，建议创建 /etc/pip.conf 写入 [global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple。
2.3 初始配置：SSH、Wi-Fi 与摄像头使能
完成烧录后，将 SD 卡插入 Pi，连接网线（或等待 Wi-Fi 连接），上电启动。首次启动时，Pi 会自动扩展文件系统并重启。等待约 1-2 分钟后，尝试通过 SSH 连接：ssh 用户名@raspberrypi.local（需电脑安装 Bonjour 服务）或直接使用路由器分配的 IP 地址。若无法连接，请检查路由器后台确认 Pi 是否获得 IP，并确认防火墙未屏蔽 22 端口。
登录后，首先执行 sudo raspi-config 进行基础配置：
- Interface Options → Camera：启用摄像头（若使用 libcamera 框架，此步骤会添加
dtoverlay=imx219等设备树覆盖）。 - Localisation Options → Timezone：设置为 Asia/Shanghai，避免日志时间偏差。
- Advanced Options → Expand Filesystem：确保根分区占满 SD 卡空间（Imager 默认已自动扩展，但手动确认无妨）。
摄像头使能后，使用 libcamera-hello 命令测试。若输出 Camera available 并短暂显示预览窗口（无头模式下可添加 --list-cameras 参数），说明摄像头硬件与驱动正常。若提示 No cameras available，请检查 CSI 排线是否插紧、方向是否正确（金属触点应面向 PCB 板上的“CAMERA”标签），并确认 dmesg | grep -i camera 是否有错误信息。
raspistill 命令已被 libcamera-still 取代。若你的代码仍调用 raspistill，需要安装兼容层：sudo apt install raspicam-docs 或修改代码适配 libcamera API。建议新项目直接使用 picamera2 Python 库，它是官方推荐的摄像头控制接口。
2.4 实战案例：从零到可用的无头部署排障
某实验室需要部署一台 Pi 4B（8GB）作为视觉采集节点，要求通过 Wi-Fi 连接，并运行 OpenCV 实时读取 CSI 摄像头画面。团队按照上述流程烧录了 64-bit Lite 镜像，预配置了 SSH 和 Wi-Fi。上电后，SSH 连接成功，但执行 libcamera-hello --list-cameras 时提示 No cameras available。
排查过程如下：
- 检查硬件连接：重新插拔 CSI 排线，确认金属触点朝向正确（排线蓝色标签应面向网口方向）。再次测试，问题依旧。
- 检查设备树覆盖：执行
dmesg | grep -i imx，发现没有任何 imx219 相关输出。说明摄像头未被内核识别。 - 检查 raspi-config 状态：进入
sudo raspi-config，发现 Camera 选项显示“Enabled”，但/boot/config.txt中未自动添加dtoverlay=imx219。手动添加该行并重启。 - 重启后验证：
libcamera-hello --list-cameras成功列出摄像头，但执行libcamera-hello时出现Failed to allocate buffers错误。 - 分析原因：该错误通常与 CMA（Contiguous Memory Allocator）内存不足有关。Pi 4B 默认 CMA 为 256MB，但 OpenCV 同时占用大量内存。编辑
/boot/config.txt，添加gpu_mem=128和cma=128，重启后问题解决。
| 排查步骤 | 命令/操作 | 预期结果 | 实际结果 | 结论 |
|---|---|---|---|---|
| 1. 硬件检查 | 重新插拔排线 | 摄像头被识别 | 仍无设备 | 排除物理接触问题 |
| 2. 内核日志 | dmesg \| grep -i imx | 显示 imx219 驱动加载 | 无输出 | 设备树未加载 |
| 3. 配置检查 | cat /boot/config.txt | 包含 dtoverlay=imx219 | 缺失 | raspi-config 未生效 |
| 4. 手动修复 | 添加 dtoverlay=imx219 | 摄像头列表可见 | 成功 | 驱动加载正常 |
| 5. 内存分配 | 添加 cma=128 | libcamera-hello 正常 | 成功 | CMA 不足导致 buffer 分配失败 |
复盘本次排障，核心教训有两点：第一，raspi-config 在无头模式下偶尔不会正确写入设备树覆盖，手动编辑 /boot/config.txt 是更可靠的方案；第二，摄像头 buffer 分配失败往往被误判为驱动问题，实际是 CMA 内存不足，调整 cma 参数比增加 gpu_mem 更有效。建议在部署前将 cma=128 直接写入 /boot/config.txt，避免后续运行大型应用时出现隐性内存瓶颈。
gpu_mem 和 cma 为过大值，否则会挤压系统可用内存。对于 8GB 版本的 Pi 4B，建议 gpu_mem=64、cma=128；对于 4GB 版本，建议 gpu_mem=32、cma=64。修改后务必执行 sudo reboot 使配置生效。
2.5 常见误区与总结复盘
在环境准备阶段，以下误区会导致后续排障成本成倍增加：
- 误区一：使用 32-bit 系统。32-bit 内核无法访问超过 4GB 内存，且部分 Python 包（如 TensorFlow、PyTorch）已停止提供 armhf 轮子，导致依赖安装失败。务必选择 64-bit 镜像。
- 误区二：忽略电源质量。劣质电源导致的欠压问题会被误判为“系统不稳定”或“摄像头故障”。建议在
/boot/config.txt中添加avoid_warnings=1仅用于测试，生产环境应更换合格电源。 - 误区三：换源不彻底。只更换
sources.list而忽略raspi.list，会导致raspberrypi-kernel等固件包更新失败。同时，pip 源和 apt 源需要分别配置。 - 误区四：跳过系统更新。烧录后的镜像可能包含已知 bug，尤其是摄像头驱动和内核补丁。首次登录后应执行
sudo apt update && sudo apt full-upgrade -y，但需注意更新后可能需要重启。
总结而言，一个稳健的 Raspberry Pi 环境准备流程应遵循“硬件核对 → 镜像烧录 → 预配置 → 上电验证 → 换源更新 → 摄像头测试”的闭环。每一步都应有明确的验证标准，例如：SSH 连接成功、vcgencmd get_throttled 返回 0、libcamera-hello --list-cameras 列出设备。只有将这些基础打牢，后续的依赖安装、性能调优和摄像头应用开发才能建立在可靠的地基之上。