ESP-IDF 6配网迁移清单：组件依赖、API改名与手机端兼容

作者LIU, ZHUOHUI

ESP-IDF配网迁移要以目标手机能完成配置、能从规定故障恢复为终点。编译成功只是中间门槛，依赖、管理器生命周期、安全支持和已安装App的兼容性都应进入变更记录。

版本边界：本文使用固定ESP-IDF v6.0迁移指南与v5.5参考基线。产品需另外选择准确发行版本；本文未编译项目或执行硬件测试，示例属于模板，验收结果需要由具体工程补齐。

冻结迁移前后的版本基线

改依赖前先归档已知可用版本，包括IDF tag或提交、芯片目标、工具链、应用提交、分区表、sdkconfig、sdkconfig.defaults、组件清单和依赖锁文件。手机App构建与配网库提交同样需要保存。“IDF 5”和“最新版App”无法复现。

保留一次正常配网和一次受支持失败重试的脱敏日志，记录应用实际选择的安全方案、手机需要的入网材料。源配置与构建生成配置可能不同，两者都要保存，避免把旧工程继承的选项误认为SDK新默认。

把配网组件变成显式依赖

v6.0迁移指南明确wifi_provisioning移出IDF主树，后继组件为network_provisioning。项目应在组件manifest中声明外部依赖，不能继续依赖原来随SDK提供的组件。

下面是示意YAML模板，并非已经构建的工程。占位值必须替换成针对所选IDF和芯片验证过的精确版本，同时保存解析出的依赖锁。

# main/idf_component.yml：示意模板
dependencies:
  espressif/network_provisioning:
    version: "<validated exact release>"

官方示例中的版本范围不能证明范围内每个解析结果都通过产品测试。应查看所选版本在组件注册表中的依赖；这里的1.3.1仅作为版本化文档引用，并非硬件验证推荐。锁文件改变前先审查差异。

若先在5.x引入新组件，需按迁移说明排除旧wifi_provisioning构建。将这一阶段独立提交，便于区分组件替换造成的故障与IDF升级造成的故障。

核对API和生命周期变更

多数接口前缀由wifi_prov改为network_prov，但部分管理器函数还增加了wifi。下表列后缀；旧前缀是wifi_prov_mgr_，新前缀是network_prov_mgr_。具体声明仍应核对已解析组件的头文件。

v6.0指南特别列出的管理器后缀变化
旧后缀 新后缀 核查路径
is_provisioned is_wifi_provisioned 启动判断
configure_sta configure_wifi_sta 凭据应用
reset_provisioning reset_wifi_provisioning 存储状态重置
reset_sm_state_on_failure reset_wifi_sm_state_on_failure 失败尝试恢复
reset_sm_state_for_reprovision reset_wifi_sm_state_for_reprovision 受控重新进入

除了函数名，还要搜索头文件、回调类型、事件、构建依赖和配置项。顺序走查初始化、首次配网、取消、失败、成功、反初始化、再次配网，确认每条路径由谁拥有管理器、谁能释放传输资源。正常路径通过编译，仍可能留下错误的清理假设。

重新审查安全配置与手机端能力

v6.0迁移指南指出protocomm Security 0和1的支持默认关闭。这影响构建支持哪些方案，不会自动改写应用选择，也不会自动升级用户已安装的手机库。

检查生成sdkconfig里的CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0和CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1。旧配置可能保留显式取值。同版本protocomm API页的默认值介绍仍与迁移页不同，工程判断应核对实际配置和目标SDK源码，不能直接照抄该段文字。

protocomm参考说明Security 0不提供加密和认证，并推荐生产采用Security 2。切换到Security 2时，需要同时验证手机库支持及设备专属入网材料流程。若有明确兼容需求而暂留Security 1，应记录理由、期限和认证测试；不能把关闭安全作为握手失败的生产解决办法。

从干净构建走到协议握手

从依赖锁定、干净构建、安全握手到恢复测试与放行证据的迁移检查门槛
原创迁移门槛图；上一项通过不代表下一项已经通过。

建立只包含迁移改动的小分支，在干净构建目录里执行构建，保存依赖解析、编译链接输出、镜像标识和配置差异。随后先验证发现和安全会话，再提交网络凭据。失败要区分依赖解析、编译链接、传输发现、安全协商和Wi-Fi配置，避免全部归因于新SDK。

首次成功后，继续验证取消、重新进入、错误凭据、管理器停止和预期资源释放策略。在与旧基线相同的负载下比较堆和任务状态，测量前先规定可接受余量。为调试握手增加日志时，也不能泄露入网秘密。

安排旧新App和旧新固件交叉回归

最小版本交叉矩阵
组合 要求结果
支持中的旧App＋迁移固件 完成声明的安全与配网流程，或显示已批准的升级要求。
新App＋支持中的旧固件 选择受支持协议，不静默降低安全策略。
新App＋迁移固件 首次配网、失败恢复和授权重新进入都可完成。
不支持组合 在产生误导性成功状态前说明下一步。

使用实际分发的App构建以及产品声明支持的手机和系统。SoftAP、BLE按实际出货通道覆盖，不凭空增加第二套通道。复用配网恢复指南的故障用例，并在真实升级路径需要时保留旧凭据。每次都安装全新App可能掩盖存量用户问题。

给迁移建立放行和回退记录

放行记录关联旧新镜像、依赖锁、API和配置差异、手机矩阵、失败用例、修复提交与最终重测结果。每个声明支持的组合必须有通过记录，或有明确接受的限制。未测量的恢复时间和资源数据留空，不填“预计达标”。

源码回退与设备回退分别留证。分支能恢复旧提交，不代表已部署设备能接受旧镜像，也不代表旧固件能解释迁移后的持久状态。设备恢复需遵守bootloader、安全版本和更新策略；没有回退路径时，应在发布前写清向前修复或返修方法。

评估具体迁移范围时，可向Obeita固件诊断团队提供现有工程版本、目标芯片、组件清单、手机库与安全方案，以此确定可审核的回归范围。

类似文章