修复 ESP-IDF / VS Code 中 QEMU 无法启动的问题

修复 ESP-IDF / VS Code 中 QEMU 无法启动的问题

本文记录在 Windows + ESP-IDF v6.0.1 + VS Code ESP-IDF 插件环境下，修复 QEMU 模拟器无法启动的过程。

问题现象

通过 VS Code ESP-IDF 插件启动 QEMU Monitor 或 QEMU Debug 时，出现错误：

qemu-system-xtensa is not found in PATH or access is denied

尝试安装 QEMU 时还出现：

备注：使用的是命令行的安装方式：

python $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv32

提示报错

由于找不到 libiconv-2.dll，无法继续执行代码

但进入 QEMU 的 bin 目录后，手动运行：

.\qemu-system-xtensa.exe --version

又可能是正常的，或者在补 DLL 后可以正常运行。

这说明问题通常不在项目固件，而在 QEMU 安装目录结构、运行时 DLL 和 ESP-IDF 工具识别机制。

根因分析

此问题实际包含两个独立部分。

1. Windows QEMU 包缺少运行时 DLL

ESP-IDF 下载的 Windows QEMU 压缩包中通常只包含：

qemu-system-xtensa.exe
qemu-system-xtensaw.exe

而 qemu-system-xtensa.exe 依赖：

libiconv-2.dll

如果该 DLL 不在 QEMU 可执行文件所在目录，也没有在系统 PATH 中，Windows 就会报：

找不到 libiconv-2.dll

ESP-IDF 自带 Git 工具中通常已经有这些 DLL，例如：

C:\Users\<用户名>\.espressif\tools\idf-git\2.39.2\mingw64\bin\

其中包括：

libiconv-2.dll
libintl-8.dll
libwinpthread-1.dll

2. QEMU 的目录层级必须符合 ESP-IDF 的 tools.json

ESP-IDF 不只是检查某个目录里是否存在 qemu-system-xtensa.exe。

在 ESP-IDF v6.0.1 的 tools/tools.json 中，qemu-xtensa 的导出路径定义为：

"export_paths": [
  [
    "qemu",
    "bin"
  ]
]

因此 ESP-IDF 期望的目录结构是：

%USERPROFILE%\.espressif\tools\qemu-xtensa\
  esp_develop_9.2.2_20250817\
    qemu\
      bin\
        qemu-system-xtensa.exe

注意其中的这一层：

qemu\bin

如果手工解压时把最外层 qemu 目录去掉，最终结构变成：

...\esp_develop_9.2.2_20250817\bin\qemu-system-xtensa.exe

虽然可以通过完整路径直接执行，但 ESP-IDF 工具管理器无法识别安装状态，导致：

WARNING: directory for tool qemu-xtensa version ... is present,
but the tool has not been found

随后 VS Code 插件生成 ESP-IDF 环境时，也不会把 QEMU 的目录加入 PATH，最终引发：

qemu-system-xtensa is not found in PATH or access is denied

正确的 QEMU 目录结构

以 ESP-IDF v6.0.1 使用的版本为例，最终目录应如下：

C:\Users\<用户名>\.espressif\tools\qemu-xtensa\
└── esp_develop_9.2.2_20250817\
    └── qemu\
        ├── bin\
        │   ├── qemu-system-xtensa.exe
        │   ├── qemu-system-xtensaw.exe
        │   ├── libiconv-2.dll
        │   ├── libintl-8.dll
        │   └── libwinpthread-1.dll
        ├── include\
        ├── lib\
        └── share\
            └── qemu\
                ├── esp32-v3-rom.bin
                └── esp32s3_rev0_rom.bin

ESP32 与 ESP32-S3 都使用：

qemu-system-xtensa.exe

ESP32-C3、ESP32-C6 等 RISC-V 芯片则需要使用 qemu-riscv32。

修复步骤

以下示例假设：

用户名：11349
ESP-IDF：C:\Users\11349\esp\v6.0.1\esp-idf
IDF 工具目录：C:\Users\11349\.espressif

请按自己的环境替换路径。

1. 删除不完整的 QEMU 安装目录

在 PowerShell 执行：

Remove-Item -Recurse -Force `
  C:\Users\11349\.espressif\tools\qemu-xtensa\esp_develop_9.2.2_20250817 `
  -ErrorAction SilentlyContinue

2. 确认下载包存在

ESP-IDF 下载后的压缩包通常位于：

C:\Users\11349\.espressif\dist\

例如：

qemu-xtensa-softmmu-esp_develop_9.2.2_20250817-x86_64-w64-mingw32.tar.xz

如果没有该文件，可通过 ESP-IDF 的安装流程重新下载。注意在 Windows 上应使用 PowerShell、CMD 或 ESP-IDF Terminal，不要在 Git Bash/MSYS2 环境中执行 IDF 6 工具安装命令。

3. 解压时保留压缩包中的 qemu 顶层目录

压缩包中的布局是：

qemu/
qemu/bin/
qemu/bin/qemu-system-xtensa.exe
...

解压目标目录应为：

C:\Users\11349\.espressif\tools\qemu-xtensa\esp_develop_9.2.2_20250817

