1. 项目概述与核心价值

手头有个树莓派Zero W，总想给它接个小屏幕，做个便携信息终端或者迷你监控面板。市面上1.8寸的SPI接口LCD屏价格很友好，ST7735又是其中非常常见的驱动芯片，按理说资源应该很多。但真动手的时候才发现，网上教程虽多，但芯片型号、屏幕分辨率、树莓派型号稍有不同，直接照搬大概率会卡在某个环节，不是点不亮就是显示错位。我自己就折腾了好一阵，才把一块128x160分辨率的ST7735屏在运行Bookworm系统的树莓派Zero W上完美驱动起来。

这篇指南就是把我踩过的坑、验证过的步骤和关键的配置修改点全部整理出来。如果你手头正好是树莓派Zero W（或Zero 2 W）和一块1.8寸128x160的ST7735屏，那么跟着做，大概半小时就能让屏幕亮起来，显示自定义的图片和文字。整个过程会涉及硬件接线、系统SPI接口启用、Python环境下的库安装（这里有个Bookworm系统带来的大坑），以及针对非标准分辨率屏幕的库文件修改。最终的目标是让你不仅能把屏幕点亮，更能理解每一个步骤背后的原因，以后遇到类似的SPI设备也能举一反三。

2. 硬件准备与接线解析

驱动一块SPI屏幕，第一步也是最容易出错的一步就是接线。线接错了，后面所有软件配置都是徒劳。树莓派Zero W的GPIO引脚和常见的40针全尺寸树莓派排列一致，但体积更紧凑。ST7735屏幕模块通常有8个引脚，我们需要逐一对应。

2.1 核心引脚功能理解

在动手接线前，先花一分钟搞清楚每个引脚是干什么的，这能帮你后续排查问题：

• VCC和GND ：电源和地线。 务必注意 ，绝大多数1.8寸ST7735屏的工作电压是3.3V，请绝对不要接到树莓派的5V引脚上，否则很可能烧毁屏幕。树莓派的GPIO电平也是3.3V，这正好匹配。
• SCK (Serial Clock) ：SPI时钟线，由主设备（树莓派）产生，用于同步数据位传输。
• SDA (MOSI) ：主设备输出，从设备输入线。树莓派通过这根线向屏幕发送图像数据或命令。注意，有些屏的标注可能是“SDA”，有些是“MOSI”，在这里它们是同一个意思。
• CS (Chip Select) ：片选线。当有多个SPI设备连接到同一组SPI总线时，用这根线来选择当前要与哪个设备通信。我们的屏幕通常默认接CE0（SPI0的片选0）。
• DC (A0) ：数据/命令选择线。这是一个非常关键的引脚。ST7735控制器需要区分接收到的是“命令”（如设置屏幕方向、亮度）还是“显示数据”（具体的像素颜色）。拉高或拉低此引脚电平来告知控制器。
• RST (Reset) ：复位线。拉低电平可以强制屏幕控制器复位，重新初始化。在程序开始或屏幕显示异常时很有用。
• LED (Backlight) ：背光控制。通常接一个GPIO，通过输出高电平（3.3V）来点亮背光。有些屏幕的背光可能直接接VCC，那就常亮了。

2.2 具体接线方案与验证

经过实测，以下接线方案对树莓派Zero W和常见的128x160 ST7735屏有效。建议使用母对母杜邦线，并确保连接牢固。

屏幕引脚	树莓派Zero W引脚	引脚编号 (物理位置)	备注
VCC	3.3V Power	Pin 1	关键！必须接3.3V
GND	Ground	Pin 9	任意GND引脚均可
SCK	GPIO 11 (SPI0 SCLK)	Pin 23	SPI0的时钟线
SDA (MOSI)	GPIO 10 (SPI0 MOSI)	Pin 19	SPI0的主出从入数据线
DC (A0)	GPIO 24	Pin 18	可自定义，但代码中需对应
RST	GPIO 25	Pin 22	可自定义，但代码中需对应
CS	GPIO 8 (SPI0 CE0)	Pin 24	SPI0的片选0，通常固定
LED	GPIO 22	Pin 15	背光控制，可自定义

接线安全提示 ：在接通电源前，务必再三检查VCC是否接在3.3V（Pin 1），而不是5V（Pin 2或4）。接错5V是导致屏幕“秒烧”最常见的原因。另外，建议先完成所有接线，再给树莓派上电，避免带电插拔。

接好线后，可以先不给背光（LED）引脚接线，等系统配置好、运行测试程序时再接上，这样能更直观地判断是背光没亮还是屏幕根本没工作。

3. 树莓派系统配置与SPI启用

