企业官网建设流程全解析

我至今还记得第一次把杜邦线往树莓派GPIO排针上插时的忐忑：金黄色的针脚密密麻麻排了两列，每个针脚旁边没有丝印标注，网上查来的引脚图要来回核对三四遍才敢接通电源。如果你也处在“树莓派买回来了，系统也装好了，但面对GPIO不知道从哪儿下手”的阶段，那么这篇就是为你准备的。GPIO（General Purpose Input Output，通用输入输出）是树莓派和物理世界对话的窗口，通过它，你可以让LED按你的节奏亮灭、读取按键和传感器的状态、控制舵机和电机。这篇文章是树莓派学习系列第7篇，我们一次性把GPIO基础捋清楚：引脚布局、Python操作、输入输出、PWM，以及我这些年踩过的坑。

先从原理入手，再上实操，最后给一套可以直接抄的排查思路。这样即便你没学过电子电路，也能在半小时内把第一颗LED点亮。

1. GPIO到底是什么：别把它想成神秘引脚

1.1 输入输出：每个引脚本质上是一个可编程的开关和电表

很多初学者把GPIO想象成一种需要“驱动”或“协议”的东西，其实没那么玄乎。GPIO的每一个引脚，在芯片内部就是一组可以配置的寄存器。你把它配置成输出模式，它就像一个小型开关，由程序决定对外输出高电平（3.3V）还是低电平（0V）；你把它配置成输入模式，它就像一块电压表，程序去读取这个引脚上当前是3.3V还是0V。

这里有个关键点：树莓派的GPIO输出的是3.3V，不是5V。Arduino的引脚输出是5V，很多新手把Arduino的习惯带过来，直接用树莓派GPIO去驱动5V继电器模块，或者给某个传感器供电，结果轻则读不到信号，重则烧掉引脚。后面我会专门讲电压和电流红线，这里先记住这个核心差异。

树莓派的Linux系统把所有GPIO都抽象成了文件或设备节点，Python库又把这些节点封装成几个函数。所以你不用关心底层寄存器怎么操作，但理解“输入/输出”的本质，能帮你后续排查问题。另一个容易混淆的点是：有些教程会提到“GPIO的8种工作模式”，这个说法经常被搜索引擎归结到树莓派头上，但严格说它来自STM32那类单片机的GPIO配置（输入浮空、输入上拉、输入下拉、模拟输入、开漏输出、推挽输出、推挽复用、开漏复用）。树莓派的Linux GPIO并没有暴露这么细的模式，RPi.GPIO库一般只区分INPUT、OUTPUT、PWM、软件中断等。别被这个概念带偏，先把最常用的输入和输出玩熟。

1.2 40Pin排针：先记住电源和地，再记编号

树莓派从1代到4代，物理接口基本都保持40Pin排针（早期的26Pin版本不算），1代B+之后都是40Pin。板子拿在手里，让USB接口朝下、GPIO排针在右上角，从左上角开始数，靠近外侧的是第1针，内侧是第2针，一行行往下就是双排共40根针脚。这个物理编号叫BOARD编号，从1到40。

第一次接触时不要试图背下40个引脚，只记几根关键针脚就够了：

• 第1针：3.3V电源
• 第2针、第4针：5V电源
• 第3、5、7、9等若干针：GND地线
• 剩下的大部分是GPIO引脚，其中很多还复用I2C、SPI、UART等串行接口功能

为了直观，你把引脚图下载下来或者用pinout命令查看。在终端里输入pinout，系统会直接打印出一张引脚功能图，标注每个物理针脚的编号、BCM编号、I2C/SPI/UART复用功能。这个小工具比对着网上图片方便很多，树莓派官方系统自带。

我自己的经验是：接线之前先用笔在纸上列出你本次要用哪几个引脚，比如LED接GPIO 17，按键接GPIO 27，然后对照引脚图找到对应的物理针脚位置，再动手插线。不要边插边想，不然很容易错位。

1.3 GPIO编号体系：BCM和BOARD为什么让人头疼

你会在所有树莓派教程里看到两种编号方式：BOARD和BCM。BOARD编号就是物理针脚号码，1到40，从左上角一路排下来。BCM编号则是博通SoC内部的GPIO号，比如GPIO 17在物理上对应第11针，GPIO 27对应第13针。同一个引脚，两个编号，新手就在这上面栽跟头。

