ESP-IDF v6.0 升级指南：PSA Crypto 迁移与新芯片支持

ESP-IDF v6.0 升级指南PSA Crypto 迁移与新芯片支持【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfESP-IDF v6.0 将加密栈升级至 MbedTLS v4.0 并全面转向 PSA Crypto 接口同时新增 ESP32-H4 芯片预览支持构建与工具链也有一批改动。如果你直接调用过mbedtls_sha*、mbedtls_md*等加密 API本文帮你定位迁移点如果你的项目面向 ESP32-H4或已在用 C5/C61 新硬件如果你需要判断手头 v5.x 项目现在升级还是等 bugfix这个版本在解决什么问题v6.0 是乐鑫规划的 2026 年度主线版本仓库自带的迁移文档标题就是「从 5.5 迁移到 6.0」说明它承接的是 v5.x 系列。ROADMAP.md 给出了明确节奏2026 年 1 月底 beta2、2 月底 RC1 与正式版、4 月第一个 bugfixv6.0.1同一条路线上还排了 7 月的 v6.1 和年底的 v6.2。它要解决三件事加密接口统一到 PSA 标准、芯片矩阵继续扩张、以及构建系统与工具链的整理。旧版本也不会被放弃——同一份路线图里5.2/5.3/5.4/5.5 各分支都排了 bugfix 计划直到它们分别进入 EOL5.2 是 2026 年 8 月5.3 是 2027 年 1 月。功能深潜按场景看变化加密相关MbedTLS v4.0PSA Crypto 成为主接口这是 v6.0 影响面最大的变更。加密库 components/mbedtls 已切到 MbedTLS v4.0加密功能由 TF-PSA-Crypto 提供MbedTLS 本身侧重 TLS 与 X.509。对使用者的直接影响在迁移文档 docs/zh_CN/migration-guides/release-6.x/6.0/security.rst 里写得很清楚传统加密原语 APImbedtls_sha*_*()、mbedtls_md*_*()等已被移除不是改名而是删掉执行任何加密操作前必须完成psa_crypto_init()常规启动流程里 ESP-IDF 会代劳但早于启动流程运行的代码如某些安全启动场景需显式调用esp_ecdsa_*系列旧函数被移除改用esp_ecdsa_opaque_key_t配合psa_import_key()完成密钥导入以适配 ECDSA 硬件的不透明密钥原来需要传f_rng/p_rng回调的 API 改为 PSA RNGMBEDTLS_THREADING_C默认启用默认禁用secp192r1曲线。受益人群是任何用到 TLS、证书解析、安全启动、密钥运算的项目。文档同时提示 PSA 迁移可能增加 flash 占用具体数值取决于你启用的功能集合建议升级后先量一次体积。新硬件支持ESP32-H4 进入预览C5/C61 已是正式版COMPATIBILITY_CN.md 列出了芯片支持矩阵ESP32-H4 从 v6.0 开始提供预览支持ESP32-C5v1.0和 ESP32-C61v1.0则从 v5.5.2 起就是正式支持。ROADMAP 同时把 ESP32-H21、ESP32-H4 的量产版支持列为 2026 年目标。要注意文档里的一句提醒预览版本的支持在芯片正式支持版本发布后就会结束量产项目请以正式发布版本为准H4 项目先用 6.0 做技术预研是合适的但量产决策要等正式版本。构建与迁移工具13 个专题的迁移指南v6.0 的迁移文档不是一篇大而全的说明而是按模块拆成了 13 个专题页放在 docs/zh_CN/migration-guides/release-6.x/6.0/ 下build-system、wifi、networking、toolchain、tools、storage、system、peripherals、protocols、provisioning、bluetooth-classic、security 等。好处是你能只读与自己相关的章节比如只用 Wi-Fi 的项目看 wifi.rst 和 networking.rst 即可。现在就能验证什么按顺序做以下五步每步都有可验证的结果获取代码并装工具链命令输出无报错、提示环境已导出即成功git clone https://gitcode.com/GitHub_Trending/es/esp-idf cd esp-idf ./install.sh . ./export.sh运行idf.py --version终端回显 v6.0 系版本号当前仓库为 6.0 开发版。挑一个入门示例编译例如examples/get-started/blinkidf.py build产物目录里出现.bin文件。用esptool chip-id读取目标板芯片型号与版本对照 COMPATIBILITY_CN.md 确认你手上的芯片在支持矩阵内。通读一遍 security.rst 迁移文档在本地代码里全局搜索mbedtls_sha、mbedtls_md、esp_ecdsa_load_pubkey搜出来的每个命中都是待迁移点。升级决策参考该升新项目直接起步 v6.0面向 ESP32-H4 的开发代码里还在写传统mbedtls_*原语的项目早迁移早省事。该等量产中的 v5.x 项目不必赶在 2 月正式版当天切换先用路线图里的 bugfix 版本如 5.2 线排到 v5.2.7/5.2.8顶住EOL 前留出迁移窗口即可。v6.0 主要 breaking changes 对照摘自 security 迁移文档变更点v5.x 行为v6.0 处理方式加密原语 APImbedtls_sha*/mbedtls_md*可用已移除改用 PSA Crypto APIECDSA 密钥esp_ecdsa_*系列函数改用esp_ecdsa_opaque_key_tpsa_import_key()随机数API 传f_rng/p_rng回调统一走 PSA RNG线程安全MBEDTLS_THREADING_C默认关默认开启保持开启常见问题 FAQ老项目代码不改能直接编译吗只调用esp_tls、esp_https_ota这类高层接口的项目大概率兼容直接使用传统加密原语或esp_ecdsa_*旧函数的项目会编译失败这类代码需要按 security.rst 逐处改写。预览支持和正式支持差在哪以 COMPATIBILITY_CN.md 的定义预览版支持在芯片正式支持版本发布后结束不再维护正式版还区分「需求版本」低于它芯片可能异常和「推荐版本」低于它可能用不上新特性。量产请以正式版为准。5.2/5.3 的老项目是不是被抛弃了不是。路线图里 5.2 线 2026 年内还有 v5.2.74 月和 v5.2.88 月5.3 线排到 2027 年 1 月的 v5.3.7EOL 前持续提供 bugfix。PSA 迁移会增加多少 flash文档没有给统一数字明确说明「取决于启用的功能」并给出了非 PSA 构建与 PSA 迁移后的对照表。实际做法是以自己项目的完整配置编译后对比idf.py size输出。行动清单收尾全局搜索代码中的mbedtls_sha、mbedtls_md、esp_ecdsa_load_pubkey、f_rng列出待迁移 API 清单通读 docs/zh_CN/migration-guides/release-6.x/6.0/ 下与自己模块相关的迁移页用 beta/RC 分支搭一条独立编译线验证示例可构建、体积变化可接受给老项目的 5.x 分支规划 bugfix 升级时间点对照 ROADMAP.md 的 EOL 日期确认目标芯片型号与版本核对 COMPATIBILITY_CN.md 中的需求版本下一步去哪里等你完成上面清单就等待 2026 年 2 月底的 v6.0 正式版发布说明届时以 release notes 和 6.0 迁移指南的定稿版本作为最终迁移依据。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考