ESP32 Linux 开发环境

ESP32 作为 Espressif（乐鑫科技）推出的高性能物联网芯片，凭借其强大的处理能力、丰富的外设接口和完善的开源生态，成为物联网开发的热门选择。搭建稳定的开发环境是 ESP32 开发的第一步，本文将详细介绍在 Ubuntu 20.04 系统上基于 ESP-IDF（Espressif IoT Development Framework）搭建 ESP32 开发环境的完整流程，包括前置工具安装、码云镜像配置、代码拉取、环境初始化及 HelloWorld 工程编译，帮助开发者快速上手。

一、环境准备与前置说明

在开始搭建前，我们需要明确开发环境的核心组件：

• 操作系统：Ubuntu 20.04 LTS（64 位，推荐桌面版，命令行版需额外配置图形化依赖）
• 开发框架：ESP-IDF
• 核心工具：Git（代码管理）、Python（ESP-IDF 依赖）、CMake（构建工具）、交叉编译链（针对 ESP32 的编译器）

由于 ESP-IDF 及其子模块主要托管在 GitHub，国内访问可能存在速度慢或连接不稳定的问题，因此本文采用码云（Gitee）镜像进行加速，通过 Espressif 官方提供的esp-gitee-tools工具实现仓库镜像切换，提升代码拉取效率。

二、前置工具安装

ESP-IDF 的编译和运行依赖一系列系统工具和库，需先通过 Ubuntu 的包管理工具apt安装。打开终端（Ctrl+Alt+T），执行以下命令：

2.1 系统更新

首先更新系统包列表，确保安装的工具为最新版本：

sudo apt update && sudo apt upgrade -y

2.2 安装基础依赖工具

执行以下命令安装开发必需的工具，包括 Git、Python、CMake、编译工具链等：

sudo apt install -y git wget flex bison gperf python3 python3-pip python3-setuptools \
python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

各工具作用说明：

• git：用于拉取 ESP-IDF 及相关子模块代码
• python3及相关包：ESP-IDF 的脚本和工具链依赖 Python 3.8+（Ubuntu 20.04 默认 Python 3.8，满足要求）
• cmake和ninja-build：构建系统工具，用于生成编译脚本
• flex、bison：语法分析工具，ESP-IDF 内部部分组件编译依赖
• ccache：编译缓存工具，加速重复编译
• dfu-util和libusb-1.0-0：用于 ESP32 的 USB 固件烧录

三、拉取 esp-gitee-tools 工具

为解决国内访问 GitHub 的网络问题，Espressif 在码云提供了官方镜像仓库，并开发了esp-gitee-tools工具用于快速切换仓库镜像。

3.1 克隆 esp-gitee-tools 仓库

执行以下命令从码云克隆esp-gitee-tools：

git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git

克隆完成后，进入工具目录：

cd esp-gitee-tools

3.2 jihu-mirror.sh 脚本使用说明

jihu-mirror.sh是esp-gitee-tools中的核心脚本，用于切换 ESP-IDF 及子模块的仓库地址（从 GitHub 切换到码云镜像，或恢复默认）。其主要功能通过两个命令实现：

1. 设置码云镜像（set）

./jihu-mirror.sh set

作用：将当前仓库（及子模块）的远程地址从 GitHub（https://github.com/espressif/...）替换为码云镜像（https://gitee.com/EspressifSystems/...），适用于国内网络环境，加速代码拉取和更新。

2. 恢复 GitHub 地址（unset）

./jihu-mirror.sh unset

作用：将仓库远程地址恢复为原始 GitHub 地址，适用于需要提交代码到 GitHub 或依赖 GitHub 特定功能的场景。

使用注意事项：

• 脚本需在 ESP-IDF 仓库目录（或其子模块目录）中执行，否则无法识别仓库结构
• 执行前需确保当前目录已初始化 Git 仓库（即存在.git文件夹）
• 切换镜像后，需重新执行git submodule update更新子模块，确保子模块地址同步切换

四、拉取 ESP-IDF 代码

ESP-IDF 是 ESP32 开发的核心框架，包含芯片驱动、操作系统（FreeRTOS）、网络协议栈等关键组件。由于其包含多个子模块（托管在 GitHub），需通过git clone --recursive拉取，结合esp-gitee-tools加速。

4.1 克隆 ESP-IDF 仓库

回到用户主目录（或自定义开发目录），执行以下命令克隆 ESP-IDF：

注意：若使用码云地址需要 按照4.2处理子模块地址，建议直接使用github地址拉取

cd ~  # 回到主目录，可替换为自己的开发目录
#github地址![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/bdd93b13683048fb950e517c43db9944.png#pic_center)git clone --recursive https://github.com/espressif/esp-idf.git
#码云地址
git clone https://gitee.com/EspressifSystems/esp-idf.git

说明：--recursive参数用于递归拉取所有子模块，若省略此参数，后续需手动更新子模块。