举个例子：在代码里写GPIO.setmode(GPIO.BCM)然后用GPIO.output(17, True)，点亮的是物理第11针；如果写的是GPIO.setmode(GPIO.BOARD)，再用GPIO.output(11, True)，效果相同。最典型的错误是模式设成BCM，却把物理针脚号当参数传进去，结果控制了一个完全不同的引脚，板子没反应还以为是硬件坏了。

我的建议是统一用BCM编号。原因有三：第一，绝大多数传感器示例代码都用BCM；第二，BCM编号和芯片数据手册对应，查资料方便；第三，wiringPi编号在树莓派4B上已经基本没人用了，没必要学。记住：setmode必须在所有setup和output调用之前执行，否则代码会报错提示你没有设置模式。

2. 环境准备：一条命令装库，先跑通首个程序

2.1 确保系统是官方系统，Python版本不是障碍

我默认你已经在树莓派上装好了官方系统，不管是Raspberry Pi OS还是Ubuntu Server。树莓派官方系统通常自带Python 3，版本在3.7到3.11不等，这不重要，因为我们要用的RPi.GPIO库是老牌库，兼容性很稳定。唯一要确认的是系统能联网，因为我们需要安装一个Python库。如果是在校学生用的是预装了系统的SD卡，建议先跑一遍sudo apt update && sudo apt upgrade把系统包更新干净，再安装后面的库。这一步能减少很多莫名其妙的“Permission denied”和“ModuleNotFoundError”。

顺便说一句，直接连键盘显示器是最省事的操作方式。如果手里只有笔记本，也可以通过SSH远程登录，GPIO操作和本机执行没有任何区别。远程操作时需要注意：如果程序在SSH会话里跑着，只要那个会话一断，程序就停了。想要断电后自动跑，后面可以再学systemd服务或者cron，本文先不展开。

2.2 安装RPi.GPIO（以及树莓派5的替代方案）

在终端里执行：

sudo apt update sudo apt install python3-pip sudo pip3 install RPi.GPIO

有些预装系统可能已经包含了RPi.GPIO，你可以先跑一句python3 -c "import RPi.GPIO as GPIO; print(GPIO.VERSION)"试试。如果输出版本号，说明已经装了。

这里要特别提醒：如果你用的是树莓派5，事情会有点不一样。树莓派5换用了RP1芯片来管理外设，老牌的RPi.GPIO库官方已经明确不再适配树莓派5。在树莓派5上直接import RPi.GPIO会报错或者无法正常工作。社区给的替代方案有两个：一个叫rpi-lgpio，它把RPi.GPIO的API重新实现了一遍，老代码基本不用改；另一个叫gpiod，是更接近Linux内核风格的库，API更复杂但更正规。我建议树莓派5用户先装rpi-lgpio：

sudo pip3 install rpi-lgpio

然后把import RPi.GPIO换成import lgpio as GPIO？不对，rpi-lgpio安装后依然提供RPi.GPIO模块名，所以代码不用改。我自己实测时，直接用import RPi.GPIO也能跑起来，因为rpi-lgpio会注册兼容入口。如果你在树莓派5上遇到老代码报错，优先尝试这个库。

2.3 第一个程序：点亮一颗外接LED

硬件准备：一颗普通发光二极管、一个220Ω到1kΩ的电阻、两根公母杜邦线。先把电阻串在LED的任意一端，然后把电阻的另一端接到某个GPIO引脚（我用BCM 17，物理第11针），LED的另一端接到GND。别看这个电路简单，电阻不是可选项。后面我会详细说电阻的取值逻辑，这里先按标准接法做。

然后新建一个文件led_test.py：

import RPi.GPIO as GPIO import time LED_PIN = 17 GPIO.setmode(GPIO.BCM) GPIO.setup(LED_PIN, GPIO.OUT) GPIO.output(LED_PIN, GPIO.HIGH) time.sleep(3) GPIO.cleanup()

保存后运行：

python3 led_test.py

你应该能看到LED亮3秒后熄灭。如果灯没亮，不要急着怀疑代码，先检查接线：LED的极性对不对？发光二极管长脚是阳极，要接电阻后接到GPIO；短脚是阴极，接GND。如果接反了，灯不会亮，但通常不会烧东西。另外，确认杜邦线有没有插到正确的物理针脚上，我一再强调这一点，因为太多的“程序没反应”最后都是接错针脚。

