树莓派显示屏不亮？Pi 4 和 Pi 5 的 DSI、HDMI 及触摸排查指南

从这里开始：你用的是哪种连接方式？

请按顺序完成与你所用连接方式对应的章节。每一步排除一种原因，而前面的步骤正是最容易出问题的地方。

DSI 显示屏：黑屏或仅背光亮

1. 为你的 Pi 选用正确的排线

Raspberry Pi 5 的 DSI 连接器比早期型号更小，因此随旧款显示屏附带的排线无法适配。根据 Raspberry Pi 官方文档：

• Raspberry Pi 4 及更早型号：15 芯对 15 芯柔性扁平电缆（FFC）。
• Raspberry Pi 5：22 芯对 15 芯 FFC（Standard – Mini）。22 芯一端较小，插入 Pi；较大的一端插入显示屏。
• Raspberry Pi 5 上的 Touch Display 2（10 英寸）：使用附带的 22 芯对 22 芯 Mini – Mini FFC。

Raspberry Pi Zero 系列没有 DSI 连接器，因此完全无法使用 DSI 显示屏。

2. 检查排线是否插到位、方向是否正确

翻开连接器的锁定卡扣，将排线完全插到底后再扣上卡扣。在 Raspberry Pi 4B 及更早型号上，显示屏连接器标注为 DISPLAY（而非 CAMERA），金属触点朝向以太网口和 USB-A 接口。排线插反、半插入或插到摄像头连接器上，出现的症状与面板损坏完全相同。

3. 为显示屏提供独立的 5 V 供电

官方显示屏的供电与 DSI 排线是分开的：

• 初代 Touch Display：用跳线从 Pi 的 GPIO 排针取电，黑线接 6 号引脚（GND），红线接 4 号引脚（5 V），若 4 号引脚已被占用则接 2 号引脚。也可以改用 micro USB 电源供电，但此时切勿再连接 GPIO 供电线。
• Touch Display 2：使用附带的 GPIO 供电线，小端插入显示屏的 J1 接口，红线接 2 号引脚，黑线接 6 号引脚。

如果背光始终不亮，供电是首要怀疑对象。第三方面板的背光通常需要单独供电，请查阅厂商的接线图。

4. 不要添加不需要的 dtoverlay 行

Raspberry Pi OS 在 /boot/firmware/config.txt 中默认带有 display_auto_detect=1，固件会借此自动为可识别的 DSI 显示屏加载 overlay。因此，在标准 Raspberry Pi 上，官方显示屏无需任何 dtoverlay 行。手动添加一行，尤其尺寸或接口写错时，是黑屏的常见原因。

Raspberry Pi Compute Module 则不同：它不会自动检测 DSI 显示屏，需要自行添加 overlay：

• Touch Display 2（5 英寸）：dtoverlay=vc4-kms-dsi-ili9881-5inch
• Touch Display 2（7 英寸）：dtoverlay=vc4-kms-dsi-ili9881-7inch
• Touch Display 2（10 英寸）：dtoverlay=vc4-kms-dsi-ili79600-10-1inch
• 初代 7 英寸 Touch Display：dtoverlay=vc4-kms-dsi-7inch

默认使用标注为 1 的接口；若要使用 0 号接口，请追加 ,dsi0（例如 dtoverlay=vc4-kms-dsi-7inch,dsi0）。对于初代显示屏，还应删除任何 display_auto_detect 行。

5. 第三方 DSI 面板需要专用的 overlay

自动检测只覆盖固件能识别的显示屏。第三方 MIPI DSI 面板需要与其控制器、通道数和时序相匹配的设备树 overlay，通常由面板厂商提供。如果厂商的 overlay 针对较旧的内核或其他 Pi 型号，即使接线正确，面板也可能一直黑屏。请索取在你要用的具体 Pi 型号和 OS 版本上实测过的 overlay。我们的Raspberry Pi 5 显示屏说明和MIPI DSI 显示屏概览介绍了应向厂商确认哪些内容。

