Arduino IDE 配好 ESP32：从安装开发板包到编译第一份代码

这一篇先得到第一份编译成功的日志

这次先让电脑把官方 GetChipID 示例编译成 ESP32 固件。完成后，你会在输出区看到程序和动态内存的占用统计，并保存一份能追溯版本与目标的日志。还没买开发板也可以跟做；上传和串口读数接着在下一篇完成。

第一次安装，按下面的 IDE 路线依次做：安装编辑器 → 安装 ESP32 开发板包 → 设置 N8R8 → 打开示例并验证。命令行复验放在后面的独立小节，需要时再看，不用同时安装两套工具。

IDE 提供编辑、编译和上传界面；Espressif 的 esp32 开发板包提供芯片工具链与目标配置；库用于额外器件或功能。GetChipID 使用开发板包自带的库，不接 LED、不装传感器库。本篇固定 IDE 2.3.8、core 3.3.12；可选 CLI 路线固定 1.5.1。

点击查看大图 ↗

参考：[1] Arduino IDE 2.3.8 正式发布[2] Arduino CLI 1.5.1 正式发布[3] Arduino-ESP32 3.3.12：安装文档与稳定版索引[6] Arduino-ESP32 3.3.12：官方 GetChipID 完整示例

第 1 步：装好 IDE，打开一个空白程序

从下方正式发布页选择与你的系统和 CPU 架构匹配的 IDE 2.3.8 安装包。macOS 要区分 Apple Silicon 与 Intel；Windows 和 Linux 选择发布页支持的对应构建。首次打开后，先确认编辑窗口能正常使用。

这一步只安装编辑器，暂时不用寻找串口或连接开发板。也先不要照另一篇旧教程手动克隆 core；后面统一通过开发板管理器安装，避免同一环境出现两份 ESP32 支持。

1. 打开 Arduino IDE 2.3.8 发布页，下载并安装匹配系统的版本。
2. 启动 IDE，新建一个空白 sketch，再保存到自己能找到的文件夹。
3. 查看 IDE 的版本信息，确认显示 2.3.8，再进入下一步。

做到这里，你应该看到

IDE 能打开、编辑并保存程序，版本为 2.3.8。没有串口也可以继续。

如果卡住了

安装包无法启动时先核对操作系统和 CPU 架构；记录系统报错，不在这一步安装串口驱动。

参考：[1] Arduino IDE 2.3.8 正式发布

第 2 步：让 IDE 认识 ESP32

IDE 刚装好时还没有本篇需要的 ESP32 工具链。把下方稳定版索引加入首选项，再通过开发板管理器安装指定版本。搜索结果要同时核对包名、作者和版本。

1. 打开 IDE 首选项，找到“附加开发板管理器网址”（Additional Boards Manager URLs）。
2. 加入下方网址并保存；如果已有其他网址，保留原条目，另加这一条。
3. 打开开发板管理器（Boards Manager），搜索 esp32，找到作者为 Espressif Systems 的包。
4. 选择 3.3.12，点击安装，等待完成后再次检查已安装版本。

https://espressif.github.io/arduino-esp32/package_esp32_index.json

做到这里，你应该看到

开发板管理器显示 Espressif Systems 的 esp32 3.3.12 已安装。

如果卡住了

下载超时就保留失败的包名与 URL，恢复网络后重试同一版本。官方中国镜像使用 -cn 后缀，本篇构建采用上述稳定版索引；不要把两种安装产物混在一份复现记录里。

参考：[3] Arduino-ESP32 3.3.12：安装文档与稳定版索引

第 3 步：按 N8R8 设置开发板

在 Tools → Board → esp32 中选择 ESP32S3 Dev Module，再逐项核对下表。这里的 N8R8 表示 8 MB Flash 和 8 MB OPI PSRAM；只选中 S3，还没有完成这块板的配置。

本系列首次上传使用板载 USB-to-UART 接口，USB CDC On Boot 设为 Disabled，Serial 日志走 UART0。分区选择与 8 MB Flash 对应的 8M with spiffs；PSRAM 用 OPI，不代表 Flash 也改成 OPI。其他菜单保留默认。

点击查看大图 ↗

做到这里，你应该看到

板目标和六项菜单值与表一致；保存自己的菜单记录，再打开示例。

如果卡住了