拉取完代码后，可以选择合适的版本分支，本文选择最新 remotes/origin/release/v5.5分支

4.2 处理子模块地址

ESP-IDF 的子模块在.gitmodules文件中采用相对路径配置（例如url = ../../espressif/esp32c3-hal.git），默认指向 GitHub。若从 GitHub 直接克隆 ESP-IDF，子模块会自动关联 GitHub 地址；但如果是从码云克隆（或国内网络拉取子模块失败），则需要手动将子模块地址切换为绝对路径的码云镜像。

步骤 1：进入 ESP-IDF 目录

cd esp-idf

步骤 2：运行子模块地址转换脚本

执行 ESP-IDF 内置的set-submodules-to-github.sh脚本，将子模块的相对路径转换为绝对路径（默认 GitHub，后续可通过jihu-mirror.sh切换为码云）：

./tools/set-submodules-to-github.sh

脚本作用：遍历.gitmodules文件，将所有子模块的url从相对路径（如../../xxx.git）替换为绝对路径（如https://github.com/espressif/xxx.git），确保子模块地址可访问。

步骤 3：切换子模块为码云镜像

为加速子模块拉取，使用之前下载的esp-gitee-tools中的jihu-mirror.sh脚本切换子模块地址：

# 假设esp-gitee-tools在用户主目录（根据实际路径修改）
~/esp-gitee-tools/jihu-mirror.sh set

步骤 4：更新子模块

执行以下命令更新所有子模块（若之前git clone --recursive未成功拉取子模块，此步骤会补全）：

git submodule update --init --recursive

注意：若更新过程中出现网络错误（如 “failed to connect to github.com”），可重复执行git submodule update --init --recursive，或重新运行jihu-mirror.sh set确认镜像已切换。

五、安装 ESP-IDF 工具链

ESP-IDF 需要特定的交叉编译工具链（针对 Xtensa 架构）、OpenOCD（调试工具）等组件，这些工具可通过 ESP-IDF 内置的install.sh脚本自动安装。

5.1 执行安装脚本

在 ESP-IDF 目录中，运行install.sh：

./install.sh

脚本执行过程说明：

• 脚本会检查当前系统环境，确认依赖是否满足
• 自动下载适配当前系统的工具链（如xtensa-esp32-elf）、OpenOCD、Python 虚拟环境等
• 工具默认安装在~/.espressif目录下（可通过--prefix参数指定自定义路径）

可能遇到的问题及解决：

• 权限不足：若提示 “Permission denied”，无需使用sudo（可能导致权限混乱），检查当前用户对~/.espressif目录是否有写入权限（通常默认有）
• 网络超时：工具链下载依赖 GitHub 或 Espressif 官方服务器，国内用户可通过配置代理加速，或多次重试

六、配置环境变量

安装完成后，需将 ESP-IDF 的工具链路径、框架路径等添加到系统环境变量中，以便终端识别idf.py等命令。

6.1 临时生效环境变量

在 ESP-IDF 目录中，执行export.sh脚本：

. ./export.sh  # 注意开头的点和空格，等效于source ./export.sh

执行成功后，终端会显示环境变量配置信息，例如：

Added ESP-IDF tools to PATH: /home/user/.espressif/tools/...
ESP-IDF is now in PATH: /home/user/esp-idf

6.2 永久生效环境变量

上述方法仅在当前终端生效，关闭终端后需重新执行。若要永久生效，可将脚本添加到 shell 配置文件（如.bashrc或.zshrc）：

对于 bash 用户：

#$PAT为export.sh脚本路径
echo "alias get_idf='. $PATH/export.sh'" >> ~/.bashrc
source ~/.bashrc  # 立即生效

执行get_idf 命令

七、编译 HelloWorld 工程验证环境

环境搭建完成后，我们通过编译 ESP-IDF 自带的helloworld示例工程验证是否配置成功。

7.1 进入 HelloWorld 工程目录

ESP-IDF 的示例工程位于examples目录下，helloworld是最基础的示例：

cd examples/get-started/hello_world/

7.2 配置目标芯片

ESP-IDF 支持多种芯片（如 ESP32、ESP32-C3、ESP32-S3 等），需指定目标芯片型号。此处以 ESP32 为例：

idf.py set-target esp32

执行后，工具会生成针对 ESP32 的配置文件（sdkconfig）。

7.3 编译工程

执行以下命令开始编译：

idf.py build

编译过程说明：

• 第一步：检查环境依赖，确认工具链和组件是否齐全

• 第二步：运行 CMake 生成编译脚本（基于 Ninja）

• 第三步：编译源代码、链接库文件，生成固件（.bin文件）

• 成功后，终端会显示编译时间和固件信息，例如：
  

7.4 查看编译产物

编译成功后，在工程目录的build文件夹中会生成以下关键文件：

• hello_world.bin：主程序固件
• bootloader/bootloader.bin：引导程序
• partition_table/partition-table.bin：分区表
• elf文件：用于调试的可执行文件