ESP-IDF 工程最容易让人卡住的地方不一定是业务代码而是工程本身。路径里有中文或空格、环境变量没激活、目标芯片没设置、组件没被 CMake 找到、板厂 Demo 目录结构太乱这些问题加起来比传感器算法本身还耗时间。这次我没有从一个完全空的工程开始写屏幕和网络而是先拿 ESP32-S3-LCD-1.47 的板厂 Demo 跑起来再把它改造成自己的传感器项目。这样做不是偷懒而是避开一开始就掉进 LCD、背光、LVGL 刷新这些板级细节里。第一步不是写代码是确认工具链能跑在 Windows 上做 ESP-IDF我不建议一开始就手动拼环境变量。官方安装器或 VS Code ESP-IDF 插件能省掉很多基础麻烦。安装好以后先在 PowerShell 里确认idf.py可用。powershellpowershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py --version能看到版本号说明环境至少能被激活。这里有个坑VS Code 里看到的构建按钮不等于 PowerShell 命令。终端里真正需要跑的是idf.py build。如果终端里找不到idf.py先别改代码先修环境。工程路径也要尽量简单。我一般放在类似这样的目录textC:\esp\sensor_demo路径里不要有中文和空格。不是说一定不能用而是后续组件、脚本、构建缓存一多简单路径能少出很多奇怪问题。空工程先跑通再碰板厂 Demo如果 ESP-IDF 以前没在这台电脑上跑过我会先建一个空工程powershellcd C:\esppowershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py create-project sensor_democd C:\esp\sensor_demopowershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py set-target esp32s3powershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py build这一步没有业务价值但有排查价值。空工程都编不过时后面任何业务错误都不可信。先让最小工程过一遍再去跑板厂 Demo排查范围会小很多。板厂 Demo 先别急着删ESP32-S3-LCD-1.47 的屏幕、背光、RGB、LVGL 都涉及板级代码。如果一开始就大删特删屏幕不亮时很难知道是删错了还是自己加的代码有问题。更稳妥的顺序是text1. 原始 Demo 原封不动编译2. 烧录后确认屏幕、背光、基础 UI 正常3. 建一个自己的分支或备份4. 删掉和项目无关的功能5. 每删一块就编译一次6. 再加 BME690、WiFi 后台和数据上传。这个流程看起来啰嗦但能避免一个很烦的问题删了十几个文件以后才发现工程不能编译却不知道是哪一步删坏了。我会把 main.c 当成启动入口而不是杂物间很多小项目最后都会变成一个巨大的main.c。刚开始写很方便后面加传感器、WiFi、网页、屏幕、上传以后就会越来越难维护。我更喜欢把main.c保持得短一点只安排启动顺序cvoid app_main(void){ init_nvs_storage(); RGB_Init(); LCD_Init(); BK_Light(70); LVGL_Init(); sensor_bme690_start(); app_wifi_start(); app_upload_start(); app_ui_start();}这段代码看起来没什么技术含量但它让工程结构清楚很多。传感器出问题就看sensor_bme690网页打不开就看app_wifi屏幕刷新不对就看app_ui。不要让所有模块都在main.c里互相调用。目录结构要早点定下来一个比较清楚的工程可以这样放textC:\esp\sensor_demo├─ CMakeLists.txt├─ sdkconfig.defaults├─ partitions.csv├─ main│ ├─ main.c│ ├─ app_ui.c│ ├─ app_ui.h│ ├─ app_wifi.c│ ├─ app_wifi.h│ ├─ app_upload.c│ ├─ app_upload.h│ ├─ sensor_bme690.c│ ├─ sensor_bme690.h│ ├─ LCD_Driver│ ├─ LVGL_Driver│ ├─ RGB│ └─ Wireless└─ components ├─ bosch_bme690 ├─ lvgl__lvgl └─ espressif__led_strip目录结构不是为了好看而是为了以后排查问题。比如上传失败时应该知道去app_upload找传感器读数不对应该去sensor_bme690找屏幕状态不刷新应该去app_ui找。早期不拆后面再拆会很痛。因为功能已经缠在一起了移动一个函数可能影响一串东西。CMake 出错时先看组件有没有被声明ESP-IDF 工程里文件存在不代表编译器能找到。很多“找不到头文件”的问题其实是 CMake 没把目录或依赖声明清楚。main/CMakeLists.txt里应该把需要的源文件、头文件目录和依赖组件写清楚。示例cmakeidf_component_register( SRCS main.c app_ui.c app_wifi.c app_upload.c sensor_bme690.c INCLUDE_DIRS . REQUIRES nvs_flash esp_wifi esp_http_server bosch_bme690)如果sensor_bme690.c里引用了 BME690 驱动头文件但REQUIRES没写对应组件就可能编译不过。不要看到报错就先改 include 路径先看组件关系是否合理。依赖版本不要乱升板厂 Demo 里常常带着已经适配好的 LVGL、LCD 驱动和其他组件。这个时候不要一上来就把依赖全部升级到最新。尤其是 LVGL不同版本 API 差异可能很大升级以后屏幕代码可能要跟着改。idf_component.yml可以先保持相对稳定yamldependencies: idf: 4.4 lvgl/lvgl: ~8.3.0 espressif/led_strip: ^2.4.1后续真的需要升级再单独开一个分支处理。早期目标是把传感器和网页跑起来不是先和依赖版本搏斗。构建、烧录、监视要分清ESP-IDF 常用命令就几个但刚开始容易混。编译powershellpowershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py build烧录powershellpowershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py -p COM3 flash看串口powershellpowershell -ExecutionPolicy Bypass -NoProfile -Command . D:\esp\v6.0.1\esp-idf\export.ps1; idf.py -p COM3 monitor如果端口不是 COM3就先查串口powershellGet-CimInstance Win32_SerialPort | Select-Object DeviceID,Name这里也有个小坑有时候烧录端口和监视端口一样但设备重启后端口会短暂消失。不要看到一次连接失败就立刻怀疑代码先确认设备有没有重新枚举完成。网页后台跑起来以后工程才真正开始像项目串口能看到 BME690 数据只能说明底层读数工作。网页后台跑起来以后工程才开始有完整使用感。浏览器能看到温湿度、气压、气体阻值、联网状态和上传状态调试会轻松很多。网页后台不需要一开始做得漂亮但字段要真实。尤其是时间戳、数据来源、传感器状态和上传结果最好都显示出来。页面越透明越容易定位问题。写到这里工程搭建最大的经验是别贪快ESP-IDF 工程搭建不难但容易乱。最稳的办法不是一次性把所有功能都加进去而是空工程、板厂 Demo、传感器、WiFi、网页后台一层一层叠。如果你也在做类似项目建议先记住三件事路径保持简单板厂 Demo 先原样跑通main.c不要变成大杂烩。做到这三点后面遇到编译错误、屏幕不亮、传感器没数据时排查范围会小很多。阅读顺序这一组文章建议按标题前面的序号阅读01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10。当前这篇是 04ESP-IDF 工程搭建把开发板 Demo 改造成自己的传感器项目。下一篇下一篇 05让板子有界面用 LVGL 做一个能看懂状态的硬件屏