1. 为什么选择旧版本镜像：Python版本兼容性是关键

很多朋友第一次在树莓派上安装OpenCV和MediaPipe时，都会直接使用最新的树莓派系统镜像，结果发现各种报错层出不穷。我自己最初也是这样，折腾了好几天才发现问题出在Python版本上。最新的树莓派系统自带Python 3.11甚至更高版本，而这些新版Python与OpenCV和MediaPipe的兼容性并不理想，特别是在树莓派这种ARM架构的设备上。

这里有个很实际的问题：OpenCV和MediaPipe这些库都需要预编译的二进制包，而官方提供的预编译包通常只针对特定Python版本和系统架构。树莓派使用的是ARM架构，很多库都没有提供最新Python版本的预编译包，这就意味着你需要从源码编译，而这个过程在树莓派上可能需要几个小时甚至更久，而且很容易出错。

经过多次尝试，我发现使用自带Python 3.7的旧版系统镜像是最稳定的方案。Python 3.7是个很好的折中选择——既有足够新的特性，又有丰富的预编译包支持。具体来说，我推荐使用2023-02-21-raspios-buster-armhf这个镜像，这个版本的自带Python就是3.7.3，亲测安装OpenCV和MediaPipe非常顺利。

2. 镜像下载与验证：找到正确的版本

下载旧版镜像其实并不复杂，但需要知道去哪里找。树莓派官网提供了所有历史版本的镜像文件，我们可以直接访问官方的旧版本镜像仓库。这里有个小技巧：不要只看镜像的文件名，一定要查看对应的info文件，里面详细记录了每个镜像包含的软件版本信息。

打开镜像仓库页面后，你会看到很多以日期命名的镜像文件。找到2023-02-21-raspios-buster-armhf这个版本，下载对应的xz压缩文件。这个文件大概有400多MB，下载时需要一点耐心。下载完成后，你需要使用解压软件（如7-Zip或PeaZip）解压出img镜像文件，这个文件大概有3GB左右，确保你的磁盘有足够空间。

验证镜像的Python版本很重要。除了查看info文件外，你还可以在烧录系统后快速验证：启动树莓派，打开终端输入python3 --version。如果显示Python 3.7.x，说明你选对了镜像。这一步虽然简单，但能避免后续很多麻烦，我建议不要跳过。

3. 系统烧录与初始配置

烧录镜像到SD卡推荐使用Win32 Disk Imager，这个工具简单可靠。虽然树莓派官方也有烧录工具，但实测发现对旧版镜像的支持不如Win32 Disk Imager稳定。操作步骤很简单：插入SD卡，打开软件，选择解压出来的img文件，选择正确的驱动器盘符，然后点击Write即可。

烧录完成后，不要急着启动树莓派，还需要进行一些必要的初始配置。首先是在SD卡的boot分区创建两个文件：ssh和wpa_supplicant.conf。创建ssh文件时，只需要新建一个空文件，去掉.txt后缀即可，这个文件的作用是启用SSH服务。wpa_supplicant.conf文件则是配置WiFi连接，内容需要根据你的网络环境修改：

country=CN
ctrl_interface=DIR=/var/run/wpa_supplicant
update_config=1
network={
    ssid="你的WiFi名称"
    psk="你的WiFi密码"
    key_mgmt=WPA-PSK
}

这些配置完成后，将SD卡插入树莓派并通电启动。等待几分钟让系统完成初始设置，就可以进行下一步了。

4. 网络连接与系统更新

树莓派启动后，你需要找到它的IP地址才能通过SSH连接。推荐使用Advanced IP Scanner这类网络扫描工具，它可以扫描你局域网内的所有设备。树莓派的MAC地址通常以DC:A6开头，这个特征可以帮助你快速识别。

找到IP地址后，使用SSH客户端（如PuTTY或Windows Terminal）连接树莓派。默认用户名是pi，密码是raspberry。第一次连接时会提示安全警告，选择确认即可。

连接成功后，第一件事就是更换软件源，这会大幅提升后续的下载速度。树莓派使用的是APT包管理系统，我们需要将源更换为国内镜像。编辑/etc/apt/sources.list文件：

sudo nano /etc/apt/sources.list

将文件内容替换为：

deb http://mirrors.tuna.tsinghua.edu.cn/raspberry-pi-os/raspbian/ buster main non-free contrib rpi
deb-src http://mirrors.tuna.tsinghua.edu.cn/raspberry-pi-os/raspbian/ buster main non-free contrib rpi

接着编辑另一个源列表文件：

sudo nano /etc/apt/sources.list.d/raspi.list

内容改为：

deb http://mirrors.tuna.tsinghua.edu.cn/raspberrypi/ buster main ui

更新源列表并升级系统：

sudo apt-get update
sudo apt-get upgrade

这个过程可能需要一些时间，取决于你的网络速度。系统升级完成后，还需要配置pip源：

pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

5. OpenCV安装详解与依赖处理