2.4 代码逐行解释

逐行看这段代码：第一行导入RPi.GPIO模块，并给它起了一个缩写叫 GPIO，后面所有调用都基于这个别名。time用来延时。LED_PIN = 17是我们选用的BCM引脚号，等会儿换引脚，只改这一行就行。GPIO.setmode(GPIO.BCM)告诉库我们使用BCM编号体系，它决定了后面所有引脚号的意义。GPIO.setup(LED_PIN, GPIO.OUT)把该引脚设置为输出模式，相当于把芯片内部的开关切换到输出挡位。GPIO.output(LED_PIN, GPIO.HIGH)输出高电平，此时引脚对外是3.3V，电流流过LED，灯就亮了。time.sleep(3)保持这个状态3秒。最后的GPIO.cleanup()把引脚恢复为输入模式，释放资源。

有一个让很多人困惑的点：为什么点亮LED后要延时再cleanup()？因为如果不延时，程序瞬间结束，LED一亮就灭，肉眼可能根本没看到。而cleanup()会把所有引脚恢复为输入模式，相当于切断输出，所以灯灭了。如果代码在最后没有cleanup()，程序退出后引脚会保持你最后设置的电平状态，灯会一直亮着。这既可能是好事也可能是坏事，后面会专门讨论。

3. 输出模式：从“亮一下”到“按你的节奏闪烁”

3.1 限流电阻怎么选：不是随便一个电阻都行

GPIO输出高电平时，引脚上本质是输出一个3.3V的电压。如果直接把LED接到GPIO和GND之间，LED正向导通电阻很小，流过的电流会非常大，轻则LED烧毁，重则损坏树莓派的引脚。所以必须串联一个限流电阻。欧姆定律：R = (V_GPIO - V_LED) / I_LED。普通红色LED的正向压降大约1.8V到2.0V，蓝白LED大约3.0V到3.3V，工作电流一般取5mA到20mA。

以红色LED、希望电流10mA计算：R = (3.3 - 1.9) / 0.01 = 140Ω。所以选220Ω到470Ω都没问题，电流会偏小一些，LED不会像手电筒那么亮，但完全能看清，而且对引脚更安全。我之前写过一版用100Ω电阻的代码，灯是很亮，但手指摸到电阻表面都能感觉到温升。后来统一改成330Ω，安稳很多。记住：树莓派单个GPIO最大安全输出电流大约是16mA，不要超过这个值。如果你看到教程里有人直接不接电阻把LED接到GPIO上，那是在燃烧板子的寿命。

另外，如果你要驱动继电器、电机、蜂鸣器这类大电流设备，不能直接接GPIO，必须通过三极管、MOS管或者专门的驱动模块。这一点我在后面的坑位章节会再强调。

3.2 用循环写一个闪烁灯

闪烁的本质就是让GPIO以一定时间间隔交替输出高电平和低电平。把刚才的代码稍作修改：

import RPi.GPIO as GPIO import time LED_PIN = 17 GPIO.setmode(GPIO.BCM) GPIO.setup(LED_PIN, GPIO.OUT) try: while True: GPIO.output(LED_PIN, GPIO.HIGH) time.sleep(0.5) GPIO.output(LED_PIN, GPIO.LOW) time.sleep(0.5) except KeyboardInterrupt: pass finally: GPIO.cleanup()

这次代码里加了try/except/finally。KeyboardInterrupt是当你按下Ctrl+C终止程序时抛出的异常，except捕捉到之后跳过循环，进入finally块执行GPIO.cleanup()。这样程序终止后LED会熄灭，引脚不会在异常退出时保持高电平，也方便下次运行。

很多新手看到这个结构觉得多余，直接写了while True没有异常处理，结果程序一旦报错，LED永远亮着，引脚也被系统占用，再运行程序就报RuntimeError: Port already in use。所以从第一课开始，就养成try/except/finally的习惯，能少踩很多坑。

3.3 把LED控制封装成函数，之后项目复用

学到这里，你可以把LED操作封装成一个小函数，让代码更清晰：

import RPi.GPIO as GPIO import time def led_init(pin): GPIO.setmode(GPIO.BCM) GPIO.setup(pin, GPIO.OUT) def blink_led(pin, on_time=0.5, off_time=0.5, count=10): for _ in range(count): GPIO.output(pin, GPIO.HIGH) time.sleep(on_time) GPIO.output(pin, GPIO.LOW) time.sleep(off_time)

封装不是为了炫技，而是当你手头有3个LED时，不会在主程序里写20行重复的output调用。后面做智能小车、家居项目时，这种小块函数都能直接复用。我自己的项目模板里都会放一个gpio_utils.py，把LED、按键、蜂鸣器的基础操作都写进去。当然，封装过度也不行，项目大了之后直接用面向对象写硬件驱动类更合理。这篇先讲基础，不展开。

4. 输入模式与按键消抖：读电平容易，读“真”难

4.1 浮空引脚为什么不能直接读

输入模式的应用场景是读取外界状态，比如按键是否被按下、传感器输出是高还是低。最简单的办法是读取引脚电平。先别急着写代码，你要理解引脚悬空的问题。所谓悬空，就是引脚没有接任何确定电压来源，只接着一根杜邦线，线的另一端悬在半空。

此时你用GPIO.input(pin)去读，读到的值是不确定的，有时候是高，有时候是低，甚至手指靠近一点都会变。这是因为引脚自身有很高的输入阻抗，周围电磁噪声很容易耦合进去。所以做输入检测时，不能让引脚悬空，必须通过一个电阻把它稳定在确定的电平上，这个电阻就叫上拉电阻或下拉电阻。

4.2 外部上拉/下拉和内部上拉怎么选

先说外部上拉：在GPIO引脚和3.3V之间接一个10kΩ电阻，平时引脚被拉到高电平。当按键按下后，引脚被按键接到GND，电平变成低。这样程序读到低电平时就知道按键被按下了。如果把电阻接到GND就叫下拉电阻，平时低电平，按下后变成高电平，程序就要反过来判断。

树莓派内部其实已经集成了可配置的上拉/下拉电阻，所以在RPi.GPIO中不需要外接电阻就能实现上拉效果：

GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_down=GPIO.PUD_UP)

这行代码把引脚配置成输入，并启用内部上拉。此时按键的一端接GPIO引脚，另一端接GND。平时引脚为高电平，按下时引脚为低电平。用内部上拉的好处是省一个电阻，坏处是内部上拉电阻的阻值很大（大约50kΩ左右），抗干扰能力不如外部10kΩ电阻。如果按键引线特别长，或者环境里有大功率电机干扰，建议用外部上拉电阻。

另外有个初学者特别容易踩的点：按键用内部上拉时，另一端必须接GND，不是接3.3V。如果按键另一端接到3.3V，按下后引脚就变成高电平，由于内部上拉也是高电平，等于按键完全没作用。反过来，如果启用内部下拉，按键另一端要接3.3V。

4.3 消抖：按键按一下，程序读成十下的原因

机械按键在按下和松开的时候，金属触点并不是一次性稳定接触，而是会在几毫秒到几十毫秒内反复弹跳。你明明只按了一下，程序可能读到几次甚至十几次电平跳变。如果不做消抖，计数器会乱跳，这是所有初学者都会遇到的现象。

最简单的软件消抖是延时判断：

import RPi.GPIO as GPIO import time BUTTON_PIN = 27 LED_PIN = 17 GPIO.setmode(GPIO.BCM) GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_down=GPIO.PUD_UP) GPIO.setup(LED_PIN, GPIO.OUT) while True: if GPIO.input(BUTTON_PIN) == GPIO.LOW: time.sleep(0.05) # 跳过抖动窗口 if GPIO.input(BUTTON_PIN) == GPIO.LOW: GPIO.output(LED_PIN, not GPIO.input(LED_PIN)) while GPIO.input(BUTTON_PIN) == GPIO.LOW: time.sleep(0.1)

这段代码做的逻辑是：先读到低电平，等待50毫秒；如果50毫秒后还是低电平，说明不是噪声，确实是按键按下了。然后切换LED状态，并检测按键是否松开，防止一按下去就多次触发。