HDMI 显示屏:“无信号”或分辨率不对

1. 使用第一个 HDMI 端口

在 Raspberry Pi 4B 和 5 上,板上标有 HDMI0 的端口是第一路显示输出(Linux 中为 HDMI-A-1)。测试其他任何内容之前,请先将单块显示屏连接到该端口。

2. config.txt 中旧的 HDMI 设置已失效

许多教程仍让你在 config.txt 中设置 hdmi_force_hotplug、hdmi_group 和 hdmi_mode。Raspberry Pi 官方文档现已将这些列为遗留选项,并注明它们“在 Raspberry Pi OS Bookworm 及更高版本中不起作用”。在使用 KMS 图形驱动时,由 Linux 管理整个显示管线,包括 HDMI 输出。

3. 在 cmdline.txt 中用 video= 强制指定显示模式

未设置模式时,Pi 会读取显示屏的 EDID 并自动选择分辨率。小型 HDMI 驱动板上报的 EDID 有时与屏幕不匹配,从而导致“无信号”或画面被裁切。可在 /boot/firmware/cmdline.txt 的单行内容中添加 video= 参数来强制使用屏幕原生模式,例如 1024×600、60 Hz 的屏幕使用 video=HDMI-A-1:1024x600M@60。

格式为 video=<display>:<width>x<height>M@<refresh>。第二个 HDMI 端口使用 HDMI-A-2,DSI 或 DPI 显示屏使用 DSI-1。分辨率和刷新率请以屏幕数据手册为准。cmdline.txt 中的所有内容必须保持在同一行。

画面旋转或镜像

• 桌面环境:进入 首选项 > 控制中心 > 屏幕,选择相应显示屏,然后将 方向 设为正常、向左、倒置或向右。
• 仅控制台:扩展 video= 参数,例如 video=DSI-1:720x1280@60,rotate=90。使用 reflect_x、reflect_y 或 reflect_xy 进行镜像。

两个限制:所有已连接的显示屏共用同一个 rotate= 设置,且 rotate= 仅对文本控制台生效。直接通过 DRM 绘制的应用程序(如 cvlc 或 libcamera 应用)需要使用各自的旋转选项。

触摸与画面不对应

在桌面上,在控制中心设置方向后,触摸会随之调整。在无桌面环境且显示屏已旋转的情况下,请在 config.txt 中该显示屏的 overlay 上添加触摸参数:invx 和 invy 反转相应坐标轴,swapxy 交换两轴,disable_touch 关闭触摸。例如,在 7 英寸 Touch Display 2 上添加 dtoverlay=vc4-kms-dsi-ili9881-7inch,invx,invy 可同时反转两个轴。

对于初代 7 英寸显示屏,以这种方式添加触摸 overlay 时需移除 display_auto_detect=1。Raspberry Pi 指出,在设备树中旋转触摸可能与你的输入库冲突,因此应尽可能在输入库或桌面层面旋转触摸事件。

屏幕十分钟后变黑

这是屏幕熄屏(screen blanking),并非故障。启用时,Raspberry Pi OS 会在 600 秒无操作后熄屏。可在 控制中心 中关闭(Screen Blanking 开关),或通过 sudo raspi-config > 2 Display Options > D2 Screen Blanking 关闭。对于文本控制台,在 cmdline.txt 中添加 consoleblank=0 可使其永不熄屏。

什么时候问题出在屏幕而不是 Pi

如果屏幕接在已知正常的 Pi 上,且线缆、供电和设置都正确却仍然黑屏,请先测量背光供电并换一块屏幕测试,再考虑修改软件。如果是做产品而非一次性搭建,应选择供应商能针对你的具体主机提供 overlay、时序和上电时序的屏幕。我们的显示接口对比说明了在 Raspberry Pi 设计中何时选择 DSI 或 HDMI 更合适。