↓ Skip to main content
Developer Portal
Developer Portal

ESP-IDF

Table of Contents
探索 ESP-IDF——乐鑫面向全系列 SoC 的官方开发框架，用于构建可量产的应用。

English version

欢迎使用 ESP-IDF

ESP-IDF——乐鑫物联网开发框架（Espressif IoT Development Framework）——是我们面向每一款乐鑫 SoC 的官方、可量产级 SDK。无论您在搭建传感器节点原型、交付 Matter 认证产品，还是构建带 AI 的边缘设备，ESP-IDF 都将驱动程序、网络协议栈、安全能力与构建工具集于一处，让您专注于应用本身。

为何选择 ESP-IDF

一套框架，多款芯片。 在所有乐鑫 SoC 系列上使用相同的 API、构建系统与工作流。可切换到最新发布的芯片以获得新特性，或切换到更具成本优势的芯片以控制 BOM——而无需改动应用代码。

面向真实产品。 ESP-IDF 驱动着全球已出货逾十亿颗 ESP 芯片上的应用。我们的发布路线图包含定期的功能版与修复版。

GitHub 开源。 您可以直接阅读源码，并与全球贡献者与商业伙伴共建生态。

最新发行版支持的 SoC

最新 ESP-IDF 发行版 — 支持下列完整乐鑫产品线——按射频、性能与外设选型，并在产品演进过程中沿用同一套框架。

ESP32
Wi-Fi & Bluetooth Classic & BLE
ESP32-S2
Wi-Fi
ESP32-S3
Wi-Fi & BLE
ESP32-C2
Wi-Fi & BLE
ESP32-C3
Wi-Fi & BLE
ESP32-C5
Wi-Fi & BLE
ESP32-C6
Wi-Fi、BLE 与 IEEE 802.15.4
ESP32-C61
Wi-Fi & BLE
ESP32-H2
BLE 与 IEEE 802.15.4
ESP32-P4
高性能

如需查看权威且最新的列表（包括新增的芯片和目标平台），请参阅 ESP-IDF 兼容性——各芯片版本的详细 ESP-IDF 支持情况。

新芯片支持状态

跟踪乐鑫新芯片在 ESP-IDF 及相关框架中的支持情况，并提供每款芯片的详细状态页面和发布进展更新链接。

Hardware Support

Browse Espressif hardware resources, including DevKits, hardware design guidelines, the official KiCad library, and support status pages for new chips across SDKs and frameworks.

安装 ESP-IDF

在 Windows、macOS 与 Linux 上最快的方式是使用 ESP-IDF 安装管理器（EIM）。它会安装工具链、Python 环境与 ESP-IDF 本体，让您无需再手动查找和安装各项依赖，即可运行 idf.py build。

下载

从 EIM 下载页 获取图形安装包、便携压缩包与发行合集，或通过各平台包管理器安装 EIM：

包管理器（推荐）

# 安装图形界面版本
winget install Espressif.EIM
# 仅安装 CLI 版本
winget install Espressif.EIM-CLI

如需更新 EIM：

winget upgrade Espressif.EIM

手动下载： 从 EIM 下载页 或 GitHub Releases 获取安装包，然后运行 .exe。安装程序会自动检测并安装缺失的依赖项，并引导您完成设置流程。

Note

如果您下载的是 CLI 专用版本（例如 eim-cli-*.exe），必须从终端/命令提示符运行，而不是双击。双击会短暂打开终端窗口，显示帮助信息后立即关闭——看起来像安装程序崩溃了。请打开 PowerShell，切换到文件所在目录，然后运行 .\eim-cli-*.exe --help。

安装完成后，可从「开始」菜单启动图形界面版本，或使用 CLI：

eim install

包管理器（推荐）

# 添加 EIM tap
brew tap espressif/eim
# 安装图形界面版本（可从「应用程序」启动）
brew install --cask eim-gui
# 或仅安装 CLI 版本（可在终端运行）
brew install eim

如需更新 EIM：

brew upgrade eim
# 或
brew upgrade --cask eim-gui

手动下载： 您也可以从 EIM 下载页 下载 macOS 的 .dmg 或 .zip 安装包——适合离线安装场景。

Homebrew 适用于大多数 Linux 发行版：

# 添加 Espressif tap
brew tap espressif/eim
# 仅安装 CLI 版本
brew install eim
# 或安装图形界面版本（包含 CLI）
brew install --cask eim-gui

如需更新 EIM：

brew upgrade eim
# 或
brew upgrade --cask eim-gui
Note

图形界面版本需要图形环境，具体依赖取决于您的 Linux 发行版。

包管理器（推荐） — Debian、Ubuntu、Linux Mint 等。

安装 Espressif 签名密钥并添加已签名的 APT 软件源：

# 安装 Espressif 签名密钥
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://dl.espressif.com/dl/eim/eim.gpg -o /etc/apt/keyrings/eim.gpg
sudo chmod 0644 /etc/apt/keyrings/eim.gpg

# 添加 Espressif APT 软件源（deb822，启用 signed-by）
sudo curl -fsSL https://dl.espressif.com/dl/eim/eim.sources -o /etc/apt/sources.list.d/espressif.sources

# 更新软件包索引
sudo apt update

# 仅安装 CLI 版本
sudo apt install eim-cli
# 或安装图形界面版本（包含 CLI）
sudo apt install eim

如需更新 EIM：

sudo apt update && sudo apt upgrade eim

