树莓派加 Python这个名字在爱好者和极客圈里响了十多年至今依然是动手学习编程最合适的一套组合。拿到一块树莓派你多半会先折腾 Linux 系统、接传感器、做点自动化小项目而这些玩法里 90% 的代码都能用 Python 搞定。这篇入门教程不搞花活就按我这些年实际操作的经验从选型、烧录系统、无屏幕启动到 GPIO 控制、摄像头拍照一路带着你把基础踩实。这篇文章适合谁完全没碰过树莓派、但有 Python 基础的新手或者买了一块板子却不知道从哪入手的半小白。你不需要懂底层电路不需要会写 C 语言只要会开电脑、能照抄命令就能跟着走完整个流程。等把系统刷好、点起第一颗 LED、用摄像头拍出第一张照片你对树莓派和 Linux 系统的基本认识就有了。1. 树莓派入门先别急着买想清楚你拿它干嘛1.1 树莓派 4B 和树莓派 5怎么选这几年最热门的两个型号是 4B 和 5。4B 是 2019 年发布的配置是四核 Cortex-A72 处理器最高 8GB 内存日常跑 Python 脚本、接摄像头、控制舵机完全够用。5 是 2023 年底发布的性能提升到了四核 Cortex-A76USB 3.0 口多了GPU 也升级了跑桌面系统、跑轻量级 AI 推理会比 4B 舒服很多。我的建议很简单如果你预算有限或者只是想要一块学习板4B 完全能陪你玩两三年市面上所有教程、代码、配件基本都基于 4B 写的资料铺天盖地遇到问题好搜。如果你打算把树莓派当小电脑用或者以后想跑一些人脸识别、语音识别之类的偏重任务直接上 5性能和 IO 接口都更宽松。这里特别提醒一句树莓派 5 换了新的 GPIO 驱动方案老库 RPi.GPIO 在 5 上兼容性一般需要用 gpiozero 或者其他新库这一点我在第四章单独说。同为 40Pin GPIO 接口物理外形、引脚定义基本一致4B 的老配件大多能用到 5 上但电源要求更高建议配 5V 5A 的官方电源别拿手机充电头糊弄。1.2 新手必须买的配件清单很多朋友第一次买树莓派只买了块裸板结果一到手发现没法开机又要单独买卡买线来回等快递很抓狂。入门口袋方案直接在买板子的时候配齐16GB 以上 TF 卡建议 Class 10 或 A1 级别容量别低于 16GB32GB 更从容读卡器用来给 TF 卡烧系统5V 3A 或 5V 5A 的 USB-C 电源适配器4B 用 3A5 用 5A中途换卡不换电源容易出玄学问题USB 键盘鼠标一套无线键鼠更省事一块 HDMI 小屏幕或者干脆先无屏幕通过 SSH 操作我用的是后者基础电子配件面包板、杜邦线若干、LED 灯珠、220 欧电阻、轻触按钮、舵机 SG90如果你完全不想买屏幕就跳到 2.2 节我会专门讲怎么无屏幕启动。1.3 入门阶段目标别定太大新手最不容易坚持下去的原因是目标定太高。我见过太多人一开始就想做自动驾驶小车结果代码还没跑通光调参就劝退了。入门阶段我的建议是把目标拆成三个小里程碑第一点亮一颗 LED能让它按你的节奏闪烁。第二用按钮控制 LED或者用 PWM 控制舵机转一个角度。第三摄像头拍一张照片或者录一段视频。三个里程碑跑完你对 GPIO、Python 库、Linux 命令行都会有大体认知后面再上什么项目都不慌。2. 烧录系统与无屏幕启动2.1 用 Raspberry Pi Imager 烧录系统Raspberry Pi 官方出过一款烧录工具叫 Raspberry Pi Imager现在 Windows、macOS、Linux 都能装。这个工具比老式 Win32DiskImager 方便太多内置了官方系统的下载、校验、烧录和初始化配置功能。下载之后打开操作流程是这样的选择设备型号比如 Raspberry Pi 4 或 5选择操作系统新手建议直接选 Raspberry Pi OS64-bit选择 TF 卡对应的盘符点击右下角齿轮图标做初始化配置这个选项经常有人漏掉但对我们无屏幕用户来说是最关键的一步烧录前系统会提醒卡上的数据会被清空点确认就行。整个过程通常几分钟取决于卡的写入速度。烧录完成后系统会把卡分区挂载回来这时候会看到 boot 和 rootfs 两个分区不要乱动先安全弹出。这里要提一个烧录报错的高频点很多人直接拿旧读卡器烧录速度慢不说还容易中途中断报错通常是 “write error” 或 “error while writing” 之类。解决办法很简单换一个支持 UHS-I 的读卡器别用几块钱那种杂牌货再把烧录软件更新到最新版。2.2 无屏幕启动SSH 和 Wi-Fi 提前配置无屏幕玩法核心思路是给树莓派预先配置好 Wi-Fi、SSH 和账号密码让它一开机就自动连网然后你用电脑远程登录。如果你用的是新版 Raspberry Pi Imager刷系统前在配置文件界面就能设置。需要填几个关键项设置主机名默认是 raspberrypi.local局域网里可以直接用这个域名访问开启 SSH选 “Use password authentication”或者更安全的密钥认证设置用户名注意新版系统默认用户名已经不是 pi 了必须自己设一个密码别设太简单配置 Wi-Fi填 Wi-Fi 名称和密码选好国家代码如果没有用 Imager或者想手动改也可以用旧方法把 TF 卡插回电脑在 boot 分区新建一个空文件文件名叫 ssh注意不带任何扩展名再把 Wi-Fi 配置写进 wpa_supplicant.conf 文件。但我个人建议用 Imager 的内置配置更稳定不容易踩权限和格式的坑。烧录完成后把卡插进树莓派接上电源等它启动。然后从电脑终端执行ssh 用户名raspberrypi.local首次连接会有 finger print 确认输 yes然后输入密码。如果 raspberrypi.local 无法解析多半是网络环境的分发机制问题可以直接到路由器后台看树莓派的 IP 地址再用 用户名IP 连接。联网之后先更新系统这是最基础也是最重要的一步sudo apt update sudo apt full-upgrade -y2.3 开机第一件事换源和改时区系统能跑起来第一步不是急着写 Python 代码而是先把软件源换成国内镜像否则 apt 下载速度会慢到怀疑人生。所谓换源就是把系统默认的软件包仓库地址指向国内维护的镜像站。Raspberry Pi OS 基于 Debian源配置文件在 /etc/apt/sources.list另外新版系统还有一个 /etc/apt/sources.list.d/raspi.list 文件。操作时先备份原文件sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo nano /etc/apt/sources.list把里面的内容替换成对应版本的镜像地址。树莓派官方系统的源地址格式大概是deb http://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/ bookworm main contrib non-free rpi注意版本代号不同系统的代号不一样bookworm 对应新版系统老版本可能是 bullseye 或 buster千万别看到教程就抄不匹配会报源错误只是白折腾。修改完执行sudo apt update sudo apt full-upgrade -y时区和本地化也要顺手调了。执行sudo raspi-config在面板里选 Localisation Options设置 Timezone 为 Asia/Shanghai键盘布局选 Generic 105-key (Intl) PC语言区域选 en_US.UTF-8 就行。如果中文系统还想装中文输入法可以装 fcitx5 和 fcitx5-chinese-addonssudo apt install fcitx5 fcitx5-chinese-addons -y重启后在输入法框架里切换到拼音或五笔就能打中文了。3. Python 环境与工具链3.1 系统自带的 Python 3 够用吗Raspberry Pi OS 默认已经安装了 Python 3终端输入 python3 --version 就能看到版本。对入门阶段来说系统自带 Python 完全够用你不需要任何安装操作。但有几个问题必须注意第一默认 Python 环境是干净的只带了一些基础包像 requests、opencv、gpiozero 这些常用库需要自己装。第二直接用 pip 安装库时系统会提示需要加 --break-system-packages 参数或者在虚拟环境中安装这是新版系统对外部管理 Python 环境做的保护。很多新手在这一步被卡住以为环境坏了其实不是。我的建议是别去跟系统 Python 环境硬碰硬更不要贸然把系统的 Python 版本升级或者把系统自带的 pip 换掉。树莓派的很多系统工具依赖特定版 Python你手动升级很容易把系统搞崩。Python 开发的事交给虚拟环境。所以如果你的目标只是先跑跑 GPIO 和摄像头那么系统自带 Python 3 apt 装库就够用如果你打算做一个正经项目需要管理多个第三方库那就必须上 venv。3.2 用 venv 做虚拟环境从第一天就养成习惯虚拟环境说白了就是给每个项目单独开一个隔离的 Python 空间项目 A 装了 requests 的 2.31 版本项目 B 可以装 3.0 版本互不干扰。创建和激活虚拟环境的命令非常简单mkdir my_project cd my_project python3 -m venv venv source venv/bin/activate激活成功后终端提示符前面会多出 (venv) 字样你在里面 pip 装的所有库都会进到这个环境目录中系统自带的 Python 环境完全不被污染。退出环境输入 deactivate 就行。有一点我吃过大亏树莓派本身内存不大别在 TF 卡上存放太多虚拟环境一个项目的环境一两百兆很常见。另外GPIO 和摄像头这类需要访问硬件的库例如 gpiozero、libcamera放在虚拟环境里通常也能正常工作因为它们底层依赖 nginx 其实不对底层依赖的是系统库文件Python 库只是封装层。碰到权限问题把当前用户加进相应的用户组即可。3.3 pip 源和常用库在国内用 pip 下载包同样会卡需要换成镜像源。在用户目录下创建 .pip/pip.confmkdir -p ~/.pip cat ~/.pip/pip.conf EOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple [install] trusted-host pypi.tuna.tsinghua.edu.cn EOF这样之后 pip install 下载包的速度会肉眼可见地提升。入门阶段常用库我列一份实际常用清单gpiozero控制 GPIO 的官方推荐库语法简单适合新手RPi.GPIO老牌库教程多树莓派 4B 上很好用5 上不推荐requests发 HTTP 请求配合接口做物联网项目Pillow图像处理库拍照之后做简单图像处理很方便smbus2操作 I2C 设备比如 OLED 屏幕、传感器opencv-python计算机视觉新手入门可以晚点再碰平时装库用 pip install 包名需要给某个项目装就先进那个项目的虚拟环境再装。建议在同一个终端里把 apt 安装系统库和 pip 安装 Python 库分开来遇到装 numpy 或 opencv 报错优先尝试 apt install python3-numpy 这种方式反而更省心。4. GPIO 编程实战从 LED 到舵机4.1 引脚图与两种 GPIO 库的取舍树莓派 40Pin GPIO 的引脚功能图在网上一搜一大把我建议你把它存在手机里接线时随时对照。因为 GPIO 引脚拿错非常容易烧坏传感器模块虽然板子大多有保护但确实有人就这么报废过。两种常见库的差异哈RPi.GPIO 用的是 BCM 编号直接按引脚功能编号控制比如 BCM17 对应物理 Pin11代码里用 17 来指代gpiozero 同样使用 BCM 编号语法更面向对象比如 Led 类、Button 类、Servo 类代码读起来像英语句子。在树莓派 4B 上两个库都用得很顺手但在树莓派 5 上官方很多示例已经开始转向 gpiozero 和基于 Linux 的 GPIO 子系统我建议新手直接学 gpiozero老教程如果遇到 RPi.GPIO 报错不要死磕把代码换成 gpiozero 实现一遍通常就通了。4.2 点亮第一颗 LED从零开始写硬件接线很简单LED 阳极接 GPIO17物理 Pin11阴极串联一个 220 欧电阻然后接到 GND物理 Pin6。电阻一定要接我之前偷懒不接电阻LED 亮是亮了但没几分钟就开始发烫再往后 GPIO 口也出问题了后来才知道是电流过大把引脚折腾得不轻。记一下 gpiozero 的代码from gpiozero import LED from time import sleep led LED(17) while True: led.on() sleep(1) led.off() sleep(1)保存为 led.py然后运行python3 led.py如果 LED 没亮第一件事检查连线第二件事检查代码文件夹目录、GPIO 编号别写错。gpiozero 最大的好处是回调简单旋转角度映射函数都内置了新手几乎不需要查底层寄存器的手册。还有一个高频问题运行 GPIO 代码时提示权限不足。解决方案是把当前用户加入 gpio 组sudo usermod -a -G gpio 用户名然后注销重新登录。树莓派默认把当前用户加进了一堆组但有些精简系统不会自动加遇到再说这招就行。4.3 按钮输入与轮询模式按钮控制的道理和 LED 反过来GPIO 引脚读取输入电平判断是高是低。电路接法按钮一端接 GPIO18物理 Pin12另一端接 GND再给 GPIO18 接一个 10K 上拉电阻到 3.3V或者干脆用 gpiozero 的内部上拉功能省掉电阻。代码from gpiozero import LED, Button from signal import pause led LED(17) btn Button(18, pull_upTrue) btn.when_pressed led.on btn.when_released led.off pause()这里用到了 gpiozero 的事件回调不用手动轮询程序一直挂在 signal.pause() 上等待事件。运行后按下按钮 LED 亮松开灭动作很直观。新手写到这里容易犯一个错误从网上抄来 RPi.GPIO 的轮询代码while True 里一直检测按钮状态CPU 占用率高点击响应也容易抖动。gpiozero 自带软件去抖处理只要不是特别变态的硬件抖动都不用自己写去抖函数。4.4 舵机控制与 PWM 频率调试从 LED 升级到舵机第一次接触 PWM脉冲宽度调制相当于用脉冲宽度来控制舵机转动角度。SG90 这类小型舵机的控制信号频率一般是 50Hz即周期 20ms高电平时间 0.5ms 对应 0 度1.5ms 对应 90 度2.5ms 对应 180 度。用 gpiozero 控制非常方便from gpiozero import Servo from time import sleep servo Servo(14) servo.min() sleep(1) servo.mid() sleep(1) servo.max() sleep(1) servo.detach()这里 Servo(14) 用 GPIO14物理 Pin8信号线接 GPIO14红线接 5V 电源棕线接 GND。SG90 的电源别直接接树莓派的 3.3V功率不够最好从 5V 引脚取电或者干脆用一个单独的 5V 电源给舵机供电地线要和树莓派共地。跑代码之前先用一个在线 PWM 或者直接跑上面代码看看舵机是否抖动、是否超出转动范围。sg90 的参数是 0 到 180 度gpiozero 的 Servo 默认映射到 -1 到 1如果你发现舵机到了某个位置狂抖通常是 PWM 信号的脉宽区间没设置对可以用 min_pulse_width 和 max_pulse_width 参数修正servo Servo(14, min_pulse_width0.0005, max_pulse_width0.0025)实际的脉宽范围还是以舵机说明书为准不要照抄我这里的值有些舵机 0.5ms 到 2.5ms 是错的可能已经超出物理范围了调试时一点点来。4.5 给小车留个伏笔电机驱动板与 L298N热门搜索里经常有树莓派小车、4WD 小车之类的词我提一个入门时容易忽略的点树莓派 GPIO 本身输出电流很小不能直接驱动电机必须用电机驱动板最常见的方案是 L298N 或者 TB6612FNG。接线时把树莓派 GPIO 引脚接到驱动板的 IN1~IN4电机接 OUT1~OUT4驱动板单独供电机电源树莓派和驱动板还是要共地。代码层面的核心也是 PWM不过不是控制舵机而是控制电机转速。左右轮速度不对称导致小车跑不直这是所有人都会遇到的问题解决方法是用两个变量分别微调左右轮的占空比没有捷径只能一点点调。入门阶段建议先把前面四章跑完小车项目可以放到后面专门开一个系列来写。5. 摄像头、USB 摄像头与简单媒体应用5.1 OV5647 摄像头模块安装树莓派官方摄像头模块用的传感器正是 OV5647500 万像素通过 CSI 排线连接到树莓派。安装时要断电操作先掰开 CSI 接口的卡扣排线蓝色端朝向 HDMI 方向插进去按下卡扣听到“咔哒”一声才是到位。排线接反是最常见的问题表现为系统认不到摄像头。装好之后新版系统推荐用 libcamera 命令族不用再折腾 raspistill 那些老命令了。输入下面命令确认系统能识别摄像头libcamera-hello --list-cameras如果能看到摄像头信息说明 CSI 识别正常。如果提示 no cameras available检查排线是否插紧、是否接反也可以尝试 raspi-config 里确认 Camera 接口已启用。摄像头预览窗口运行libcamera-hello -t 0拍照输出图像libcamera-still -o test.jpg录一段 10 秒视频libcamera-vid -t 10000 -o test.h264我日常测试摄像头的顺序就这套全部跑通摄像头这一关就算过了。注意 libcamera-still 拍完照片后终端会卡住一段时间这是正常现象等待照片生成就行很多新手在那疯狂按 CtrlC反而会中断保存过程。5.2 USB 摄像头与 luvcview如果你没有 CSI 摄像头用 USB 摄像头也能在树莓派上玩而且接法更无脑插上 USB 口就能用。查看视频流有个小工具叫 luvcview支持 UVC 协议的 USB 摄像头安装和使用都很简单sudo apt install luvcview -y luvcview -d /dev/video0 -s 640x480luvcview 适合快速验证摄像头能不能出图但如果你要做图像识别最好还是走 Python 方案用 OpenCV 打开摄像头。opencv 读取 USB 摄像头的代码非常简单只是树莓派上编译安装 opencv 比较慢建议直接用 apt 装系统编译好的包sudo apt install python3-opencv这条命令装的是 Python 3 的 OpenCV能省去几十上百分钟的编译时间初学者没必要为了最新版本折腾源码编译。5.3 用 Python 拍照把 OpenCV 接进来写一段通用的 Python 代码读取摄像头画面并保存照片import cv2 cap cv2.VideoCapture(0) if not cap.isOpened(): print(camera not opened) exit(1) ret, frame cap.read() if ret: cv2.imwrite(photo.jpg, frame) print(saved photo.jpg) cap.release()这个代码逻辑简单到没什么可拆的唯一要说的是 VideoCapture(0) 里的 0表示第一个摄像头设备如果你同时接了 USB 摄像头和 CSI 摄像头设备编号会变可能需要试 0、1、2 才能找到目标设备。树莓派跑 OpenCV 做实时人脸检测也完全可以但要调整图像尺寸把处理帧缩小一些别直接跑 1080p否则 CPU 占用直接拉满画面卡成幻灯片。这是所有新手都会踩的坑我当年第一次跑人脸检测就是拿着 1280x720 的帧死磕后来把帧缩到 640x480流畅度肉眼可见地提升。6. 常见问题与排查技巧实录6.1 新用户最容易踩的 6 个坑烧录、启动、写代码的过程中踩坑是正常的关键是知道坑在哪我整理了五个高频问题直接做成速查表问题可能原因解决思路上电后绿灯不亮电源功率不足或 TF 卡没插好换官方电源重新插卡上电后绿灯常亮但无法 SSH系统未预配置 SSH或 IP 变了检查 boot 分区是否有 ssh 文件重新查 IPapt update 卡住或报错软件源没换或版本代号不对换成国内镜像核对版本代号pip install 报 externally-managed系统保护机制创建 venv或加 --break-system-packagesGPIO 代码报权限错误当前用户不在 gpio 组usermod -a -G gpio 用户名重新登录libcamera 找不到摄像头CSI 排线没插好或系统没启用断电重插排线raspi-config 里启用 Camera这些坑没有一个需要高深知识才能解决大多是环境、权限、接口层面的小问题排查顺序永远从硬件连接开始再看软件配置最后看代码。6.2 几个我踩过的典型排查思路SSH 连不上的时候先别急着怀疑系统坏了。第一步查树莓派电源灯有没有稳定亮第二步查路由器后台有没有一个 IP 分配给树莓派第三步查防火墙和 MTU 之类的问题。说来好笑我遇到过一次连不上的原因是树莓派局域网里 IP 冲突换了固定 IP 之后立刻通了。烧录报错时大多数情况出在 SD 卡或者读卡器上。我处理过好几张烧录到一半就报错的卡换卡如换命直接把杂牌卡扔了换闪迪的 Ultra 系列再没出过问题。TF 卡的质量真的会影响系统稳定性别在卡上省钱。apt 软件源的问题最常见的是抄了其他教程的源但没核对系统版本。树莓派系统的版本代号可以从 /etc/os-release 文件里看或者执行 lsb_release -a 查看bookworm 是新的bullseye 是老一点的两个版本的源地址和组件名有不少差异照抄必踩雷。6.3 远程桌面与 ToDesk从命令行到图形界面很多新手不习惯纯命令行操作想直接看图形桌面。基础方案是用系统自带的 VNC在 raspi-config 里启用 VNC 服务然后用 VNC Viewer 连接。另一个选择是安装 ToDesk树莓派官方也支持直接下载对应的 arm64 版本安装包安装后用手机或电脑上控制很适合把树莓派放在角落里无头跑的场景。我个人的习惯是命令行为主图形界面为辅因为写代码、跑脚本、看日志命令行的效率比图形界面高太多。VNC 和 ToDesk 更像是应急和展示用的方案不是日常主力所以入门阶段不要求图形界面反而能逼自己把 Linux 命令练熟。结尾这套入门流程我前前后后给不下十个朋友讲过每次都会特别强调一点树莓派学习的关键不是这条命令、那段代码本身而是逐步建立“命令行 文件 Python 脚本”的思维模式。从一开始的烧录、配置、SSH到后面的 GPIO、摄像头、虚拟环境每一步都在为更复杂的项目打底子别急着跳步。如果让我只挑一条建议送给你那就是拿到手先把基础流程完整跑三遍第一遍看着教程做第二遍不看教程做第三遍尝试改参数、改代码看系统怎么响应。三遍下来你能把意外情况见个遍之后在任何社区提问都不至于像个完全不懂的门外汉。树莓派这东西玩的就是折腾的过程折腾明白了后面的大项目自然水到渠成。