新物先判断只有屏幕黑，还是整个设备没运行
开机后是否有声音，是否出现配网热点，已联网的设备是否还能回答？这些观察能帮助区分只有显示异常和整机没有运行。完全没有运行迹象时，先检查供电、启动与固件，不要直接给屏幕判故障。
反过来，设备还能说话也不代表屏幕一定完好。本文固定的 v2.5.2 面包板源码在 esp_lcd_panel_init 返回失败时使用 NoDisplay；其他初始化调用仍可能通过 ESP_ERROR_CHECK 中止程序。这能解释为什么显示与语音应分别检查，但不能据此保证所有显示故障都能被程序自动忽略。
- 做到这里，你应该看到
- 能列出除屏幕之外至少一项设备运行或失败的迹象。
第 1 步：核对接口、驱动和分辨率
“0.96 寸屏幕”只是外形描述。购买信息或模块资料还应说明驱动、像素数和接口。官方基础方案列的是 SSD1306、I2C、128×32 或 128×64；尺寸相近的另一块屏，并不自动兼容。
下面是 v2.5.2 已核对的两个构建项。若你用的是 SH1106、彩色 LCD 或其他接口，先找明确支持它的固件；不要把修改显示文字或背景图片当成更换驱动的方法。
| 屏幕配置 | v2.5.2 对应构建项 |
|---|---|
| SSD1306，128×32 | bread-compact-wifi |
| SSD1306，128×64 | bread-compact-wifi-128x64 |
| 其他驱动或彩屏 | 另查板型、驱动和发布说明，不套用上面两个项。 |
- 做到这里，你应该看到
- 模块资料与目标包的屏幕配置一致。
第 2 步：断电，按标识检查四根线
不同模块的四根排针顺序可能不同。先读屏上的 GND、VCC、SCL、SDA，再沿每根线核对开发板连接；不能把照片中的第一根线当成所有屏幕的 GND。供电规格也要按所用模块确认。
v2.5.2 bread-compact-wifi 的显示信号配置为 SDA → GPIO41、SCL → GPIO42。44 引脚与 42 引脚板上的物理位置不同，对照自己的板型图核对丝印，而不是数左边第几个孔。
- 做到这里，你应该看到
- 四根线按模块标识核对完成，SDA 与 SCL 没有混用，供电满足该模块说明。
- 如果卡住了
- 插针未焊、接触不良或插偏一排都要先排除；修改连接前先断开 USB。
参考：[1] 官方教程：面包板硬件与接线[2] 官方百科链接的常见问题 Q&A（历史资料）[4] v2.5.2 面包板 Wi-Fi 引脚与 I2S 配置
第 3 步：按故障现象选择一次对照测试
如果刚换固件后出现半屏、布局错位，先核对分辨率；如果换了屏幕才全黑，先核对接口、驱动和接线。这是选择检查顺序的线索，不是凭现象直接判定原因。
有同规格备用屏时，可以保持固件与接线方案不变，只换屏幕做对照；没有明确规格的备用屏，不适合用于证明原屏幕已损坏。每次改变后都使用同一条启动流程，记录结果。
- 做到这里，你应该看到
- 对照测试只改变一项，并留下改变前后的结果。
参考：[1] 官方教程：面包板硬件与接线[2] 官方百科链接的常见问题 Q&A（历史资料）[3] v2.5.2 面包板 Wi-Fi 屏幕构建配置
想换彩屏时，换的是整套适配资料
彩屏通常还涉及不同接口、更多信号、背光或显示驱动。先在官方百科找到对应 LCD 或具体板型教程，再决定购买；基础 OLED 方案的包名和四线连接不能作为彩屏通用方案。
把当前能工作的 OLED 配置保存下来。新的屏幕、固件和接线一并确认后再尝试，可以减少在多个不匹配因素之间来回排查。
参考：[1] 官方教程：面包板硬件与接线[3] v2.5.2 面包板 Wi-Fi 屏幕构建配置[4] v2.5.2 面包板 Wi-Fi 引脚与 I2S 配置
资料来源与版本说明
本文属于小智现成固件路线，按文末官方资料与固定源码复核。历史 Q&A 与旧界面仅用于其所注明的版本情境，具体动作再按固定源码与板型核对；当前控制台的登录后界面和实物操作尚未验证。资料核对日期：。资料核对、程序构建与实板测试分别记录，不互相替代。
飞书原文请在浏览器打开；如跳转到登录页，按飞书提示访问。历史截图的原图出处与当前工具入口分别标明。