手动下载： 使用 EIM 下载页 获取 .deb 包或 Linux 便携二进制。

包管理器（推荐） — Fedora、RHEL、CentOS、openSUSE 等。

导入 Espressif 签名密钥并添加 RPM 仓库：

# 导入 Espressif 签名密钥
sudo rpm --import https://dl.espressif.com/dl/eim/eim.asc

# 添加 Espressif RPM 仓库
sudo curl -fsSL https://dl.espressif.com/dl/eim/rpm/eim.repo -o /etc/yum.repos.d/espressif-eim.repo

# 仅安装 CLI 版本
sudo dnf install eim-cli
# 或安装图形界面版本（包含 CLI）
sudo dnf install eim

注意： eim.repo 同时启用 gpgcheck=1（校验每个软件包）和 repo_gpgcheck=1（校验仓库元数据）。如果您之前使用 gpgcheck=0 手动配置过该仓库，可继续使用——本次变更仅影响新安装。

如需更新 EIM：

sudo dnf upgrade eim

手动下载： 使用 EIM 下载页 获取 RPM 包或 Linux 便携二进制。

包管理器（推荐） — Arch Linux、Manjaro、EndeavourOS、CachyOS 等。

# 1. 导入并在本地签名 Espressif 签名密钥（一次性操作，必须在 pacman -Syu 前完成）
curl -fsSL https://dl.espressif.com/dl/eim/eim.asc | sudo pacman-key --add -
sudo pacman-key --lsign-key 06E9A6C0325E124198C685F18B1F38BDC9383E1D

# 2. 将 EIM pacman 仓库添加到 /etc/pacman.conf
sudo tee -a /etc/pacman.conf << 'EOF'
[eim]
SigLevel = Required DatabaseOptional TrustAll
Server = https://dl.espressif.com/dl/eim/pacman/$arch
EOF

# 3. 更新软件包数据库
sudo pacman -Syu

# 4. 仅安装 CLI 版本
sudo pacman -S eim-cli
# 或安装图形界面版本（包含 CLI）
sudo pacman -S eim-gui

重要： 第 1 步（导入密钥）必须在执行 pacman -Syu 之前完成。否则 pacman 无法验证仓库数据库，会拒绝同步。密钥指纹为 06E9A6C0325E124198C685F18B1F38BDC9383E1D。

注意： 图形界面版本依赖 gtk4、libadwaita 和 webkit2gtk-4.1，在某些发行版上可能需要额外配置。

如需更新 EIM：

sudo pacman -Syu

手动下载： 使用 EIM 下载页 获取 Arch Linux 包或便携二进制。

EIM 完成后，您即拥有基于 CMake 的工程、Xtensa 与 RISC-V 工具链，以及在各支持操作系统上一致的 idf.py 工作流。

IDE 与编辑器

继续使用您熟悉的工具即可。ESP-IDF 以 CMake 为先，任何具备良好 CMake 与 C/C++ 支持的编辑器都很合适。若要一体化体验，可从下列入口开始：

  • Visual Studio Code — 官方 ESP-IDF 扩展：在编辑器内完成配置、烧录、监视与 SDK 配置
  • Eclipse — 面向 Eclipse 用户的 ESP-IDF 插件
  • CLion — 以 CMake 配置文件打开工程，利用导航与调试能力

延伸阅读：文档

从点亮 LED 到量产所需的资源：

AI 辅助开发（MCP）

通过 模型上下文协议（Model Context Protocol，MCP） 服务器将 ESP-IDF 接入助手与自动化：

  • ESP-IDF Tools Local MCP Server（ESP-IDF v6.0+）— 向兼容的助手暴露您的工程；使用 eim run "idf.py mcp-server" 运行（例如 VS Code Copilot、Cursor）
  • Espressif Documentation MCP Server — 让工具查询当前乐鑫文档（含 ESP-IDF），获得与已发布文档一致的回答

ESP 组件仓库

跳过样板代码，直接使用来自官方 ESP 组件仓库（ESP Component Registry） 的持续维护、带版本管理的基础组件，包括驱动、协议、UI 辅助工具、云连接器等。你可以添加依赖，而无需将整个代码库复制到项目中：

idf.py add-dependency "namespace/component_name"

在 components.espressif.com 浏览完整目录。

—
已发布组件数
—
仓库累计下载次数

当前热门

来自组件仓库的高使用量组件快照：

面向专用技术栈的框架

当产品需要的不仅是「纯固件」时，下列乐鑫框架构建在 ESP-IDF 之上，可加速常见领域：

  • ESP-BROOKESIA — 面向 AIoT 设备的人机交互开发框架
  • ESP-DSP — 针对片上音频、控制与分析的数字信号处理优化
  • ESP-WHO — 面向带摄像头 ESP32 级设备的视觉流水线模块
  • ESP-Matter — 与乐鑫芯片与认证路径对齐的 Matter 连接
  • ESP-Zigbee-SDK — 适用于 ESP32-C6、ESP32-H2 等支持 IEEE 802.15.4 芯片的 Zigbee 协议栈

社区与交流

当您的产品需要的不只是「原生」固件时，下列乐鑫框架构建在 ESP-IDF 之上，可加速常见领域的开发：

文章列表

本页为 ESP-IDF 专题简介与资源汇总；与本标签相关的博客文章列表仅在英文站点维护。请在 英文版 ESP-IDF 页面 底部浏览全部文章。

Related