ESP32代码上传遇SerialTimeoutException(Write timeout)错误求助

问题背景 #

已更换多个串口端口、添加ESP32板管理器URL、尝试多段无问题代码，仍出现上传超时错误，具体错误信息如下：

esptool.py v3.0-dev
Serial port COM10
Connecting...
Traceback (most recent call last):
  File "esptool.py", line 3682, in <module>
  File "esptool.py", line 3675, in _main
  File "esptool.py", line 3330, in main
  File "esptool.py", line 512, in connect
  File "esptool.py", line 492, in _connect_attempt
  File "esptool.py", line 431, in sync
  File "esptool.py", line 369, in command
  File "esptool.py", line 332, in write
  File "site-packages\serial\serialwin32.py", line 323, in write
serial.serialutil.SerialTimeoutException: Write timeout
Failed to execute script esptool
An error occurred while uploading the sketch

排查与解决步骤 #

• 确认上传模式与硬件连接

  • 上传前触发ESP32的上传模式：按住BOOT键，短按RESET键，松开RESET后保持按住BOOT，直到IDE开始上传代码后再松开（部分ESP32开发板必须此操作才能进入烧录模式）
  • 更换USB数据线：使用带数据传输功能的线，避免使用仅充电的线材；尝试不同品牌或长度的数据线
  • 检查供电稳定性：确保ESP32的电源为3.3V且电流充足，避免因供电不足导致串口通信中断；若使用USB供电，尽量连接电脑后置USB端口
  • 核对串口引脚：自行焊接的模块需确认TX/RX交叉连接（ESP32 TX → USB转串口 RX，ESP32 RX → USB转串口 TX）

• 调整串口上传参数

  • 降低上传波特率：在Arduino IDE中进入工具 > 上传波特率，选择更低的选项（如从921600改为115200），部分串口芯片或线材无法支持高速波特率
  • 确认端口正确性：在设备管理器中查看当前ESP32对应的COM口，上传时插拔设备确认端口变化，避免选错端口

• 更新或替换esptool.py

  • 当前使用的esptool.py v3.0-dev为开发版本，存在兼容性风险，可更换为稳定版：
    1. 找到Arduino IDE安装目录下的hardware/espressif/esp32/tools/esptool.py文件
    2. 替换为ESP-IDF官方仓库的稳定版esptool.py
  • 更新ESP32板包：进入工具 > 开发板 > 开发板管理器，找到ESP32并更新到最新稳定版本

• 修复串口驱动

  • 卸载并重新安装USB转串口芯片的最新驱动（如CH340、CP2102等，直接前往芯片厂商官网下载）
  • 检查设备管理器中的串口设备，若存在黄色感叹号，右键选择“更新驱动程序”修复

• 释放串口资源

  • 关闭所有占用串口的软件，包括串口调试助手、虚拟机、杀毒软件等，避免后台程序抢占串口导致写入超时

内容的提问来源于stack exchange，提问作者Dawood's signature