没有 ESP32S3 Dev Module 选项时，返回上一步核对包作者和安装状态。不要以名字相似的其他板目标代替。

参考：[4] Arduino-ESP32 3.3.12：Tools Menu[5] Arduino-ESP32 3.3.12：boards.txt 的 esp32s3 菜单[7] 乐鑫 DevKitC-1 v1.1 用户指南：固定文档提交 927ed7e

第 4 步：打开示例，按验证并检查输出

先下载并解压本页示例包。在解压目录内打开 GetChipID 文件夹中的 GetChipID.ino；文件夹与程序文件同名，保持这层目录。它是 core 3.3.12 自带示例的原样副本，上游许可也在包内。

点击 Verify（验证/对勾），等待编译结束，展开输出区并保存日志。判断成功要看最终结果：出现存储占用统计，同时没有后续编译失败。第一次下载工具或编译可能需要等待，不能把仍在执行当成通过。

下表摘自本站留存的 CLI 构建日志，退出码为 0；它用来说明成功统计长什么样。你电脑上的字节数可能因配置不同而变化，实际记录自己的结果。

1. 下载示例 ZIP，解压后打开 GetChipID/GetChipID.ino。
2. 复核上一节的板目标与菜单设置，点击 Verify。
3. 等待结束，检查完整输出，保存版本、目标配置与最终日志。

做到这里，你应该看到

原样 GetChipID 编译完成，日志没有最终错误，并保留版本与配置。到这里已经完成本篇的 IDE 路线。

如果卡住了

Verify 失败先看输出中的第一处具体错误，再用末尾排错表定位。编译不需要串口，不用反复插拔 USB 来处理编译错误。

参考：[5] Arduino-ESP32 3.3.12：boards.txt 的 esp32s3 菜单[6] Arduino-ESP32 3.3.12：官方 GetChipID 完整示例

可选：用命令行重复同一份构建

已经完成 IDE 路线，可以直接继续下一篇。要保存可重复的终端命令，再使用 CLI 1.5.1。Windows 使用 PowerShell，macOS/Linux 使用终端；下方单引号命令不适用于 Windows cmd.exe。先按示例 README 安装 esp32:esp32@3.3.12，再执行下面的版本检查与编译。IDE 与 CLI 可能使用不同的数据目录，要分别确认，不能用 IDE 的安装截图证明 CLI 的版本。

下方命令从本项目仓库根目录执行。只下载 ZIP 的读者，进入解压得到的 esp32-arduino-setup 目录，把编译命令末尾的 examples/esp32/esp32-arduino-setup/GetChipID 换成 GetChipID，其他参数不变。完整 FQBN 对应上表菜单，不依赖 IDE 的临时设置。

arduino-cli version
arduino-cli core list
arduino-cli compile --fqbn 'esp32:esp32:esp32s3:FlashSize=8M,PSRAM=opi,FlashMode=qio,PartitionScheme=default_8MB,CDCOnBoot=default,USBMode=hwcdc' --warnings all --verbose examples/esp32/esp32-arduino-setup/GetChipID

做到这里，你应该看到

CLI 为 1.5.1、esp32:esp32 为 3.3.12，编译退出成功；日志、目标与源文件一同保留。

参考：[2] Arduino CLI 1.5.1 正式发布[5] Arduino-ESP32 3.3.12：boards.txt 的 esp32s3 菜单[6] Arduino-ESP32 3.3.12：官方 GetChipID 完整示例

卡在哪一步，就从对应现象恢复

先用原样 GetChipID 检查环境，再检查自己的改动。若原样能编译，改后不能编译，比较两份代码；若原样也失败，记录第一处错误和工具路径，再按下表处理。

本篇完成后，固件还在电脑上。下一篇才把它写入开发板并读日志：示例每约 3 秒输出芯片型号、核心数和一个由 MAC 末尾三字节构造的整数。这个整数不是完整 MAC，也不是安全身份凭据。本站未做这套硬件的上传与串口实测，运行结果仍需按下一篇确认。

参考：[2] Arduino CLI 1.5.1 正式发布[3] Arduino-ESP32 3.3.12：安装文档与稳定版索引[4] Arduino-ESP32 3.3.12：Tools Menu[5] Arduino-ESP32 3.3.12：boards.txt 的 esp32s3 菜单[6] Arduino-ESP32 3.3.12：官方 GetChipID 完整示例