50毫秒这个值是我的经验值。机械按键的抖动一般在10到20毫秒内结束，取50毫秒已经有足够余量。要是你的按键接了一段很长的线，抖动会更严重，可以把延时调到100毫秒。但这种time.sleep消抖方式有个缺陷：延时期间程序是阻塞的，其他任务都停了。如果项目里同时要处理多个按键，或者要控制多个LED闪烁，阻塞式消抖会让系统显得卡顿。更专业的做法是用状态机或者边沿检测，后续可以单独写一篇，这里先把最基础的做法吃透。

5. PWM：呼吸灯、舵机和调光的基础

5.1 占空比与频率：PWM不是模拟电压

PWM的全称是脉宽调制，简单说就是让引脚以极高的频率在高低电平之间切换。LED看到的不是一个稳定的3.3V，而是一串方波。人眼有视觉暂留效应，只要切换频率够高，看到的就是一个亮度固定的灯。改变高电平在一个周期内占的比例，也就是占空比，就能改变亮度。

举例：周期是10毫秒，其中高电平占3毫秒、低电平7毫秒，占空比就是30%。LED亮度大约只有最大亮度的30%。如果高电平占8毫秒，占空比80%，灯就明显更亮。这里必须澄清一个概念：PWM不是模拟电压，虽然两者最终效果在某些场合看起来一样，但本质上一个持续输出2.4V的电源和一个以80%占空比高速切换的3.3V方波，在电气特性上是完全不同的。LED可以用PWM，电机可以用PWM，但如果你要驱动一个需要精确模拟电压的电路，不能直接拿PWM输出接上去，后面要加滤波器。

5.2 用RPi.GPIO控制PWM输出

RPi.GPIO里的PWM使用非常简单：

import RPi.GPIO as GPIO import time LED_PIN = 17 GPIO.setmode(GPIO.BCM) GPIO.setup(LED_PIN, GPIO.OUT) pwm = GPIO.PWM(LED_PIN, 50) # 50Hz频率 pwm.start(0) # 初始占空比0% for duty in range(0, 101, 5): # 从0到100，步进5 pwm.ChangeDutyCycle(duty) time.sleep(0.05) time.sleep(1) for duty in range(100, -1, -5): pwm.ChangeDutyCycle(duty) time.sleep(0.05) pwm.stop() GPIO.cleanup()

这段代码实现了呼吸灯效果：LED先慢慢变亮，再慢慢变暗。50Hz是电源频率附近，人眼基本感觉不到闪烁。有些对闪烁敏感的人可能还是能察觉，可以提高到1kHz，LED表现更稳定。注意，RPi.GPIO的PWM是软件PWM，启动后依赖于系统调度，如果你同时跑很多程序，PWM波的抖动会变大。如果项目对PWM频率精度要求很高，比如舵机控制，推荐用树莓派硬件PWM，或者干脆换树莓派Pico。但基础学习和普通调光，软件PWM足够了。

5.3 从呼吸灯到舵机：PWM的典型应用边界

舵机是PWM应用的经典场景。标准舵机接收的PWM信号频率是50Hz，整整20毫秒为一个周期，高电平脉冲宽度通常从0.5毫秒到2.5毫秒，对应舵机从0度转到180度。把50Hz和0.5ms到2.5ms结合来看，占空比大约在2.5%到12.5%之间。所以控制舵机不是简单地设置一个占空比，而是要根据脉宽换算。

这里有个容易忽略的坑：树莓派的GPIO逻辑电平是3.3V，但很多常见的SG90舵机标称工作电压是4.8V到6V，它的信号线也经常被设计成5V逻辑。直接用树莓派3.3V GPIO信号去控制5V供电的舵机，大多数情况下能工作，因为舵机芯片的输入高电平阈值没有那么高。但稳妥起见，最好用电平转换模块或确认舵机兼容3.3V逻辑。反过来，绝对不能把舵机的5V电源接到树莓派GPIO上给系统供电，舵机瞬间电流可以到几百毫安甚至更高，会把树莓派搞重启甚至烧掉。舵机要单独用外部5V电源，并且电源地要和树莓派的地线共地，否则信号参考电位不一致，舵机就不受控。

5.4 树莓派Pico和标准树莓派的PWM差异