不要把压缩包中的 qemu 顶层目录剥掉。

解压后必须得到：

C:\Users\11349\.espressif\tools\qemu-xtensa\
  esp_develop_9.2.2_20250817\
    qemu\
      bin\
        qemu-system-xtensa.exe

4. 补齐 QEMU 所需 DLL

将 IDF Git 工具的运行时 DLL 复制到 QEMU bin 目录：

$gitBin = "C:\Users\11349\.espressif\tools\idf-git\2.39.2\mingw64\bin"

$qemuBin = "C:\Users\11349\.espressif\tools\qemu-xtensa\" +
           "esp_develop_9.2.2_20250817\qemu\bin"

Copy-Item "$gitBin\libiconv-2.dll" $qemuBin
Copy-Item "$gitBin\libintl-8.dll" $qemuBin
Copy-Item "$gitBin\libwinpthread-1.dll" $qemuBin

将 DLL 放在 exe 同级目录是最简单、最可靠的方式。Windows 加载 DLL 时会优先检查应用程序所在目录，因此无需把 DLL 添加到全局系统目录。

5. 验证 QEMU 本身可执行

$qemuBin = "C:\Users\11349\.espressif\tools\qemu-xtensa\" +
           "esp_develop_9.2.2_20250817\qemu\bin"

& "$qemuBin\qemu-system-xtensa.exe" --version

预期输出：

QEMU emulator version 9.2.2 (esp_develop_9.2.2_20250817)
Copyright (c) 2003-2024 Fabrice Bellard and the QEMU Project developers

让 VS Code ESP-IDF 插件识别 QEMU

VS Code ESP-IDF 插件的：

• ESP-IDF: Launch QEMU Server
• ESP-IDF: Monitor QEMU Device
• ESP-IDF: Launch QEMU Debug Session

都要求：

qemu-system-xtensa

能够在插件生成的 ESP-IDF 环境 PATH 中找到。

如果 QEMU 位于 ESP-IDF 预期的工具目录结构：

%USERPROFILE%\.espressif\tools\qemu-xtensa\
  <版本>\qemu\bin

ESP-IDF 的 idf_tools.py export 会自动将其加入 PATH，不需要手动修改 Windows 用户 PATH。

修复目录后应：

1. 彻底退出 VS Code；
2. 确保后台没有残留 Code.exe；
3. 重新打开 VS Code；
4. 打开 ESP-IDF 项目；
5. 从命令面板执行：

   ESP-IDF: Launch QEMU Server
   

6. 再执行：

   ESP-IDF: Monitor QEMU Device
   

如何确认插件环境已正确识别 QEMU

VS Code 中打开：

ESP-IDF: Open ESP-IDF Terminal

执行：

Get-Command qemu-system-xtensa
qemu-system-xtensa --version

预期 Get-Command 的来源应是：

C:\Users\<用户名>\.espressif\tools\qemu-xtensa\
esp_develop_9.2.2_20250817\qemu\bin\
qemu-system-xtensa.exe

如果 ESP-IDF 终端输出的 PATH 中能看到：

...\qemu-xtensa\esp_develop_9.2.2_20250817\qemu\bin

则 VS Code 插件的 QEMU 功能通常也能正常工作。

常见误区

误区 1：手工运行 exe 成功，就代表插件一定能启动

不一定。

例如下面的命令成功：

.\qemu-system-xtensa.exe --version

只能说明 QEMU 本体与 DLL 正常，不能说明 ESP-IDF 工具管理器已经识别该安装目录。

插件依赖 ESP-IDF 的工具导出规则，因此目录层级必须与 tools.json 一致。

误区 2：只把 QEMU 的 bin 加入 Windows PATH

这可以临时解决命令查找问题，但不是最佳方案：

• 用户 PATH 可能已经过长；
• VS Code 需要重启才能继承更新后的环境变量；
• ESP-IDF 工具管理器仍可能认为 QEMU 未安装；
• 不能解决 QEMU 缺失 libiconv-2.dll 的问题。

优先确保 QEMU 安装在 ESP-IDF 期望的位置。

误区 3：在 Git Bash/MSYS2 中执行 IDF 6 的工具安装

ESP-IDF 6 对 MSYS/MINGW 环境有限制，可能显示：

MSys/Mingw is not supported

安装 QEMU、调用 idf_tools.py、运行 VS Code 插件相关命令时，建议使用：

• Windows PowerShell；
• Windows CMD；
• VS Code 的 ESP-IDF: Open ESP-IDF Terminal。

总结

在 Windows 下修复 ESP-IDF QEMU 启动异常，核心检查以下三项：

1. QEMU 目录结构正确

   qemu-xtensa\<version>\qemu\bin\qemu-system-xtensa.exe
   

2. QEMU 运行时 DLL 完整

   libiconv-2.dll
   libintl-8.dll
   libwinpthread-1.dll
   

3. 重启 VS Code，让 ESP-IDF 插件重新生成工具 PATH

其中最容易忽略的点是：不能漏掉 QEMU 压缩包最外层的 qemu 目录。这层目录正是 ESP-IDF 通过 tools.json 自动识别、导出 QEMU 到 PATH 的关键。