企业官网建设流程全解析

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

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

ESP-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 月第一个 bugfix（v6.0.1），同一条路线上还排了 7 月的 v6.1 和年底的 v6.2。

它要解决三件事：加密接口统一到 PSA 标准、芯片矩阵继续扩张、以及构建系统与工具链的整理。旧版本也不会被放弃——同一份路线图里，5.2/5.3/5.4/5.5 各分支都排了 bugfix 计划，直到它们分别进入 EOL（5.2 是 2026 年 8 月，5.3 是 2027 年 1 月）。

功能深潜：按场景看变化

加密相关：MbedTLS v4.0，PSA 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 里写得很清楚：

• 传统加密原语 API（mbedtls_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 RNG；MBEDTLS_THREADING_C默认启用，默认禁用secp192r1曲线。

受益人群是任何用到 TLS、证书解析、安全启动、密钥运算的项目。文档同时提示 PSA 迁移可能增加 flash 占用，具体数值取决于你启用的功能集合，建议升级后先量一次体积。

新硬件支持：ESP32-H4 进入预览，C5/C61 已是正式版

COMPATIBILITY_CN.md 列出了芯片支持矩阵：ESP32-H4 从 v6.0 开始提供预览支持；ESP32-C5（v1.0）和 ESP32-C61（v1.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 即可。

现在就能验证什么

按顺序做以下五步，每步都有可验证的结果：

1. 获取代码并装工具链，命令输出无报错、提示环境已导出即成功：

git clone https://gitcode.com/GitHub_Trending/es/esp-idf cd esp-idf && ./install.sh && . ./export.sh

2. 运行idf.py --version，终端回显 v6.0 系版本号（当前仓库为 6.0 开发版）。
3. 挑一个入门示例编译，例如examples/get-started/blink，idf.py build产物目录里出现.bin文件。
4. 用esptool chip-id读取目标板芯片型号与版本，对照 COMPATIBILITY_CN.md 确认你手上的芯片在支持矩阵内。
5. 通读一遍 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 迁移文档）：

常见问题 FAQ

老项目代码不改能直接编译吗？

只调用esp_tls、esp_https_ota这类高层接口的项目大概率兼容；直接使用传统加密原语或esp_ecdsa_*旧函数的项目会编译失败，这类代码需要按 security.rst 逐处改写。

预览支持和正式支持差在哪？

以 COMPATIBILITY_CN.md 的定义：预览版支持在芯片正式支持版本发布后结束，不再维护；正式版还区分「需求版本」（低于它芯片可能异常）和「推荐版本」（低于它可能用不上新特性）。量产请以正式版为准。

5.2/5.3 的老项目是不是被抛弃了？

不是。路线图里 5.2 线 2026 年内还有 v5.2.7（4 月）和 v5.2.8（8 月），5.3 线排到 2027 年 1 月的 v5.3.7，EOL 前持续提供 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