搜索树莓派相关内容时，你经常会看到“树莓派Pico控制舵机”这种题目。Pico是树莓派家族里的微控制器开发板，不是标准树莓派单板计算机，它的GPIO操作方式和本篇讲的标准树莓派完全不同。Pico用的是MicroPython或C语言，没有Linux系统，GPIO控制更接近单片机，PWM精度也比标准树莓派的软件PWM高得多。如果你只是想做一个小型、低功耗、实时的硬件控制项目，Pico反而比标准树莓派更适合，成本也低很多。但如果你需要同时跑摄像头、网络、数据库这些Linux服务，双系统协同才是更优解。Pico的具体玩法可以留到系列后续再单独拆解，这里先把标准树莓派的GPIO基础打牢。

6. 综合练习：做一个按键控制亮灭的智能小夜灯

6.1 硬件连接

理论学再多，不如动手做一个能用的东西。这个综合小项目很简单：一个按键控制LED的亮灭，按一下亮，再按一下灭。硬件清单：树莓派任意型号、一个LED、一个330Ω电阻、一个轻触按键、若干杜邦线。

连接方式如下：

• LED阳极（长脚）通过330Ω电阻接到BCM 17（物理第11针），阴极接GND
• 按键一端接BCM 27（物理第13针），另一端接GND
• 不需要外接上拉电阻，因为代码里启用内部上拉

接线前先断电或者至少确认不会误碰其他引脚。我习惯在板子通电的情况下接线，但每次都要非常小心，避免杜邦线搭到5V和3.3V之间造成短路。如果你是新手，建议给板子断电再插线，插完后检查一遍再通电。

6.2 软件逻辑

完整代码如下，它结合了输出、输入、内部上拉和消抖：

import RPi.GPIO as GPIO import time LED_PIN = 17 BUTTON_PIN = 27 GPIO.setmode(GPIO.BCM) GPIO.setup(LED_PIN, GPIO.OUT) GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_down=GPIO.PUD_UP) led_state = GPIO.LOW try: while True: if GPIO.input(BUTTON_PIN) == GPIO.LOW: time.sleep(0.05) if GPIO.input(BUTTON_PIN) == GPIO.LOW: led_state = not led_state GPIO.output(LED_PIN, led_state) while GPIO.input(BUTTON_PIN) == GPIO.LOW: time.sleep(0.1) except KeyboardInterrupt: pass finally: GPIO.cleanup()

注意看按键检测逻辑里的第二个while：它一直等到按键松开才继续判断下一次按键。这样设计是为了防止长按按键时LED反复切换。如果你希望实现“按住点动”效果，可以把这行去掉，改成按键按下时LED亮、松开时LED灭，那是另一种玩具玩法。

运行这段代码，按下按键，LED应该切换状态。如果按键不灵敏，多半是消抖时间不够，把0.05改成0.08试试。如果LED不亮，就用万用表量一下GPIO 17有没有3.3V输出。没有万用表的话，先用前面学过的点亮LED测试代码单独验证硬件是否正常，逐段缩小问题范围。

6.3 试试改进方向

这个小项目做完，你已经掌握了GPIO最核心的输入输出能力。在此基础上可以做很多扩展：

• 把LED换成有源蜂鸣器，模块的地线接GND，信号线接GPIO，就能做按键门铃
• 加两个LED，配合红绿灯逻辑，做一个简单交通灯演示
• 按键长按和短按区分处理，也就是在消抖后继续计时，检测按下时长，这能在同一个按键上实现不同功能
• 用PWM控制LED亮度，让按键每按一次亮度提升一档

我一直觉得，学习硬件编程最好的路径就是“先做个能亮的东西，再在它旁边加功能”。一开始不用追求复杂的传感器，把输出和输入这两种最基础的模式玩透，之后读温度传感器、接超声波模块都会水到渠成。

7. 新手最容易遇到的GPIO坑与排查方法

7.1 引脚烧毁的常见原因

GPIO引脚烧毁通常是电流过大或电压超限。树莓派GPIO虽然内部有保护电路，但不要把它当成金刚不坏之身。最容易出问题的操作如下：

• 直接把LED接到GPIO和3.3V之间而不接电阻
• 用GPIO直接驱动继电器线圈或直流电机
• 把5V电源接到3.3V的GPIO引脚上
• 将两个GPIO输出引脚短接在一起，一个输出高电平另一个输出低电平，会形成直通电流

其中把5V接到GPIO引脚上是杀伤力最大的。树莓派的引脚对3.3V以上的电压非常敏感，5V信号进入GPIO会直接击穿引脚内部的保护二极管。如果你要接5V逻辑的设备，务必用双向电平转换模块。

