Arduino ESP32 核心安装完全指南Arduino IDE、Windows、Linux 与 macOS 四种方式详解【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读本文以 docs/en/installing.rst 为骨架完整讲解在 Arduino 开发环境中安装 ESP32 系列 SoC 支持的四种途径Arduino IDE Boards Manager 一键安装、Windows 手动安装、LinuxDebian/Ubuntu、Fedora、openSUSE命令行安装以及 macOS 安装。读完本文你将掌握稳定版/开发版索引链接的选用、中国区 Jihulab 镜像的配置、get.exe/get.py工具链下载器的底层原理以及安装后的板卡选择、串口烧录与常见故障排查方法可在任意主流操作系统上从零搭建可用的 Arduino-ESP32 开发环境。当前仓库为 Arduino-ESP32 核心 v3.xcores/esp32/esp_arduino_version.h 中ESP_ARDUINO_VERSION_MAJOR/MINOR/PATCH分别为 3/3/11package.json 中的framework-arduinoespressif32版本同为 3.3.11覆盖 ESP32、ESP32-C3/C5/C6/H2、ESP32-S2/S3、ESP32-P4 等芯片详见 docs/en/getting_started.rst 中的 Supported SoC 表格。一、安装前须知三种安装路线与网络镜像Arduino-ESP32 支持包的安装并不只有一种方式官方建议优先使用你惯用的 IDE 完成安装同时按操作系统提供了多种备选方案。在动手之前需要先明确两件事安装方式选择本文覆盖的路线包括Arduino IDE Boards Manager最推荐跨平台、可自动管理版本Windows Git GUI 手动克隆 get.exe工具链安装Linux / macOS 终端命令手动克隆 get.py工具链安装进阶用户还可参考 docs/en/esp-idf_component.rst 将 Arduino 作为 ESP-IDF 组件使用或用 docs/en/lib_builder.rst 介绍的 Lib Builder 自行重编译静态库。网络与镜像官方原文档特别提示——中国区用户在访问 GitHub 及官方下载链接时可能遇到连接与下载速度问题因此提供了 Jihulab 镜像作为仓库源https://jihulab.com/esp-mirror/espressif/arduino-esp32.git该镜像不仅用于git clone也用于 Boards Manager 索引文件见下一节建议中国区用户全程使用-cn后缀的镜像版本。二、方式一通过 Arduino IDE Boards Manager 安装推荐这是将 Arduino-ESP32 支持直接装入 Arduino IDE 的标准方式支持 Windows、macOS、Linux 三个平台。Arduino IDE 从 1.6.4 版本开始允许通过 Boards Manager开发板管理器安装第三方平台包。2.1 准备索引链接需要将以下索引 URL 填入 Arduino IDE 的“附加开发板管理器网址”。稳定版与开发版的区别在于**稳定版Stable**面向常规开发与生产**开发版Development**包含最新提交的特性但可能不稳定。各 SoC 处于稳定还是开发状态可对照 docs/en/getting_started.rst 中的支持矩阵确认。官方源版本索引 URL稳定版https://espressif.github.io/arduino-esp32/package_esp32_index.json开发版https://espressif.github.io/arduino-esp32/package_esp32_dev_index.json中国区 Jihulab 镜像源版本索引 URL稳定版https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json开发版https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_dev_index_cn.json2.2 操作步骤从 arduino.cc 官网安装当前上游 Arduino IDE1.8 或更高版本均可。启动 Arduino打开文件 → 首选项Preferences窗口在附加开发板管理器网址Additional Board Manager URLs字段中填入上述任一索引链接。可以添加多个 URL用英文逗号分隔例如同时填入稳定版与开发版或官方源与镜像源通过工具 → 开发板 → 开发板管理器Tools → Board → Boards Manager打开管理器搜索并安装esp32平台。安装完成后务必在工具 → 开发板Tools → Board菜单中选择你的 ESP32 板卡型号中国区特别说明中国区用户必须选择带-cn后缀的软件包版本并手动执行更新。官方原文档明确指出该地区不支持自动更新——自动更新机制默认指向不带-cn后缀的标准包会导致下载失败。重启 Arduino IDE 完成安装。2.3 安装后的验证安装完成后esp32平台会被放置在你的 Sketchbook 目录下的hardware/espressif/esp32路径中。可以打开工具 → 开发板检查是否出现 ESP32 Dev Board、ESP32-C3/C5/C6/H2、ESP32-S2/S3、ESP32-P4 Dev Board 以及 Arduino Nano ESP32 等条目——这些开发板条目正是 package/package_esp32_index.template.json 中boards数组所声明的板卡列表该模板文件是 Boards Manager 索引package_esp32_index.json的生成源头也是get.py读取工具链清单的依据。三、方式二Windows 手动安装Git GUI get.exe不依赖 Arduino IDE 的 Boards Manager 时Windows 用户可以通过 Git 手动克隆仓库并运行工具链安装程序。警告官方原文档明确声明Arduino ESP32 corev2.x.x 无法在 Windows 8.x x8632 位、Windows 7 及更早版本上运行Windows 32 位系统已不再被该工具链支持。Arduino ESP32v1.0.6 仍可在 WIN32 上运行如果你仍在使用 Windows 7建议安装 Python 3.8.x这是 Windows 7 支持的最新版本。Step 1克隆仓库下载并安装最新 Arduino IDE 的 Windows Installer 版本来自 arduino.cc 官网。从 git-scm.com 下载并安装 Git。启动Git GUI执行以下操作选择Clone Existing Repository克隆已有仓库Source Location源地址https://github.com/espressif/arduino-esp32.git中国区可换成前文的 Jihulab 镜像地址Target Directory目标目录[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32点击Clone开始克隆。其中[ARDUINO_SKETCHBOOK_DIR]是你的Sketchbook 目录通常为C:/Users/[用户名]/Documents/Arduino该路径显示在 Arduino 首选项的 Sketchbook location 中。Step 2初始化子模块克隆完成后打开一个Git Bash会话切换到[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32目录并执行git submodule update --init --recursive这一步至关重要——Arduino-ESP32 仓库通过 git 子模块引入底层依赖包括预编译的 Arduino 库、编译器、烧录工具等缺少子模块将导致编译与烧录失败。Step 3运行 get.exe 安装工具链打开[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools目录双击运行get.exe。该程序会自动下载并解压当前平台所需的全部工具链到本地。仓库中同时保留了 tools/get.exe预编译 Windows 可执行文件与 tools/get.py跨平台 Python 源码两者的行为完全一致。Step 4检查安装结果当get.exe运行结束后tools目录下应出现各工具链目录——esp32-arduino-libs、xtensa-esp-elf、xtensa-esp-elf-gdb、riscv32-esp-elf、riscv32-esp-elf-gdb、esptool等。这些路径与 platform.txt 中的声明一一对应例如tools.esp32-arduino-libs.path{runtime.platform.path}/tools/esp32-arduino-libs tools.xtensa-esp-elf-gcc.path{runtime.platform.path}/tools/xtensa-esp-elf tools.riscv32-esp-elf-gcc.path{runtime.platform.path}/tools/riscv32-esp-elf tools.esptool_py.path{runtime.platform.path}/tools/esptoolplatform.txt是 Arduino 平台的核心构建配方文件编译时的compiler.path、SDK 库路径compiler.sdk.path、烧录命令esptool等均指向这些由get.exe下载的工具目录。目录缺失或路径不符时编译会直接报错这是手动安装最常见的问题点。Step 5连接开发板并烧录将 ESP32 开发板插入 USB 口等待驱动自动安装如有缺失请手动安装对应驱动。启动 Arduino IDE。在工具 → 开发板菜单中选择你的板卡型号。选择开发板所连接的COM 端口。编译并上传上传时可能需要按住开发板上的 BOOT 按键如何更新到最新代码手动安装的仓库可以使用 Git 轻松更新启动Git GUI在Open Recent Repository中能看到之前克隆的仓库点击打开在Remote远程菜单中选择Fetch from → origin等待 Git 拉取远程变更关闭 Git GUI重新打开[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools再次双击get.exe——它会根据最新的工具清单重新下载/校验工具链确保与最新代码匹配。注意git pull只会更新代码文件工具链的增删改必须通过重新运行get.exe或get.py来同步。四、方式三Linux 手动安装Linux 用户通过终端即可完成全部安装。不同发行版的主要差异在于软件包管理器与 Python 包名。4.1 Debian / Ubuntu从 arduino.cc 官网安装最新 Arduino IDE。打开终端逐行执行或整体复制粘贴后回车sudo usermod -a -G dialout $USER \ sudo apt-get install git \ wget https://bootstrap.pypa.io/get-pip.py \ sudo python3 get-pip.py \ sudo pip3 install pyserial \ mkdir -p ~/Arduino/hardware/espressif \ cd ~/Arduino/hardware/espressif \ git clone https://github.com/espressif/arduino-esp32.git esp32 \ cd esp32/tools \ python3 get.py重启 Arduino IDE。命令要点说明usermod -a -G dialout $USER将当前用户加入dialout组否则普通用户无法访问串口重新登录后生效pyserial是 esptool 烧录所依赖的 Python 串口库~/Arduino/hardware/espressif是 Sketchbook 目录~/Arduino下的标准硬件路径最终仓库被克隆为esp32子目录。如果 Arduino 安装在其他位置而非~/Arduino从mkdir -p ~/Arduino/hardware这一步开始按下述方式调整cd ~/Arduino/hardware mkdir -p espressif \ cd espressif \ git clone https://github.com/espressif/arduino-esp32.git esp32 \ cd esp32/tools \ python3 get.py4.2 Fedora从 arduino.cc 官网安装最新 Arduino IDE。注意sudo dnf -y install arduino这条命令大概率会安装到较旧的发行版本不推荐作为安装 Arduino IDE 的方式。打开终端执行sudo usermod -a -G dialout $USER \ sudo dnf install git python3-pip python3-pyserial \ mkdir -p ~/Arduino/hardware/espressif \ cd ~/Arduino/hardware/espressif \ git clone https://github.com/espressif/arduino-esp32.git esp32 \ cd esp32/tools \ python get.py重启 Arduino IDE。4.3 openSUSE从 arduino.cc 官网安装最新 Arduino IDE。打开终端执行脚本会先检测系统默认 Python 是否为 2.7再选择对应的包名sudo usermod -a -G dialout $USER \ if [ python --version 21 | grep 2.7 | wc -l 1 ]; then \ sudo zypper install git python-pip python-pyserial; \ else \ sudo zypper install git python3-pip python3-pyserial; \ fi \ mkdir -p ~/Arduino/hardware/espressif \ cd ~/Arduino/hardware/espressif \ git clone https://github.com/espressif/arduino-esp32.git esp32 \ cd esp32/tools \ python get.py重启 Arduino IDE。五、方式四macOS 手动安装macOS 安装流程与 Linux 类似但 Sketchbook 默认目录为~/Documents/Arduino。从 arduino.cc 官网安装最新 Arduino IDE。打开终端执行mkdir -p ~/Documents/Arduino/hardware/espressif \ cd ~/Documents/Arduino/hardware/espressif \ git clone https://github.com/espressif/arduino-esp32.git esp32 \ cd esp32/tools \ python get.py其中~/Documents/Arduino即 IDE 中Arduino → Preferences → Sketchbook location显示的路径请根据实际情况调整。重启 Arduino IDE。macOS 常见错误与处理错误现象处理方法xcrun: error: invalid active developer path ... missing xcrun尚未安装命令行开发工具执行xcode-select --install后重试运行python get.py报IOError: [Errno socket error] [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol versionPython 版本过旧改用python3代替python运行python get.py报urllib.error.URLError: urlopen error SSL: CERTIFICATE_VERIFY_FAILEDPython 证书未安装打开Macintosh HD Applications Python3.x目录运行其中的Install Certificates.command和Update Shell Profile.command两个脚本六、深入原理get.exe / get.py 究竟做了什么手动安装路径中反复出现的get.exeWindows与get.pyLinux/macOS是整个工具链安装的核心理解它的行为有助于排查大量安装问题。以 tools/get.py 为例其工作流程如下识别平台identify_platform()根据操作系统与 CPU 位数映射到 Arduino 平台名例如x86_64-pc-linux-gnu、aarch64-linux-gnuLinux ARM、x86_64-mingw32Windows 64 位、arm64-apple-darwinApple Silicon等。在 Apple ARM 与 64 位 Windows 上脚本还会自动回退到 x86 或 32 位版本的工具。读取工具清单load_tools_list()解析 package/package_esp32_index.template.json 中的tools数组从中筛选出适配当前平台的每个工具esp32-arduino-libs、xtensa-esp-elf-gcc/gdb、riscv32-esp-elf-gcc/gdb、esptool等。下载与校验get_tool()将压缩包下载到tools/dist/并用 SHA-256 校验和sha256sum验证完整性校验失败会标记为损坏并自动重试一次-v可开启详细输出。安全解压解压前通过is_safe_archive_path()检查压缩包条目拒绝绝对路径与目录穿越..攻击再调用safe_tar_extract/safe_zip_extract解压到tools/目录。版本去重与重命名unpack()会剔除目录名中的版本号如xtensa-esp-elf-gcc-...重命名为xtensa-esp-elf并把当前校验和写入.package_checksum文件下次运行时is_latest_version()通过比对校验和判断是否已是最新版本从而跳过重复下载解压。参数化运行脚本支持的命令行参数包括-v, --verbose 打印详细输出 -d, --force-download 强制重新下载工具 -e, --force-extract 强制重新解压工具 -f, --force-all 强制下载并解压等价于 -d -e -c, --clean-unused 清理 dist/ 中当前工具清单不再需要的旧压缩包当遇到“工具损坏、重复下载无果”的情况get.py会输出错误并以退出码 1 终止——此时可先删除tools/dist/下的损坏压缩包再配合-f参数强制重装。这一设计保证了三件事工具链与代码版本严格对应工具清单随 package/package_esp32_index.template.json 一起版本化、重复安装高效校验和跳过、以及下载过程安全SHA-256 校验 防目录穿越。七、安装后的检查清单与进阶路线安装完成后建议按以下清单确认环境可用板卡是否可见工具 → 开发板菜单中出现 ESP32 系列条目含各 SoC 的 Dev Board 及第三方开发板如 variants 目录下的数百种板卡定义例如 variants/esp32、variants/esp32s3 等。工具链是否齐全手动安装时确认tools/下存在esp32-arduino-libs、xtensa-esp-elf、riscv32-esp-elf、esptool等目录。版本号核对打开 cores/esp32/esp_arduino_version.h 可查看ESP_ARDUINO_VERSION_STR定义的当前核心版本字符串编译输出与串口监视器也会打印该版本。串口权限Linux 下确认用户已加入dialout组并重新登录macOS 下确认开发板驱动正常。首次编译烧录打开任意示例如libraries/下的 Blink 类示例选择板卡与端口后编译上传观察串口输出。若在安装或使用中遇到问题可参考 docs/en/troubleshooting.rst其中同样给出了中国区 Jihulab 镜像的仓库源与索引链接若需将 Arduino 框架嵌入 ESP-IDF 工程或按需重编译核心库可进一步阅读 docs/en/esp-idf_component.rst 与 docs/en/lib_builder.rst。总结Boards Manager 方式适合绝大多数用户注意中国区使用-cn镜像并手动更新Windows 手动安装记住“克隆 → 子模块 →get.exe”三步与 32 位系统限制Linux/macOS 手动安装的核心是python3 get.py工具链下载器其平台识别、SHA-256 校验与校验和去重机制保证了工具链与仓库代码的严格同步。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考