1. 项目概述将树莓派桌面扩展到SPI小屏折腾树莓派的朋友手里或多或少都有几块闲置的小尺寸SPI显示屏吧它们通常来自一些传感器模块套件或者早期的物联网项目分辨率不高常见的有240x240、240x320驱动芯片以ST7789、ILI9341为主。大多数时候我们只是用它们来显示几行系统状态或者传感器数据总觉得有点大材小用。最近我在做一个便携式的树莓派调试终端需要把完整的Raspberry Pi OS桌面环境64位桌面版直接镜像到一块2英寸的ST7789 SPI屏上。这样我就可以脱离笨重的HDMI显示器只用这块小屏进行临时的图形化操作和配置非常方便。经过一番摸索和踩坑我成功实现了这个目标。这个过程不仅仅是运行一个脚本那么简单其中涉及到SPI总线原理、Linux帧缓冲Framebuffer配置、设备树Device Tree覆盖层以及如何为非标准分辨率屏幕校准显示区域。如果你也有一块吃灰的SPI屏想让它变身成为树莓派的“第二桌面”甚至“主桌面”那么这篇详细的配置指南正是为你准备的。无论你是想打造一个超紧凑的桌面电脑还是为你的机器人项目添加一个图形控制界面这套方案都能提供一个稳定可靠的起点。2. 核心思路与方案选型解析2.1 为什么选择“桌面镜像”模式在树莓派上驱动SPI显示屏通常有三种主流模式理解它们的区别是成功的第一步。第一种是控制台Console模式。这种模式下SPI屏会替代HDMI或串口成为系统的文本终端。你开机后看到的不再是图形登录界面而是黑底白字的命令行。这非常适合运行无头Headless服务器但显然不符合我们“使用桌面”的需求。第二种是纯驱动Driver-Only模式。系统仅仅加载了显示屏的驱动创建了一个帧缓冲设备通常是/dev/fb1但不会自动向其输出任何内容。你需要自己编写程序比如用Python的PIL库向这个帧缓冲设备绘制图像。这给了开发者最大的灵活性但离“开箱即用”的桌面体验相距甚远。第三种就是我们这次要实现的桌面镜像Mirror模式。这种模式利用了Linux的DRMDirect Rendering Manager和KMSKernel Mode Setting子系统。简单来说系统会将SPI屏识别为一个额外的独立显示器。然后你可以通过Raspberry Pi OS自带的显示设置将主显示器HDMI的桌面内容“克隆”或“扩展”到这个SPI屏上。对于ST7789这类屏幕我们通常使用“克隆”即镜像模式因为小屏分辨率低扩展桌面操作起来并不方便。我选择镜像模式的核心原因是便捷性与实用性。安装配置完成后它就像接上了第二台显示器所有图形界面的操作包括打开菜单、拖动窗口、使用图形化配置工具都能在这块小屏上同步进行。这对于快速调试、展示或构建一体化设备来说体验远胜于命令行或自定义GUI程序。2.2 工具链选择Adafruit安装脚本的利与弊实现上述目标社区里主要有两种路径一是从零开始手动配置设备树覆盖层DT Overlay和修改config.txt二是使用现成的自动化脚本。我强烈推荐初学者甚至是有经验的开发者使用Adafruit的Raspberry-Pi-Installer-Scripts工具包这也是本指南的核心。优势在于自动化程度高脚本自动处理了驱动编译、设备树覆盖层安装、系统服务配置等一系列繁琐步骤避免了手动操作容易出错的问题。社区验证Adafruit作为知名的硬件厂商其脚本经过了大量用户的测试对常见型号尤其是他们自家产品的兼容性较好。交互式配置脚本提供了友好的命令行菜单引导你选择屏幕型号、旋转方向和显示模式无需记忆复杂的参数。但需要注意其局限性针对性设计脚本主要是为Adafruit自家生产的屏幕优化的其预设的分辨率、偏移量Offset参数可能与你手上的第三方屏幕不完全匹配。这就是为什么我们后续必须手动调整config.txt的原因。系统版本依赖脚本可能随着树莓派OS内核的更新而需要调整。本文基于最新的Raspberry Pi OS Bookworm64位桌面版验证其他版本流程类似但细节可能有差异。所以我们的整体方案可以概括为利用Adafruit脚本完成90%的繁重工作然后针对自己屏幕的具体型号通过微调内核参数来完成最后的10%的适配。这是一种高效且稳妥的策略。3. 硬件连接与系统准备3.1 SPI显示屏与树莓派的物理连接ST7789屏幕通常通过SPI接口通信这是一种高速、全双工、同步的串行总线。连接前请务必找到你屏幕的说明书或引脚图。下面是一个标准的连接示意以树莓派3/4/5的40针GPIO接口为例屏幕引脚标号功能连接至树莓派GPIO物理引脚号备注VCC电源正极3.3V引脚1或17绝对禁止接5V会烧毁屏幕GND电源地GND引脚6, 9, 14, 20, 25, 30, 34, 39等任一SCLK (CLK)串行时钟GPIO 11 (SPI0 SCLK)引脚23SPI主时钟线MOSI (SDA, DIN)主出从入GPIO 10 (SPI0 MOSI)引脚19树莓派发送数据到屏幕DC (RS, A0)数据/命令选择GPIO 25引脚22关键引脚高电平写数据低电平写命令CS片选GPIO 8 (SPI0 CE0)引脚24使能SPI设备0低电平有效RST (RESET)复位可选接GPIO或3.3V-接GPIO可软件复位接3.3V则常高电平BLK (BL, LED)背光控制GPIO 22引脚15脚本默认用此引脚PWM控制背光重要提示上表中的GPIO 25和GPIO 22是Adafruit脚本默认的DC和背光控制引脚。如果你的屏幕引脚定义不同或者你想使用其他GPIO是完全可以的但需要在后续的config.txt配置中通过dc-gpio和backlight-gpio参数明确指定。对于首次尝试建议先按此默认连接成功后再考虑自定义。连接时建议使用杜邦线并确保接触牢固。树莓派请先断电再进行连接操作。3.2 基础系统环境搭建首先你需要一个安装了Raspberry Pi OS with Desktop (64-bit)系统的树莓派。建议使用最新的“Bookworm”版本。系统安装完成后第一件事是启用SSH因为我们后续的操作主要在命令行进行这样更高效。启用SSH在树莓派桌面点击左上角树莓派图标 -Preferences-Raspberry Pi Configuration。在弹窗中切换到Interfaces标签页找到SSH选择Enable。点击OK。获取IP地址将鼠标悬停在桌面右上角的网络图标上可以看到当前的IP地址。或者打开终端输入hostname -I命令查看。使用SSH客户端连接在你的电脑Windows推荐使用PuTTY或Windows TerminalmacOS/Linux使用终端上使用SSH命令连接。例如ssh pi你的树莓派IP地址默认用户名为pi密码为raspberry如果你没有修改过。连接成功后我们先更新系统软件包列表并升级现有软件这是一个好习惯sudo apt update sudo apt full-upgrade -y升级完成后执行重启以确保所有更新生效sudo reboot等待树莓派重启后重新通过SSH连接。4. 驱动安装与桌面镜像配置详解4.1 安装脚本依赖与环境准备Adafruit的安装脚本是用Python编写的为了避免污染系统全局的Python环境我们使用虚拟环境venv来运行它。这能确保依赖包的独立性。首先切换到root用户并创建一个项目目录sudo -i mkdir /spi_screen cd /spi_screen接着安装Python3的包管理工具pipBookworm系统可能已预装但确保一下apt-get install python3-pip -y现在创建并激活Python虚拟环境python3 -m venv env source env/bin/activate激活后你的命令行提示符前会出现(env)字样。在这个环境里我们安装脚本所需的几个核心Python库pip3 install --upgrade click setuptools adafruit-python-shell注意adafruit-python-shell这个库是Adafruit提供的工具库用于其安装脚本的交互和系统操作并非屏幕驱动本身。安装完成后退出虚拟环境deactivate4.2 获取并运行Adafruit PiTFT脚本Adafruit将各种显示屏的安装脚本集中在一个仓库里。我们将其克隆到本地git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git cd Raspberry-Pi-Installer-Scripts仓库里有很多脚本针对不同屏幕如PiTFT、OLED等。对于SPI接口的ST7789屏幕我们使用adafruit-pitft.py这个脚本。直接运行它python3 adafruit-pitft.py脚本会以交互式菜单的形式运行。选择屏幕类型首先它会列出众多支持的屏幕。你需要找到对应ST7789的选项。在我的脚本版本中对应的是选项7: “ST7789V 2.0” no touch (320x240)“。请仔细阅读菜单选择最匹配你屏幕尺寸和驱动芯片的项。输入数字7并按回车。选择旋转方向接下来选择屏幕的物理安装方向。0度是默认排线在下90度是顺时针旋转排线在右依此类推。根据你的实际安装情况选择例如我选择190度。选择显示模式这是最关键的一步。脚本会问你想如何配置屏幕1. Console on TFT/OLED - Console (text) output on the screen, desktop GUI on HDMI2. Desktop on TFT/OLED - Desktop GUI on the screen, console on HDMI3. GUI on TFT/OLED, console on HDMI and TFT/OLED (dual display)4. Mirror HDMI on TFT/OLED - Mirror the desktop on the screen5. Just show the splash screen on TFT/OLED为了实现桌面镜像我们必须选择选项4: “Mirror HDMI on TFT/OLED”。输入4并按回车。脚本接下来会自动执行一系列操作下载内核头文件、编译ST7789的DRM驱动模块、创建并启用设备树覆盖层、修改/boot/firmware/config.txt等。整个过程可能需要几分钟请耐心等待期间可能会提示你输入Y确认。当脚本提示“REBOOT NOW”时表示驱动已安装完成。输入Y同意重启。sudo reboot5. 分辨率校准与偏移量调试实战5.1 首次启动与问题诊断重启后你的SPI屏幕应该已经亮起并且可能显示了一些内容但极有可能出现以下几种“异常”情况花屏或错乱屏幕上布满彩色条纹或乱码。显示不全桌面只显示了一部分另一部分跑到屏幕外面去了。偏移错位桌面内容整体偏向屏幕的一角另一侧留下黑边。这都是完全正常的因为脚本配置的分辨率和偏移参数是针对特定Adafruit屏幕的与我们手上的屏幕很可能不匹配。我们的任务就是像调校老式电视一样手动校准它。首先再次通过SSH登录树莓派。我们需要编辑系统引导配置文件/boot/firmware/config.txtsudo nano /boot/firmware/config.txt使用CtrlW搜索关键词adafruit-pitft-helper你会找到脚本添加的配置块内容大致如下# --- added by adafruit-pitft-helper Mon Feb 9 12:04:45 2026 --- [all] hdmi_force_hotplug1 # required for cases when HDMI is not plugged, etc. dtparamspion dtparami2c1on dtparami2c_armon dtoverlaymipi-dbi-spi,spi0-0,speed40000000 dtparamcompatibleadafruit_st7789_drm\0panel-mipi-dbi-spi dtparamwidth240,height320 dtparamdc-gpio25,backlight-gpio22,drm # --- end adafruit-pitft-helper Mon Feb 9 12:04:45 2026 ---核心参数是dtparamwidth240,height320这一行。这里的240和320是脚本根据你之前选择的屏幕型号预设的。5.2 确定正确的分辨率参数你需要知道你屏幕的原生分辨率。对于ST7789常见的有240x240 (圆形或方形屏)240x320 (2.0寸或2.4寸屏)135x240 (一些窄条形屏)查看你的屏幕产品页面或数据手册。假设我的屏幕是240x240那么我就将上面那行修改为dtparamwidth240,height240修改后按CtrlO保存再按CtrlX退出nano编辑器。然后重启sudo reboot重启后如果幸运的话桌面应该能正确全屏显示了。但更常见的情况是显示内容虽然比例对了但整体位置不对这就是需要设置**偏移量Offset**的时候。5.3 偏移量x-offset, y-offset的调试艺术偏移量问题是因为屏幕的驱动ICST7789的显存GRAM映射区域与屏幕的物理像素区域没有完全对齐导致的。我们需要告诉系统“请从显存的第X列、第Y行开始显示数据”。如何确定x-offset和y-offset的值这需要一个简单的调试过程。重新编辑config.txtsudo nano /boot/firmware/config.txt找到刚才修改过分辨率的那一行为其添加偏移参数。格式是dtparamwidthW,heightH,x-offsetX,y-offsetY。例如如果桌面内容整体偏右左边有黑边说明起始列太靠右了我们需要一个正的x-offset来让内容左移。但这里逻辑是反的x-offset是告诉系统从显存的第几列开始读取数据。如果左边有黑边意味着有效图像在显存中靠右了所以我们需要增大x-offset的值跳过左边无效的列。一个实用的调试方法是二分试探法先设一个明显的偏移比如x-offset80。重启后观察黑边在哪边。如果黑边从左边换到了右边说明正确的偏移值在0和80之间。下次尝试40。如果黑边还在左边说明偏移值需要更大下次尝试120。如此反复直到桌面内容居中显示。对于240x240的屏幕常见的偏移组合可能是x-offset80, y-offset0或x-offset0, y-offset80。最终我的配置行如下dtparamwidth240,height240,x-offset80,y-offset0重要心得修改config.txt后必须重启才能生效。sudo systemctl restart相关服务通常无效因为驱动和参数在内核启动早期就已加载。6. 性能优化与高级配置技巧6.1 SPI总线速度优化在config.txt的配置块中有一行dtoverlaymipi-dbi-spi,spi0-0,speed40000000。这里的speed40000000设置了SPI通信的频率为40MHz。这是脚本设置的一个相对保守且兼容性较好的值。如果你的屏幕质量较好布线简短可以尝试提高这个速度以获得更流畅的显示效果尤其是鼠标移动和窗口拖动。可以尝试提高到speed6200000062MHz或speed8000000080MHz。修改后重启观察屏幕是否出现雪花、闪屏或数据错误。如果出现则说明速率过高需要调低。警告过高的SPI速率可能导致数据传输不稳定。如果屏幕完全黑屏或无法启动可能是速率过高导致初始化失败。此时需要将SD卡连接到另一台电脑修改config.txt文件将速率改回默认值。6.2 背光与电源管理脚本默认使用GPIO 22通过PWM控制背光。你可以通过修改/boot/firmware/config.txt中backlight-gpio参数后的值来改变PWM行为甚至禁用PWM使其常亮。例如改为backlight-gpio22,active_low如果# 1. 两数之和题目给定一个整数数组 nums 和一个整数目标值 target请你在该数组中找出 和为目标值 target 的那 两个 整数并返回它们的数组下标。你可以假设每种输入只会对应一个答案。但是数组中同一个元素在答案里不能重复出现。你可以按任意顺序返回答案。思路使用哈希表 将数组中的元素和下标存储到哈希表中遍历数组 对于每一个元素 计算target - nums[i] 判断这个值是否在哈希表中如果在哈希表中 并且这个值的下标不等于i 那么返回i和这个值的下标代码class Solution { public: vectorint twoSum(vectorint nums, int target) { unordered_mapint,int map; for(int i 0; i nums.size(); i) { // 将元素和下标存储到哈希表中 map.insert(pairint,int(nums[i],i)); } for(int i 0; i nums.size(); i) { auto iter map.find(target - nums[i]); if(iter ! map.end() iter-second ! i) { return {i,iter-second}; } } return {}; } };