Raspberry Pi Python GPIO 實作：用 LED、按鈕完成第一個硬體控制

你已經能在 Raspberry Pi 上執行 Python，下一步是讓程式「影響現實世界」。相較於直接把幾十個 GPIO 函式背起來，最有效的入門方式是做一個可以觀察、可以排錯、可以驗收的實驗：按住按鈕時 LED 亮起，放開時熄滅。這個小專案包含了感測輸入、程式邏輯、硬體輸出三個嵌入式系統的基本元素。

不過有一個比程式碼更重要的前提：Raspberry Pi GPIO 是 3.3V 邏輯，不是可以直接接 5V 的萬用電源孔。 初學者最需要先學的是安全接線。以下所有接線動作都應先切斷電源。

先了解 GPIO 與 BCM 腳位

樹莓派的 40-pin 排針有兩套容易混淆的編號：接頭上的「實體位置」與 GPIO 的 BCM 編號。例如 GPIO17 對應的是實體第 11 腳，而不是排針第 17 腳。接錯位置可能讓 LED 不亮，嚴重時可能損壞裝置。

建議在實際板子上執行：

pinout

把輸出的腳位圖和手上的板子方向逐項對照。若使用擴充板或不同型號，一定要回查官方 pinout，而不是憑印象插線。

第一個練習：讓 LED 閃爍

準備 Raspberry Pi 5、一顆一般 LED、一個約 220～330Ω 的限流電阻、杜邦線與麵包板。將 GPIO17（實體 11 腳）經限流電阻接至 LED 正極，LED 負極接 GND（例如實體 6 腳）。電阻要串在 LED 電流路徑中，不要把 LED 直接跨接 GPIO 與地。

在 Raspberry Pi OS 上確認 GPIO Zero 可使用；若尚未安裝，可優先透過系統套件管理器處理：

sudo apt update
sudo apt install python3-gpiozero

建立 blink.py：

from gpiozero import LED
from time import sleep

led = LED(17)
try:
    for _ in range(5):
        led.on()
        sleep(0.5)
        led.off()
        sleep(0.5)
finally:
    led.off()
    led.close()

執行 python3 blink.py。預期 LED 亮 0.5 秒、熄 0.5 秒，完成五個循環。程式使用 finally 關閉設備資源，降低中途出錯後腳位保持輸出狀態的風險。

這不是「連線到雲端」的實驗；即使沒有網路，只要已安裝相關套件，GPIO 控制仍然能在本機完成。

第二個練習：按下按鈕，讓 LED 亮起

接著加入一顆按鈕。示例選用 GPIO27（實體 13 腳）作為輸入，按鈕另一端接 GND。GPIO Zero 的 Button 預設使用上拉配置；一般情況下按下時讀值會改變。不同按鈕接腳排列可能不同，務必先確認按鈕內部哪兩腳在按下時導通。

建立 button_led.py：

from gpiozero import LED, Button
from signal import pause

led = LED(17)
button = Button(27)

button.when_pressed = led.on
button.when_released = led.off

try:
    pause()
finally:
    led.off()
    button.close()
    led.close()

執行：

python3 button_led.py

按下按鈕時 LED 應亮起，放開時熄滅。若按鈕出現反向效果，先檢查接線與 Button 的 pull-up 設定，而不是立即改動所有程式邏輯。

Raspberry Pi 5 的常見相容性問題

有些網路教學仍直接使用舊版 RPi.GPIO 方式操作。Raspberry Pi 5 的 GPIO 控制架構不同，GPIO Zero 官方指出，在 Pi 5 上應使用支援 lgpio 的 pin factory。若看見 BadPinFactory、找不到 GPIO chip 或套件相容性錯誤，請先查作業系統、GPIO Zero 與 lgpio 的版本，再查官方相容性說明。

另外，從 Raspberry Pi OS Bookworm 以後，系統 Python 被發行版管理，不應使用 sudo pip install 直接任意覆寫系統套件。一般 Python 專案應使用虛擬環境；控制 GPIO 所需的系統套件則優先採 apt。不要為了繞過 externally-managed-environment 就把 --break-system-packages 當作預設操作。

排錯順序：先硬體、再軟體

安全提醒： 本文僅示範低壓 LED 與按鈕。不要將馬達或繼電器線圈直接接 GPIO，也不要把外部 5V 訊號直接送入 3.3V GPIO。如涉及工業設備、危險電壓或機械動作，應採用隔離、保護與專業控制設備。

如何留下可信的實作證據？

真正的教學文章應區分「可參考的範例」與「已完成實機驗證」。可保存設備型號與 OS 版本、清楚的實際接線照片、程式版本、按鈕觸發短片，以及 LED 亮／滅結果。進階可加入輸入事件日誌，量測按鈕抖動與程式反應時間，但不可在沒有儀器實測時自行宣稱延遲或可靠度數字。

本文驗證狀態： 程式已製作為可檢查的示例，未由作者在實體 Raspberry Pi 5 接線重現；安全及相容性依官方文件建立。上架前如需標示「實測」，必須補足實機證據。

想先完成系統準備，請看 Pi 5 安裝教學；需要規劃 SSH、更新與安全則閱讀 Raspberry Pi OS 設定指南。亦可回到 Raspberry Pi 完整指南。

參考資料

1. Raspberry Pi 官方〈Raspberry Pi OS：Use GPIO from Python〉：https://www.raspberrypi.com/documentation/computers/os.html
2. Raspberry Pi 官方〈Raspberry Pi computer hardware：GPIO〉：https://www.raspberrypi.com/documentation/computers/raspberry-pi.html
3. GPIO Zero 官方〈Basic recipes〉：https://gpiozero.readthedocs.io/en/stable/recipes.html
4. GPIO Zero 官方〈Pin factories〉：https://gpiozero.readthedocs.io/en/stable/api_pins.html

資料查核日期：2026 年 10 月 21 日。