总结Linux系统安装ESP-IDF的保姆级教程。如果你正在为“Permission denied”或“idf.py not found”而头疼，这篇文章将帮你彻底解决。

一、准备工作：安装系统依赖

在开始之前，我们需要确保系统具备编译ESP-IDF所需的基础工具。打开终端，执行以下命令：

# Ubuntu/Debian 系统sudo apt-get updatesudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0# CentOS/RHEL/Fedora 系统sudo dnf install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-devel openssl-devel dfu-util libusb

💡 避坑提示：如果遇到“Package not found”错误，请检查你的系统版本，并尝试使用 yum 替代 dnf（针对旧版CentOS）。

二、获取ESP-IDF源码

我们推荐将ESP-IDF安装在用户主目录下的 esp 文件夹中，避免权限问题。

# 创建目录并进入mkdir -p ~/espcd ~/esp# 克隆ESP-IDF仓库（推荐使用国内镜像加速）git clone -b v5.4.1 --recursive https://gitee.com/EspressifSystems/esp-idf.git

⚠️ 注意：如果你使用官方GitHub源（github.com/espressif/esp-idf）且下载缓慢，可以设置环境变量使用国内镜像：

export IDF_GITHUB_ASSETS="dl.espressif.cn/github_assets"

三、安装工具链（关键步骤）

进入ESP-IDF目录，运行安装脚本。这里有一个极易踩坑的点：

❌ 错误做法：使用 sudo 运行安装脚本（会导致后续用户权限混乱）

✅ 正确做法：直接以当前用户身份运行

cd ~/esp/esp-idf./install.sh

• 参数说明：

• ./install.sh：安装所有支持的芯片工具链
• ./install.sh esp32：仅安装ESP32工具链（节省磁盘空间）
• ./install.sh esp32,esp32s2,esp32s3：安装指定芯片工具链

安装过程会下载编译器、OpenOCD等工具，请耐心等待。

四、配置环境变量（永久生效）

安装完成后，每次使用ESP-IDF前都需要设置环境变量。为了避免每次打开终端都要手动设置，我们将其写入Shell配置文件。

• Bash用户：nano ~/.bashrc

• Zsh用户：nano ~/.zshrc

alias get_idf='. $HOME/esp/esp-idf/export.sh'

source ~/.bashrc  # 或 source ~/.zshrc

🎯 工作原理：我们创建了一个名为 get_idf 的别名（alias）。以后只需要在终端输入 get_idf，即可自动加载ESP-IDF环境。

在Linux系统中，普通用户默认无法访问USB串口设备（如 /dev/ttyUSB0）。如果你在烧录时遇到“Permission denied”错误，请执行以下命令：

# 将当前用户添加到 dialout 组sudo usermod -a -G dialout $USER# 重新登录系统（或重启）使更改生效

🔍 验证方法：重新登录后，在终端输入 groups 命令，如果输出中包含 dialout，则说明配置成功。

六、验证安装

让我们通过一个简单的示例项目来测试环境是否搭建成功。

# 1. 加载环境（使用我们刚才设置的别名）get_idf# 2. 复制示例项目cp -r $IDF_PATH/examples/get-started/hello_world ~/esp/# 3. 进入项目目录并配置cd ~/esp/hello_worldidf.py set-target esp32idf.py build

如果终端最后显示 Project build complete.，恭喜你！环境搭建成功。

总结

Linux下安装ESP-IDF的核心要点就三个：

• 别用 sudo安装：避免权限错乱。

• 设置别名：将 get_idf写入 .bashrc或 .zshrc，一劳永逸。

• 加入 dialout组：解决串口访问权限。

希望这篇教程能帮你顺利开启ESP32开发之旅！如果有任何问题，欢迎在评论区留言讨论。