硬件连接妥当后，我们需要在树莓派的Raspbian系统（这里以Bookworm为例）中进行软件层面的准备。核心是启用SPI接口并安装必要的工具。

3.1 基础系统设置与远程访问

首先，你需要一个安装了最新Raspbian Bookworm系统的树莓派Zero W。由于Zero W没有全尺寸HDMI接口，通常我们采用“无头模式”通过SSH远程操作，这非常方便。

1. 烧录系统 ：使用Raspberry Pi Imager工具烧录系统到Micro SD卡。在Imager中，你可以预先设置主机名、开启SSH、配置Wi-Fi和用户名密码，这样烧录完的卡插入树莓派，通电联网后就能直接通过SSH连接了，无需额外显示器和键盘。
2. 查找IP与连接 ：树莓派启动后，你需要知道它的IP地址。可以登录路由器管理界面查看，或者使用网络扫描工具（如 Advanced IP Scanner ）。在终端使用命令 ssh pi@你的树莓派IP 进行连接（默认用户可能是 pi ，Bookworm也可能需要你创建的用户名）。
3. 系统更新 ：连接成功后，首先更新系统软件包列表并升级现有软件，这是一个好习惯。

   sudo apt update
   sudo apt upgrade -y
   

   升级过程可能需要一些时间，取决于网络速度。

3.2 启用SPI接口

树莓派的SPI接口默认是关闭的，我们需要手动开启。

1. 启动树莓派配置工具：

   sudo raspi-config
   

2. 使用键盘方向键，选择 “Interface Options” （接口选项）。
3. 进入后，选择 “SPI” 。
4. 系统会询问“Would you like the SPI interface to be enabled?”，选择 “是” 。
5. 完成后，选择“Finish”，并选择在需要时重启（通常立即重启更稳妥）。

重启后，可以通过以下命令检查SPI是否已成功启用。如果看到 spidev0.0 和 spidev0.1 两个设备，说明SPI驱动已加载。

ls -l /dev/spi*

你应该能看到类似 /dev/spidev0.0 和 /dev/spidev0.1 的输出。

4. Python环境搭建与依赖库安装

我们将使用Python来驱动屏幕，因为相关的库生态非常成熟。但Bookworm系统在Python包管理上做了一个重要的安全变更，这导致直接用 pip install 安装系统包会报错，需要特别注意。

4.1 安装系统级Python依赖

首先，安装一些基础的系统软件包，这些包提供了Python运行、图像处理以及访问GPIO所需的核心组件。

sudo apt install -y python3-pip python3-pil python3-dev python3-numpy python3-libgpiod

• python3-pip : Python包管理工具。
• python3-pil (Pillow): 强大的图像处理库，用于加载、处理要在屏幕上显示的图片。
• python3-dev : 包含Python开发头文件，编译某些Python扩展时可能需要。
• python3-numpy : 科学计算库，一些图形处理操作可能会用到。
• python3-libgpiod : 访问GPIO的现代库，一些新的硬件驱动依赖它。

4.2 安装ST7735驱动库并解决“外部管理环境”错误

接下来安装专为ST7735屏幕编写的Python库。在Bookworm及更新的Debian/Ubuntu系统中，如果你直接使用 sudo pip3 install st7735 ，将会遇到如下错误：

error: externally-managed-environment
× This environment is externally managed

这是系统为了防止用 pip 安装的包破坏由 apt 管理的系统Python环境而引入的保护机制。官方推荐的方法是使用Python虚拟环境。但对于我们这种单一、明确的硬件项目，一个更直接（但需谨慎）的方法是使用 --break-system-packages 参数。 这意味着你明确知晓并接受可能的风险 。

sudo pip3 install st7735 --break-system-packages

同样地，安装另外两个可能需要的GPIO相关库：

sudo pip3 install gpiod --break-system-packages
sudo pip3 install gpiodevice --break-system-packages

关于虚拟环境的建议 ：如果你计划在树莓派上进行多个互不干扰的Python项目，学习使用 venv 创建虚拟环境是更规范的做法。但对于这个快速上手的显示屏项目，上述直接安装的方式更为快捷。

5. 关键步骤：修改ST7735库以适配128x160分辨率

这是整个过程中最具技术性也最容易出错的一步。我们从GitHub安装的 st7735-python 库，其默认配置可能是针对其他分辨率（如160x128）的屏幕。我们的屏幕是128x160，且实际有效显示区域可能需要微调，否则会出现显示偏移、只有部分画面或完全花屏。

5.1 定位并编辑库文件

我们需要修改库的核心配置文件。首先找到库的安装位置，通常在这里：

sudo nano /usr/local/lib/python3.11/dist-packages/st7735/__init__.py