安装OpenCV前需要先安装一些系统依赖库，这一步很关键，缺少依赖会导致编译失败或运行时错误。以下是必须安装的依赖包：

sudo apt-get install -y libopencv-dev python3-opencv
sudo apt-get install libatlas-base-dev -y
sudo apt-get install libjasper-dev -y
sudo apt-get install libqtgui4 -y
sudo apt-get install python3-pyqt5 -y
sudo apt install libqt4-test -y

这些依赖包包含了OpenCV运行所需的各种库文件，比如图像处理、矩阵运算、GUI支持等。安装过程中可能会遇到依赖冲突，通常按照提示运行apt --fix-broken install就能解决。

接下来需要更新numpy库。OpenCV对numpy版本有要求，太新或太旧都可能出现问题。建议使用以下命令：

pip3 install numpy --upgrade --ignore-installed

如果网络速度慢，可以尝试使用预编译的whl文件。我测试过numpy-1.21.5-cp37-cp37m-linux_armv7l.whl这个版本兼容性最好，下载后使用pip安装：

pip3 install numpy-1.21.5-cp37-cp37m-linux_armv7l.whl --upgrade --ignore-installed

现在可以安装OpenCV了：

pip3 install opencv-python

如果下载速度慢，同样可以使用预编译的whl文件。opencv_python-4.5.5.62-cp37-cp37m-linux_armv7l.whl这个版本经过测试很稳定：

pip3 install opencv_python-4.5.5.62-cp37-cp37m-linux_armv7l.whl

安装完成后验证一下：

python3 -c "import cv2; print(cv2.__version__)"

如果能够正常输出版本号，说明OpenCV安装成功。

6. MediaPipe安装与问题排查

MediaPipe的安装相对简单，但需要先确保OpenCV已经正确安装。首先安装一些必要的依赖库：

sudo apt install ffmpeg python3-opencv
sudo apt install libxcb-shm0 libcdio-paranoia-dev libsdl2-2.0-0 libxv1 libtheora0 libva-drm2 libva-x11-2 libvdpau1 libharfbuzz0b libbluray2 libatlas-base-dev libhdf5-103 libgtk-3-0 libdc1394-22 libopenexr23

这些库包含了多媒体处理、图形显示等各种功能支持。安装过程中如果遇到包找不到的情况，可能是源配置有问题，可以重新检查一下之前的源配置步骤。

对于树莓派4，直接使用以下命令安装MediaPipe：

sudo pip3 install mediapipe-rpi4

如果是树莓派3，则需要安装mediapipe-rpi3。安装过程可能需要几分钟，耐心等待完成。

验证安装：

python3 -c "import mediapipe; print('MediaPipe installed successfully')"

有时候可能会遇到一个常见的错误："TypeError: Descriptors cannot not be created directly"。这个问题通常是因为protobuf库的版本冲突，可以通过降级protobuf版本来解决：

pip3 install protobuf==3.20.3

7. 常见问题与解决方案

在实际安装过程中，可能会遇到各种问题。这里分享几个我遇到过的典型问题及解决方法。

内存不足错误：树莓派的内存有限，在安装过程中可能会因为内存不足而失败。可以通过增加交换空间来缓解：

sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# 将CONF_SWAPSIZE改为1024
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

依赖冲突：有时候不同的库需要不同版本的依赖包，可以使用virtualenv创建虚拟环境来隔离不同项目的依赖：

sudo pip3 install virtualenv
virtualenv opencv_env
source opencv_env/bin/activate

安装超时：由于网络原因，安装可能会超时。可以设置更长的超时时间：

pip3 --default-timeout=1000 install package-name

版本兼容性问题：如果遇到版本兼容性问题，可以尝试使用版本锁定的方式安装：

pip3 install opencv-python==4.5.5.62
pip3 install numpy==1.21.5

8. 环境测试与验证

所有组件安装完成后，需要进行全面的测试来验证环境是否正常工作。创建一个简单的测试脚本：

import cv2
import mediapipe as mp
import numpy as np

print("OpenCV version:", cv2.__version__)
print("MediaPipe version:", mp.__version__)

# 测试OpenCV基本功能
test_image = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)
gray = cv2.cvtColor(test_image, cv2.COLOR_BGR2GRAY)
print("OpenCV test passed")

# 测试MediaPipe基本功能
mp_hands = mp.solutions.hands
print("MediaPipe test passed")

print("All tests completed successfully!")

运行这个脚本应该能够正常输出各个库的版本信息，并且没有错误提示。如果一切正常，说明你的环境已经配置成功。

还可以进行更实际的测试，比如摄像头采集和图像处理：

import cv2
import mediapipe as mp

# 初始化摄像头
cap = cv2.VideoCapture(0)
if not cap.isOpened():
    print("Cannot open camera")
    exit()

# 测试摄像头采集
ret, frame = cap.read()
if ret:
    print("Camera test passed")
else:
    print("Camera test failed")

cap.release()

这些测试虽然简单，但能够验证核心功能是否正常工作。如果遇到问题，可以根据错误信息具体排查。