mimiclaw/docs/ESP-IDF-V6-MIGRATION.md

ESP-IDF v6.0 编译适配记录

日期：2026-03-31 目标芯片：ESP32-S3 ESP-IDF 版本：v6.0 问题：从旧版本迁移到 ESP-IDF v6.0 后编译失败，存在多处头文件缺失、配置错误、CMakeLists 遗漏

---

问题清单与修复

1. Flash 大小配置错误

错误信息：

Partitions tables occupies 16.0MB of flash which does not fit in configured flash size 2MB

修复： sdkconfig 中 flash 大小从 2MB 改为 16MB

• CONFIG_ESPTOOLPY_FLASHSIZE_2MB=y → CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
• CONFIG_ESPTOOLPY_FLASHSIZE="2MB" → CONFIG_ESPTOOLPY_FLASHSIZE="16MB"

2. WiFi 断开原因码未定义

错误信息：

error: 'WIFI_REASON_ASSOC_EXPIRE' undeclared

修复： main/wifi/wifi_manager.c — 为所有 reason code 添加 #ifdef 保护（ESP-IDF v6.0 移除了部分原因码）

3. CMakeLists.txt 缺少源文件

修复： main/CMakeLists.txt

• 添加 "ota/ota_manager.c" 到 SRCS 列表

4. 头文件缺失（共修复 16 处）

文件	缺失头文件	使用符号
main/cli/serial_cli.c	llm/llm_provider.h	llm_provider_set_api_key
main/llm/llm_provider.c	esp_http_client.h	esp_http_client_set_header
main/bus/message_bus.c	freertos/FreeRTOS.h, freertos/queue.h	xQueueCreate, QueueHandle_t
main/wifi/wifi_manager.c	esp_event.h	esp_event_handler_instance_register
main/wifi/wifi_manager.c	freertos/FreeRTOS.h, freertos/task.h, freertos/event_groups.h	xEventGroupCreate, vTaskDelay
main/ota/ota_manager.c	esp_system.h	esp_restart
main/channels/telegram/telegram_bot.c	freertos/FreeRTOS.h, freertos/task.h	xTaskCreatePinnedToCore, vTaskDelay
main/channels/telegram/telegram_bot.c	esp_err.h	esp_err_to_name
main/tools/tool_registry.c	<stdlib.h>	free()
main/proxy/http_proxy.c	<sys/time.h>	struct timeval
main/gateway/ws_server.c	<stdint.h>	uint8_t

---

ESP-IDF v6.0 API 兼容性验证

以下 API 在 v6.0 中仍然可用，无需修改：

API	位置	状态
esp_spiffs_info()	esp_spiffs.h	✅ 存在
esp_websocket_client_send_bin()	esp_websocket_client.h	✅ 存在
esp_tls_set_conn_sockfd()	esp_tls.h	✅ 存在
esp_tls_set_conn_state()	esp_tls.h	✅ 存在
esp_console_new_repl_uart()	esp_console.h	✅ 存在
esp_console_new_repl_usb_serial_jtag()	esp_console.h	✅ 存在
esp_console_new_repl_usb_cdc()	esp_console.h	✅ 存在
esp_https_ota() + esp_https_ota_config_t	esp_https_ota.h	✅ 存在
esp_wifi_set_config()	esp_wifi.h	✅ 存在

---

烧录说明

ESP32-S3 烧录使用 USB 口（内置 USB Serial/JTAG 控制器）：

idf.py -p COMx flash monitor

• 插 USB 口（标记为 USB），不是 UART 口
• 如遇连接失败，按住 BOOT 键再插线进入下载模式

---

ESP-IDF v6.0 API 变更与修复（2026-04-01）

5. SNTP API 弃用问题

错误信息：

warning: 'sntp_setoperatingmode' is deprecated: use esp_sntp_setoperatingmode() instead
warning: 'sntp_setservername' is deprecated: use esp_sntp_setservername() instead
warning: 'sntp_init' is deprecated: use esp_sntp_init() instead

修复： main/time_sync/time_sync.c

• 将所有 sntp_* 函数调用替换为 esp_sntp_* 函数
• 示例：sntp_init() → esp_sntp_init()

注意： esp_sntp 组件在 v6.0 中不存在，esp_sntp_* 函数属于 lwip 组件，会被 esp_netif 和 esp_wifi 自动包含。

6. NVS API 兼容性变化

错误信息：

error: too few arguments to function 'nvs_entry_find'; expected 4, have 3
error: passing argument 1 of 'nvs_entry_next' from incompatible pointer type

修复： main/nvs_safety/nvs_safety.c

• nvs_entry_find() 现在需要 4 个参数：nvs_entry_find(part_name, namespace, type, &iterator)
• nvs_entry_next() 需要指向迭代器的指针：nvs_entry_next(&iterator)
• 新增 nvs_release_iterator() 调用释放迭代器

建议： 使用 nvs_entry_find_in_handle() 替代 nvs_entry_find()，更简洁。

7. 结构体类型错误

错误信息：

error: expected specifier-qualifier-list before 'arg_str1'

修复： main/cli/serial_cli.c

• arg_str1 *server; → struct arg_str *server;
• arg_end *end; → struct arg_end *end;

原因： arg_str1 是函数名，不是类型。结构体成员应使用 struct arg_str 类型。

8. 未使用的函数警告

错误信息：

warning: 'provider_is_openai' defined but not used

修复： main/llm/llm_proxy.c

• 删除未使用的 provider_is_openai() 函数
• 该函数只是调用 llm_provider_is_openai_compatible()，可直接使用原函数

9. 组件依赖问题

错误信息：

Failed to resolve component 'esp_sntp' required by component 'main': unknown name.

修复： main/CMakeLists.txt

• 从 REQUIRES 列表中移除 esp_sntp 组件
• esp_sntp_* 函数属于 lwip 组件，会被其他网络组件自动包含

---

API 兼容性总结

已验证的 API（v6.0 中仍然可用）

API	状态
esp_http_client_set_header()	✅ 未弃用
esp_crt_bundle_attach()	✅ 未弃用
esp_netif_create_default_wifi_sta()	✅ 未弃用
WIFI_INIT_CONFIG_DEFAULT()	✅ 未弃用

已弃用的 API（需要替换）

旧 API	新 API	文件
sntp_*()	esp_sntp_*()	time_sync.c
nvs_entry_find(part, ns, type)	nvs_entry_find(part, ns, type, &it)	nvs_safety.c
nvs_entry_next(it)	nvs_entry_next(&it)	nvs_safety.c