注意 ：路径中的 python3.11 是Python的版本号，你的系统可能是 python3.10 或 python3.12 ，可以使用 ls /usr/local/lib/python3.*/dist-packages/ 命令查看确认。

5.2 修改分辨率参数

用 nano 编辑器打开上述文件后，找到定义屏幕尺寸的参数（通常在文件靠前的位置，比如第40行附近）。你需要将以下四个参数进行修改：

# 找到并修改这四行
ST7735_TFTWIDTH = 124   # 原值可能是 128 或 160
ST7735_TFTHEIGHT = 160  # 原值可能是 160 或 128
ST7735_COLS = 124       # 原值可能是 128 或 160
ST7735_ROWS = 160       # 原值可能是 160 或 128

为什么宽度是124而不是128？ 这是一个在实践中发现的“魔法数字”。某些ST7735屏幕的驱动芯片在初始化后，会在水平方向留下几个像素的“前沿”空白。将逻辑宽度设置为124，相当于告诉库从正确的像素列开始绘制，从而让128像素宽的内容在屏幕上完美居中显示，避免图像被截断或错位。如果设为128，你可能会发现图像靠右，左边有黑边。 这个值因屏而异，124是针对我手中这款屏的实测有效值 。如果你的屏幕显示仍有偏移，可以尝试微调这个值（如126, 122）。

修改完成后，按 Ctrl+O 保存，再按 Ctrl+X 退出nano编辑器。

6. 实战测试：显示图片与滚动文字

库修改好后，就可以进行激动人心的测试了。我们使用库作者提供的示例代码。

6.1 获取示例代码

首先，将 st7735-python 的示例代码克隆到本地：

cd ~
git clone https://github.com/pimoroni/st7735-python.git
cd st7735-python/examples

这个 examples 目录下有几个测试程序，我们主要用 image.py 和 scrolling-text.py 。

6.2 配置并运行图片显示测试

在运行 image.py 之前， 必须根据我们实际的接线修改屏幕初始化参数 。用编辑器打开该文件：

sudo nano image.py

找到初始化 ST7735 对象的部分（大约在40-50行）。你需要将其修改为与我们硬件接线对应的配置：

# 修改 disp = ST7735(...) 这一行附近的参数
disp = st7735.ST7735(
    port=0,                      # 使用SPI0端口
    cs=st7735.BG_SPI_CS_BACK,    # 片选信号，通常用这个常量
    dc="GPIO24",                 # 对应我们接的DC引脚 (GPIO24)
    backlight="GPIO22",          # 对应我们接的背光LED引脚 (GPIO22)
    rst="GPIO25",                # 对应我们接的复位引脚 (GPIO25)
    rotation=90,                 # 屏幕旋转90度（根据你的安装方向调整，可选0, 90, 180, 270）
    invert=False,                # 颜色不反转
    spi_speed_hz=4000000         # SPI通信速度，4MHz对于小屏足够且稳定
)

参数详解 ：

• port=0 : 表示使用 /dev/spidev0.0 设备。
• cs=... : 片选硬件管理方式， BG_SPI_CS_BACK 是库内置的一种模式，通常适用。
• dc , backlight , rst : 这里填的是字符串，必须与我们接线使用的GPIO编号（BCM编号）严格一致。
• rotation : 如果你的屏幕安装方向是竖屏，但希望横屏显示，可以通过这个参数旋转画面。
• spi_speed_hz : SPI总线速度。不是越高越好，过高的速度可能导致数据错误（花屏）。4MHz是一个保守且稳定的值。

保存并退出。然后运行测试命令，示例中会显示一张内置的猫咪图片。你需要将 cat.jpg 替换为 examples 目录下实际存在的图片文件名，或者指定你自己的图片路径。

python3 image.py cat.jpg  # 或者 python3 image.py /path/to/your/image.png

如果一切顺利，你应该立刻能在屏幕上看到显示的图片！第一次成功点亮屏幕的瞬间总是充满成就感。

6.3 配置并运行文字滚动测试

图片测试成功后，再来测试文字显示。同样需要先修改 scrolling-text.py 的配置：

sudo nano scrolling-text.py

找到初始化 ST7735 对象的部分（大约在10-20行），进行与 image.py 完全相同的参数修改：

disp = st7735.ST7735(
    port=0,
    cs=st7735.BG_SPI_CS_BACK,
    dc="GPIO24",
    backlight="GPIO22",
    rst="GPIO25",
    rotation=90,
    invert=False,
    spi_speed_hz=4000000
)

保存退出后，直接运行即可：

python3 scrolling-text.py

屏幕上将会出现一段滚动的文字。这个示例展示了如何在屏幕上绘制文本，是制作信息显示终端的基础。