如果真的烧坏了引脚，通常不是整个树莓派报废，而是某个或者某几个GPIO通道损坏。树莓派上的损坏是不可逆的，只能绕开这些引脚换用别的GPIO。我自己的板子就烧过一个引脚，后来一直用一个“禁用了坏引脚”的脚本做保护。当然，最稳妥防烧的办法是接一个GPIO保护扩展板，几十块钱，能省下换板子的钱。

7.2 GPIO.cleanup()不能乱写的原因

前面代码里几乎每次都在最后调用GPIO.cleanup()，它会把所有GPIO恢复为默认输入状态。这在开发阶段很方便，但也有个坑：当你的程序已经调用cleanup()后，如果之后又尝试操作某个引脚，会报错或直接跳过。更麻烦的是，如果你同时运行两个操作GPIO的Python程序，一个程序执行了cleanup()，会把另一个程序初始化的引脚也重置掉，导致另一个程序莫名其妙失效。

正确的做法是：只在程序退出时调用cleanup()，并且尽量只清理自己用的引脚。比如可以写成GPIO.cleanup([LED_PIN, BUTTON_PIN])，只传引脚列表，这样不会影响其他程序。如果程序需要长时间运行（比如服务器），则一般不主动调用cleanup()，让它保持初始化状态即可。

7.3 程序假死、权限不足、引脚被占用

刚接触GPIO时，你是不是遇到过这种情况：程序运行后看起来就像卡住了，键盘Ctrl+C也没反应。这多半不是树莓派死机，而是你的GPIO程序进入了死循环，同时异常处理没写好，导致无法正常退出。可以另开一个SSH终端，执行sudo pkill -f 你的脚本名.py把进程杀掉。如果是因为GPIO引脚被前一个没退干净的程序占用，重启一下Python进程通常能解决，终极办法是重启树莓派。

另一个常见错误是RuntimeError: Not running as root。旧版RPi.GPIO库在某些系统上需要root权限访问 /dev/mem 或 /dev/gpiomem，默认用户没有权限。解决办法是执行程序时加sudo，或者把自己的用户加入gpio组。不过官方Raspberry Pi OS较新版本已经把 /dev/gpiomem 的权限放开了，普通用户可以直接访问GPIO，一般不需要sudo。如果你在Ubuntu上遇到权限问题，加sudo是最快的办法。

引脚被占用时通常会报RuntimeError: Port already in use或者类似的“gpio busy”错误。排查时可以执行gpio readall（如果安装了wiringPi）或者pinctrl get 17查看引脚当前状态。更好的习惯是在写代码前先检查有没有其他进程占用你计划使用的引脚。

7.4 排查问题的小工具

GPIO问题排查，我最常用的顺序是：

1. 用pinout命令确认引脚位置
2. 用python3 -c "import RPi.GPIO as GPIO; GPIO.setmode(GPIO.BCM); GPIO.setup(17, GPIO.OUT); GPIO.output(17, GPIO.HIGH)"快速测试引脚是否能输出高电平
3. 用万用表量引脚和GND之间是否有3.3V
4. 检查接线图有没有接错，特别是电源和地的位置
5. 写出最小化测试代码，排除业务逻辑干扰

如果你没有万用表，可以外接一个带指示灯的模块，比如LED模块，直接看是否有电压输出。这个方法简单粗暴，但确实能帮你快速区分“程序问题”和“硬件问题”。

还有一个实用工具是pinctrl，树莓派官方系统自带，可以查看和修改引脚复用状态。比如pinctrl get 17能显示第17号引脚的当前功能和电平。这个工具比直接看电气图直观，在排查引脚被复用为其他功能时特别管用。

回看我最早学树莓派GPIO的经历，真正让人进步的并不是记住某个函数，而是日常积累下来的这些“为什么”。为什么这个灯要接电阻，为什么按键要上拉，为什么程序退出要cleanup。搞清楚这些底层逻辑，后面学任何传感器、任何外设模块都能触类旁通。如果你照着这篇文章把LED和按键的例子跑通了，GPIO基础这一关就算过了，接下来可以去碰I2C、SPI这些串行协议，也可以回头研究树莓派小车这类综合项目。希望这篇能帮你少烧几块板子，多找点乐趣。