ESP32 学习笔记【9】：windows+VScode+ESP-AT搭建

ESP32-C5 ESP-AT 固件编译环境搭建笔记

记录电脑：C:\Users\你的文件\esp下搭建 ESP-AT（ESP32-C5）本地编译环境的完整过程，供以后重装/排查问题参考。

背景

• 目标：在本地编译 ESP32-C5 的 ESP-AT 固件源码
• 关键前提：ESP32-C5 的 AT 固件要求 ESP-IDFrelease/v5.5，但build.py会自动拉取所需版本，不需要手动装 v5.5
• 开发环境：Windows + Git Bash（用于 git 操作）+ cmd（用于编译，Git Bash/MSYS 不支持跑 ESP-IDF 安装脚本）
• 编辑器：VS Code（直接打开esp-at整个文件夹编辑代码，编译仍用命令行）

一、一次性环境搭建步骤

1. 克隆 ESP-AT 项目

国内直连 GitHub 容易在克隆子模块（尤其是 esp-idf、蓝牙/Wi-Fi 库）时报Connection was reset错误，改用官方镜像：
使用：bash

cd~/espgitclone--recursivehttps://jihulab.com/esp-mirror/espressif/esp-at.git esp-at

如果中途卡住报错，可以rm -rf esp-idf后重跑python build.py install（见下），git submodule update支持断点续传，已下载的部分不会重来。

2. 装 build.py 自身依赖的 Python 包

使用：bash

python-mpipinstallcolorama

3. 运行安装脚本，选择芯片型号

必须在 cmd 或 PowerShell 里跑，Git Bash(MSYS) 不支持：

cd C:\Users\你的文件\esp\esp-at python build.py install

按提示选择：

• Platform name →4(PLATFORM_ESP32C5)
• Module name →ESP32C5-4MB
• Silence mode →0（No，推荐关闭，方便看日志）

这一步会把esp-at要求的 esp-idf（release/v5.5，具体 commit 记录在module_config/module_esp32c5_default/IDF_VERSION）克隆到esp-at/esp-idf目录下。

4. 隔离 Python 工具环境（解决"串环境"问题）

问题现象：编译时反复报No module named 'colorama'/'xlrd'/'esp_idf_monitor'，即使装了包还是报错。

原因：电脑上之前装过另一套独立的 ESP-IDF，系统里已经设置了IDF_TOOLS_PATH环境变量指向那里，导致build.py复用了那套本身就不完整的 Python 环境。

解决办法：给 esp-at 项目单独指定一个干净的工具/环境目录，不复用旧环境：
使用：cmd

set IDF_TOOLS_PATH=C:\Users\liuch\esp\esp-at\.espressif python build.py install

这会在esp-at\.espressif下重新装一套独立的 Python 虚拟环境和工具链（cmake、ninja、编译器等），不影响原来那套。

5. 补装缺失的 Python 包

新环境有时也没装全，手动补齐（在set IDF_TOOLS_PATH生效的同一个窗口里）：
使用：cmd

C:\Users\你的文件\esp\esp-at\.espressif\python_env\idf5.5_py3.11_env\Scripts\python.exe -m pip install -r C:\Users\你的文件\esp\esp-at\esp-idf\tools\requirements\requirements.core.txt python -m pip install xlrd

6. 激活完整编译环境（关键一步）

问题现象：build.py内部调用idf.py时会选错 Python 解释器（不认新装的隔离环境），导致No module named 'esp_idf_monitor'反复出现，即使包已经装好。

解决办法：用 ESP-IDF 官方的export.bat脚本，一次性把正确的 Python、cmake、ninja、工具链路径都设置到当前 cmd 窗口的 PATH 里：
使用：cmd

esp-idf\export.bat

7. 编译

使用：cmd

python build.py build

编译成功，固件生成在build\factory目录下。

8. 烧录 / 查看日志

使用：cmd

python build.py -p COM3 flash python build.py -p COM3 monitor

（COM3换成实际串口号）

二、以后日常编译（每次开新窗口都要做）

IDF_TOOLS_PATH和export.bat设置的环境变量只在当前终端窗口有效，关闭窗口后失效。以后每次要编译，重复：

cd C:\Users\你的文件\esp\esp-at set IDF_TOOLS_PATH=C:\Users\liuch\esp\esp-at\.espressif esp-idf\export.bat python build.py build

省事办法：写成批处理脚本

在C:\Users\你的文件\esp\esp-at目录下新建dev.bat：
复制到txt中然后改文件类型尾缀即可。

@echo off cd /d C:\Users\liuch\esp\esp-at set IDF_TOOLS_PATH=C:\Users\liuch\esp\esp-at\.espressif call esp-idf\export.bat

以后开一个新 cmd 窗口：

cd C:\Users\liuch\esp\esp-at call dev.bat

注意：必须用call执行，不能直接双击dev.bat（双击会开一个新窗口跑完就关掉，环境变量留不住，回到原来的窗口没用）。

跑完call dev.bat后，直接在同一个窗口敲：

python build.py build python build.py -p COM3 flash

三、其他常用操作备忘

配置项目（可选）

python build.py menuconfig

添加自定义 AT 指令

改这两个文件（参考examples/at_custom_cmd示例）：

esp-at\examples\at_custom_cmd\custom\at_custom_cmd.c esp-at\examples\at_custom_cmd\include\at_custom_cmd.h

如果自定义组件放在独立目录（不推荐直接改esp-at\components下的原始代码），需要设置：

set AT_CUSTOM_COMPONENTS=(自定义组件的绝对路径)

更新到新版本 ESP-AT

gitfetch--all--tagsgitcheckout<新版本tag>gitsubmodulesyncgitsubmodule update--init--recursive

如果对应的 IDF 版本变了（对比module_config/module_esp32c5_default/IDF_VERSION里的 commit），删掉esp-idf目录重新走一遍第 3 步。

若本地改过代码，先git commit/git stash保存改动，切换版本后再git cherry-pick/git stash pop合并回去，解决可能的冲突。

VS Code 使用方式

• 文件 → 打开文件夹→ 选中整个esp-at目录
• 直接在里面改代码
• 编译/烧录/监视日志仍然用集成终端（选 cmd 或 PowerShell，不要用 Git Bash）敲上面的命令
• 需要更准的代码跳转/自动补全，可在.vscode/c_cpp_properties.json里加：

  "compileCommands":"${workspaceFolder}/build/compile_commands.json"