7. 常见问题排查与深度优化指南

即使按照步骤操作，也可能遇到一些问题。这里汇总了常见故障及其解决方法。

7.1 屏幕完全无反应（背光也不亮）

• 检查电源 ：首先确认屏幕VCC是否接在树莓派的 3.3V (Pin 1) ，而不是5V。用万用表测量一下电压最保险。
• 检查背光 ：确认LED引脚是否接到了GPIO22，并且在代码中 backlight 参数是否正确设置为 "GPIO22" 。可以尝试在Python脚本中初始化显示屏后，手动点亮背光： disp.set_backlight(True) 。
• 检查SPI是否启用 ：再次运行 ls /dev/spi* ，确认设备存在。如果不存在，返回 raspi-config 检查SPI是否真的启用，并重启。
• 检查接线 ：逐根检查杜邦线是否松动、接触不良，特别是SCK、SDA、CS这几根数据线。可以尝试重新插拔。

7.2 屏幕背光亮但无显示（白屏或花屏）

• 检查DC/RST引脚定义 ：这是最常见的原因。确保代码中的 dc 和 rst 参数与你的物理接线（GPIO24, GPIO25）完全一致。 一个字母都不能错 。
• 检查库文件修改 ：确认 /usr/local/lib/python3.x/dist-packages/st7735/__init__.py 文件中的 ST7735_TFTWIDTH 和 ST7735_TFTHEIGHT 等四个参数是否已按照第5部分修改并保存。修改后 必须重启Python解释器或重启树莓派 才能生效。
• 降低SPI速度 ：尝试将初始化参数中的 spi_speed_hz=4000000 改为更低的 1000000 （1MHz）。过高的SPI速度在长线或干扰环境下可能导致数据错误。
• 检查屏幕初始化序列 ：极少数情况下，屏幕可能需要不同的初始化命令。 st7735 库内部已经处理了常见的ST7735变体。如果问题依旧，可以尝试在初始化时指定不同的 bgr 参数： bgr=True 。

7.3 图像显示不完整、偏移或错位

• 调整 ST7735_TFTWIDTH ：如第5部分所述，尝试微调 ST7735_TFTWIDTH 的值。如果图像靠右，左边有黑边，就减小这个值（如尝试122, 120）；如果图像靠左，右边有黑边，就增大这个值（但不要超过128）。这是一个试错过程。
• 调整 rotation 和偏移量 ：库的 ST7735 初始化可能还接受 offset_left 和 offset_top 参数，用于微调显示起始位置。例如： disp = st7735.ST7735(..., offset_left=2, offset_top=1, ...) 。查阅库的文档或源码查看更多参数。
• 确认图像尺寸 ：确保你尝试显示的图片分辨率不超过屏幕的逻辑分辨率（修改后的124x160）。过大的图片可能不会报错，但显示会异常。

7.4 Python脚本运行报错

• “ModuleNotFoundError: No module named ‘st7735’” ：说明 st7735 库没有安装成功。回顾第4.2节，使用 --break-system-packages 参数重新安装。
• 权限错误 ：运行Python脚本时如果提示无法打开 /dev/spidev0.0 ，通常是因为当前用户没有SPI设备访问权限。可以将用户加入 spi 组： sudo usermod -a -G spi $USER ，然后 注销并重新登录 （或重启）生效。或者直接使用 sudo 运行测试脚本（不推荐长期这样做）。

7.5 性能与显示优化建议

• 双缓冲与局部刷新 ：如果你需要显示动态内容（如动画、实时数据），频繁全屏刷新（ disp.display(image) ）可能会闪烁。更高级的做法是使用“双缓冲”或在内存中创建画布，只更新变化的部分，最后再一次性刷新到屏幕。Pillow库的 ImageDraw 模块提供了丰富的绘图功能。
• 字体与排版 ： scrolling-text.py 示例使用了PIL的默认字体，可能比较小。你可以加载TTF字体文件来使用更美观的字体： font = ImageFont.truetype(“/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf”, 16) 。
• 省电考虑 ：如果项目是电池供电，可以在不显示内容时通过 disp.set_backlight(False) 关闭背光，这是最大的耗电源。甚至可以通过 disp.reset() 或切断电源来进一步省电。

走到这一步，你的树莓派Zero W应该已经能自如地驱动那块1.8寸小屏了。从硬件的精准对接到软件层的“破解”与适配，整个过程是嵌入式开发中非常典型的“解决问题”的体验。记住最关键的三点：电压别接错、引脚定义要对上、库的配置参数要匹配你的硬件。有了这个基础，你就能以此为起点，开发出属于自己的迷你天气站、系统状态监视器或者复古游戏机了。