ESP-IDF v6.0 升级前先看这 3 件事：加密 API 重写、芯片边界与 2026 行动日历

ESP-IDF v6.0 升级前先看这 3 件事：加密 API 重写、芯片边界与 2026 行动日历

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

ESP-IDF v6.0 是乐鑫官方开发框架的主版本更新，组件库、构建系统、示例工程与 Wi-Fi/BLE/存储等能力都包含在内。这一版真正需要动手评估的只有两件事：加密栈整体换到 MbedTLS v4.x，全部加密调用转向 PSA Crypto API；以及 2026 年 Q1 到 Q4 的版本节奏。下面直接按"谁会受影响、影响多大、每个时间点该做什么"来讲。

加密 API 重写：哪些代码必须动，哪些只要回归

先说结论：影响只落在两类人身上。

⚡第一类，业务代码里直接调 mbedtls 接口的——这是 v6.0 升级里工作量最集中的地方。可以这么理解这次迁移：旧版里mbedtls_xxx和psa_xxx两套接口并存，4.x 之后 PSA Crypto API 成了主路径，很多传统函数被废弃或改名。你的 AES、SHA、ECDSA 调用点都要对着新接口逐个过一遍，"换个参数名"这种轻量迁移基本不存在。

mbedtls 源码以子模块形式放在 components/mbedtls/，仓库里挂的是乐鑫自维护的分支，上层封装和平台适配在components/mbedtls/port/子目录——也就是说它不是上游原版 mbedtls 的简单拷贝，个别行为差异要以乐鑫的适配代码为准。

组件的 components/mbedtls/Kconfig 里已经有一个总开关MBEDTLS_VER_4_X_SUPPORT（默认 y），控制整套 4.x 路径；CONFIG_MBEDTLS_PSA_ITS_CUSTOM_STORAGE_BACKEND（默认关）则决定 PSA 密钥存储能不能挂自定义后端，密钥存 NVS 以外的地方时才会用到。

第二类，通过组件间接用 TLS 的（esp-tls、http_client、https_server 这类用户）——代码大概率一行不用改，但要留排期。官方在 ROADMAP_CN.md 里把话说得很直白：MbedTLS v4.x 与 PSA Crypto API 的升级还在进行中，"即将发布的 beta 版本或 RC 版本可能会包含对加密 API 的进一步更新或非兼容性更新"。实际做法是：在 v6.0-beta2 或 v6.0-rc1 出来后跑一轮完整回归——编译过、TLS 握手过、证书校验过、密钥读写过，四件事都绿再切正式版。别把回归压到正式版当天，API 万一又动了一下，排期会很被动。排查兼容问题时，examples/security/（flash_encryption、key_manager）和 examples/protocols/https_server 是现成的参照路径，把项目里密钥管理与证书配置的逻辑和它们对齐着看，能快速定位差异点。

芯片支持边界：C5/C61 放心上量，H21/H4 还要等

芯片版本的支持边界以 COMPATIBILITY_CN.md 为准，跟 v6.0 直接相关的几条：

两个提醒：

• 工具命令变了：查芯片系列和版本，v6.0 起用esptool chip-id；v5.5 及更早版本还是esptool.py chip_id。写脚本的人注意这个断点，CI 里两条命令要分开配。另可用idf.py --version核对当前框架版本。
• 预览支持不等于量产支持。H4 的 v6.0 预览版适合做预研验证，别拿它跑产线。

2026 版本日历：每个节点该做什么

官方排期全部来自 ROADMAP_CN.md。文档同时声明这些是方向性计划，不是约束性承诺，具体日期可能调整。

Q1：v6.0 正式版（2026-02-27），迁移窗口从 beta 就开始了

v6.0 的 beta2 在 01/27、rc1 在 02/22、正式版 02/27 三连发。同一季度 02/13 还有 v5.5.3——还在旧分支上的团队先把这个补丁吃掉。Q1 的核心动作不是等正式版，而是用 beta/rc 把加密路径跑一遍。

Q2：v6.1-beta1（06/11）+ 旧分支密集打补丁

v6.0.1 于 06/04 发布，v6.1 走 beta1（06/11）→ rc1（07/23）→ 正式版（07/31）。旧分支方面：v5.2.7（04/28）、v5.5.4（05/08）、v5.3.6（07/02）、v6.0.2（06/04）排队落地。Q2 的任务清单就一条：用 v6.1-beta1 做第二轮回归，重点看 rc 阶段加密 API 有没有再变。

Q3：v6.1 正式版（07/31）——建议的正式切换点

v6.1 正式版之后，加密 API 基本定型，是比 v6.0 更早暴露问题的更稳切换点。同期 bugfix：v5.5.5（07/30）、v5.2.8（08/17，v5.2 的最后一发）、v6.0.3（09/10）、v6.1.1（09/03）、v5.4.5（09/28）。

Q4：v6.2（11/11 beta1 → 12/31 正式版），把主力分支定下来

v6.0 和 v6.1 两条分支全年持续出 bugfix（v6.0.4 于 11/18、v6.1.2 于 10/22、v6.1.3 于 12/16、v5.5.6 于 10/08），文档的目标是"使这两个分支更加稳定和产品化"。Q4 要做的决策是：产品线主力停在 v6.0 还是 v6.1，两条分支都长期有补丁，选哪个取决于你对 bugfix 节奏的偏好。

旧分支的迁移期限比 v6.0 发布时间更紧，这张表建议截图存档：

还在 v5.2 上的产品，2026 年 8 月 17 日之后就没有补丁可拿了；v5.3 的窗口到 2027 年 1 月 18 日关。这两条线要提前排分支切换或锁死最后 bugfix 版本，别卡在 EOL 当天。

收束：升级 v6.0 前跑完这 5 步

1. 全仓 grep 直接调用 mbedtls 接口的代码点，逐个映射到 PSA Crypto API——v6.0 里工作量最大的一块，先估时再排期。
2. beta/rc 阶段跑 TLS 全链路回归（编译、握手、证书校验、密钥读写），以examples/security/的flash_encryption、key_manager和 examples/protocols/https_server 作参照排查差异。
3. 检查构建与产测脚本：v6.0 用esptool chip-id，v5.5 及更早用esptool.py chip_id，命令断点要分开处理。
4. idf.py menuconfig确认CONFIG_MBEDTLS_VER_4_X_SUPPORT仍是 y，别被历史配置意外关掉。
5. 芯片决策：C5/C61 直接上量；H4 预览版只做预研；H21/H4 的量产支持以芯片量产状态和开发者门户跟踪页为准。

从源码分支跑 v6.0 的完整流程：

git clone https://gitcode.com/GitHub_Trending/es/esp-idf cd esp-idf && git checkout release/v6.0 ./install.sh # Windows 用 install.bat source export.sh # 每个新终端重新执行一次 cd 示例工程 && idf.py set-target esp32c6 && idf.py build flash monitor

Wi-Fi 相关场景的验证工程在 examples/wifi/ 下，getting_started、power_save、ftm各子目录可按测试目标直接取用。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf