2. 开发环境搭建：Arduino IDE配置ESP32、安装SPIFFS上传工具、验证环境

好，咱们正式开始动手。这一章的目标很明确——把电脑变成一台能开发ESP32的工作站。我见过太多人卡在环境搭建这一步，其实说白了就是几个工具的安装和配置。别急，跟着我来，半小时内搞定。

2.1 安装Arduino IDE

先去官网下载Arduino IDE。我个人习惯用1.8.x版本，稳定，插件兼容性好。2.0版本虽然界面好看，但有些老插件还没完全适配。你选哪个？我建议新手先用1.8.19。

  • 下载地址：arduino.cc/en/software
  • 选择对应操作系统的安装包（Windows选.exe，Mac选.dmg，Linux选.tar.xz）
  • 安装时一路默认即可，路径不要带中文
小提示： 如果你用Windows，安装完成后记得把Arduino路径加到系统环境变量。这样后面用命令行工具会方便很多。

2.2 配置ESP32开发板支持

Arduino IDE默认不支持ESP32，需要手动添加开发板管理器地址。嗯，这里有个坑——国内网络访问GitHub有时很慢，我建议你提前准备好。

  1. 打开Arduino IDE，点击 文件 → 首选项
  2. 在“附加开发板管理器网址”框中粘贴以下地址：
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
  1. 点击 工具 → 开发板 → 开发板管理器
  2. 搜索“ESP32”，找到由Espressif Systems官方发布的版本
  3. 点击安装（我建议选2.0.14或以上版本）
注意： 安装过程需要下载约200MB的文件，取决于你的网络状况。我曾经在客户现场用手机热点下载，等了快40分钟……建议提前准备好网络环境。

安装完成后，在 工具 → 开发板 菜单下就能看到ESP32系列了。选一个你手头有的型号，比如“ESP32 Dev Module”。

2.3 安装SPIFFS上传工具

SPIFFS是ESP32的文件系统，专门用来存网页、图片、配置文件这类静态资源。Arduino IDE默认不带上传工具，需要单独装。

这里有两个方法，我推荐第二种：

方法 操作步骤 适用场景
方法一：手动下载插件 从GitHub下载ESP32FS插件，解压到Arduino的tools目录 离线环境、网络受限
方法二：使用ESP32 Sketch Data Upload 在Arduino IDE中通过工具菜单直接调用 日常开发、快速迭代

我个人习惯用方法二，因为集成度高。具体操作：

  1. 下载 ESP32FS 插件包（网上搜“ESP32FS arduino plugin”就能找到）
  2. 将解压后的文件夹放到Arduino安装目录下的 tools 文件夹中
  3. 重启Arduino IDE，在 工具 菜单中就会出现 ESP32 Sketch Data Upload 选项
关键点： SPIFFS上传工具依赖Java运行环境。如果你电脑没装Java，会报错“无法启动JVM”。去Oracle官网下载JRE 8以上版本安装即可。

2.4 验证环境：点亮LED + 加载网页

环境搭好了，得跑个例子验证一下。我准备了一个最简单的测试程序：点亮板载LED，同时从SPIFFS加载一个网页。

先创建一个测试项目：

// 文件：spiffs_test.ino
#include <FS.h>
#include <SPIFFS.h>
#include <WiFi.h>
#include <WebServer.h>

const char* ssid = "你的WiFi名称";
const char* password = "你的WiFi密码";

WebServer server(80);

void setup() {
  Serial.begin(115200);
  pinMode(LED_BUILTIN, OUTPUT);
  
  // 初始化SPIFFS
  if(!SPIFFS.begin(true)){
    Serial.println("SPIFFS挂载失败！");
    return;
  }
  Serial.println("SPIFFS挂载成功");
  
  // 连接WiFi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
    delay(500);
    Serial.print(".");
  }
  Serial.println("\nWiFi已连接");
  Serial.print("IP地址: ");
  Serial.println(WiFi.localIP());
  
  // 设置网页路由
  server.on("/", handleRoot);
  server.begin();
}

void loop() {
  server.handleClient();
}

void handleRoot() {
  File file = SPIFFS.open("/index.html", "r");
  if(!file){
    server.send(500, "text/plain", "文件未找到");
    return;
  }
  server.streamFile(file, "text/html");
  file.close();
}

然后在项目文件夹下创建 data 目录，里面放一个 index.html：

<!DOCTYPE html>
<html>
<head>
    <title>ESP32 SPIFFS测试</title>
</head>
<body>
    <h1>环境搭建成功！</h1>
    <p>这个页面来自ESP32的SPIFFS文件系统</p>
</body>
</html>

上传步骤：

  1. 先编译上传程序（点击右箭头）
  2. 再点击 工具 → ESP32 Sketch Data Upload
  3. 等待上传完成（串口会输出进度）
常见错误： 如果上传SPIFFS时提示“SPIFFS: No such file or directory”，说明data文件夹没放在正确位置。检查一下：项目文件夹 → data → index.html，路径不能错。

上传成功后，打开串口监视器（波特率115200），看到IP地址后，在浏览器输入那个IP。如果看到“环境搭建成功！”的页面，恭喜你——环境完全OK了。

2.5 知识体系总览

下面这张图把整个环境搭建的流程串起来了，你保存下来，以后搭建其他开发环境也能参考：

ESP32开发环境搭建流程 安装Arduino IDE 配置ESP32开发板 安装SPIFFS上传工具 编写测试程序 验证环境：点亮LED+加载网页 前置条件 • 电脑能上网 • ESP32开发板 • USB数据线 验证结果 • 板载LED闪烁 • 串口输出IP地址 • 浏览器显示网页

2.6 常见问题与避坑

环境搭建过程中，我遇到过不少问题。挑几个典型的说说：

  • 上传失败：A fatal error occurred: Failed to connect to ESP32 —— 按住开发板上的BOOT键不放，再点上传，看到“Connecting...”时松手。这是ESP32进入下载模式的标准操作。
  • SPIFFS上传后文件读不到 —— 检查data文件夹里的文件名大小写。ESP32的文件系统是大小写敏感的，index.html和Index.html是两个不同的文件。
  • WiFi连不上 —— 先确认2.4G频段。ESP32不支持5G WiFi，很多双频路由器默认开5G，你得在路由器设置里把2.4G打开。
我的经验： 每次换电脑或重装系统后，我都会用这个测试程序验证一遍环境。花5分钟确认，能省后面调试时的一小时。

好了，环境搭建到这里就完成了。你现在应该能看到浏览器里那个“环境搭建成功！”的页面。记住这个感觉——后面30章的内容，都会基于这个环境来跑。

← 上一章 📖 返回目录 下一章 →