ESP-IDF VS Code 插件缓存 JTAG 序列号导致第二块开发板 OpenOCD 启动失败的排查与解决

问题现象

使用 ESP-IDF VS Code 插件调试 ESP32-S3 时，第一块开发板 OpenOCD 正常启动，换第二块板后报错：

Info : No device matches the serial string
Error: esp_usb_jtag: could not find or open device!

Windows 设备管理器显示设备正常，VID/PID 正确（303A:1001），WinUSB 驱动已安装。

根因分析

ESP-IDF VS Code 插件会将第一块开发板的 USB JTAG 序列号静默保存到 VS Code 的 workspace SQLite 数据库（state.vscdb）中。换板后，插件仍使用旧序列号启动 OpenOCD，导致新板的序列号不匹配而无法连接。

关键判断依据：命令行 idf.py openocd 或 openocd -f board/esp32s3-builtin.cfg 可正常启动，仅 VS Code 图形化启动失败。

解决方案

方法一：清除缓存的 JTAG 序列号（推荐）

这是 Espressif 官方提供的方法，来自 Issue #1788 的维护者回复：

1. 在 VS Code 中打开 ESP-IDF 项目
2. 点击左侧活动栏的 ESP-IDF 插件图标（Espressif logo），打开插件命令面板
3. 在命令列表中找到 OpenOCD Adaptor (serial & location)，点击启用它
4. 启用后，底部状态栏左侧会出现一个新按钮，显示当前缓存的 JTAG 序列号和 USB 端口位置
5. 点击该状态栏按钮即可清除缓存的序列号，插件将自动连接到下一个可用的 JTAG 设备

清除后重新启动 OpenOCD 即可正常连接第二块开发板。

方法二：命令行启动 OpenOCD 绕过插件

如果状态栏方法不适用，可以命令行启动 OpenOCD，VS Code 仅连接已有的 GDB Server：

idf.py openocd

然后在 VS Code 的 launch.json 中配置：

"miDebuggerServerAddress": "localhost:3333"

验证步骤

1. 插上第一块板，VS Code 中启动 OpenOCD，确认正常
2. 换第二块板，直接在 VS Code 中启动 OpenOCD —— 此时应报错 No device matches the serial string
3. 按上述方法一清除序列号缓存，重新启动 OpenOCD，确认第二块板正常连接

参考

• ESP-IDF VSCode Extension Issue #1788 - Virtual JTAG silently saved in workspace database（维护者回复中给出了状态栏清除方法）
• ESP-IDF VSCode Debug Documentation

本文由 AI 辅助生成，可能存在错误或遗漏，请以实际资料和官方文档为准。