ESP32 LittleFS文件系统实操:插件上传与读写追加

2026-11-13 13:18:49 94阅读 所属项目:ESP32 开发板

LittleFS 是什么,和 SPIFFS 什么关系

给 ESP32 存数据,除了上一期聊过的 Preferences 键值对,还有一条路是当文件系统用。LittleFS 是专门为微控制器设计的轻量级文件系统,可以像操作电脑上的文件系统那样去读、写、关闭和删除文件,只是更简单、限制更多。网页服务器的 HTML/CSS、配置文件、小型数据日志、图标素材,都可以直接躺进 ESP32 的 flash 里。

很多老教程用的是 SPIFFS,它到现在也完全可用,但社区里越来越多的库正在迁往 LittleFS。差异主要有三点:LittleFS 带磨损均衡算法,写入会均匀摊到 flash 各处,寿命更长;它用目录索引结构,挂载和文件访问更快;另外它在断电和系统崩溃时数据损坏风险更小,而且目前仍在活跃开发。给新项目选型,LittleFS 是更稳的那个。

上传文件靠的是一个 Arduino IDE 1.8.X 的插件,它同时支持 LittleFS、SPIFFS 和 FatFS 三种镜像,装一个就够了。用 Arduino IDE 2 的同学要走另一条路,装的是 LittleFS Uploader 插件,本文不展开。

ESP32 LittleFS 文件系统教程封面

安装文件系统上传插件

先去插件的 GitHub releases 页面,下载最新版的 esp32fs.zip,仓库 Assets 里就能看到这个压缩包。

GitHub releases 页面下载 esp32fs.zip

Windows 的安装步骤如下:

  1. 解压 esp32fs.zip,得到 esp32fs 文件夹,里面有一个 esp32fs.jar;
  2. 打开 Arduino IDE,进 File > Preferences,查看 Sketchbook 位置,比如 C:\Users\你的用户名\Documents\Arduino;
  3. 关掉 Arduino IDE,在 Sketchbook 目录下建一个 tools 文件夹(没有的话);
  4. 在 tools 里再建 ESP32FS 文件夹,在 ESP32FS 里再建 tool 文件夹;
  5. 把 esp32fs.jar 拷进 tool 文件夹。如果之前装过旧版插件,把旧的 jar 删掉换新的。

解压后得到 esp32fs.jar 文件

最终目录结构是固定的:/Arduino/tools/ESP32FS/tool/esp32fs.jar,一层都不能错位。Mac 也一样:在 /Documents/Arduino/ 下建 tools,再逐层建 ESP32FS 和 tool,把 jar 放进去,重启 IDE。

验证方法:打开 Arduino IDE,选好 ESP32 开发板,看 Tools 菜单里有没有出现 ESP32 Sketch Data Upload 这一栏。

tools/ESP32FS/tool 目录下放入 esp32fs.jar

建 data 文件夹,把文件灌进去

插件的上传逻辑是把草稿文件夹里 data 目录下的所有文件打包成镜像,整体写进 flash。操作顺序:

  1. 新建一个 Arduino 草稿并保存,空的也行;
  2. 走 Sketch > Show Sketch Folder 打开草稿所在目录;
  3. 在草稿目录里新建一个 data 文件夹;
  4. 把想存进 ESP32 的文件放进 data,比如建一个 test_example.txt,随便写几行内容;
  5. 回 Arduino IDE,走 Tools > ESP32 Sketch Data Upload;
  6. 弹窗里选 LittleFS,点 OK。

两个高频翻车点:上传前必须把串口监视器关掉,否则串口占用会直接报错;部分板子要在上传时按住板载 BOOT 键约两秒。看到 LittleFS Image Uploaded 字样就是成功了。注意上传是整盘覆盖,之前存在文件系统里的东西会被清掉,别指望增量。

Tools 菜单里的 ESP32 Sketch Data Upload 选项

上传后读文件验证

烧下面这段代码进 ESP32,打开 115200 波特率的串口监视器,按一下板上的 ENABLE/RST 键,txt 文件的内容就会打出来。

/*********
  Rui Santos & Sara Santos - Random Nerd Tutorials
  Complete project details at https://RandomNerdTutorials.com/esp32-littlefs-arduino-ide/
*********/

#include "LittleFS.h"

void setup() {
  Serial.begin(115200);

  if(!LittleFS.begin()){
    Serial.println("An Error has occurred while mounting SPIFFS");
    return;
  }

  File file = LittleFS.open("/test_example.txt");
  if(!file){
    Serial.println("Failed to open file for reading");
    return;
  }

  Serial.println("File Content:");
  while(file.available()){
    Serial.write(file.read());
  }
  file.close();
}

void loop() {

}

几个细节值得盯:头文件是 #include "LittleFS.h",ESP32 核心自带,不用额外装库;LittleFS.begin() 挂载失败直接 return,路径要用斜杠开头的绝对路径 /test_example.txt;读的时候用 file.available() 配合 file.read() 逐字节吐到串口,读完记得 file.close()。

写文件与追加怎么玩

读通了之后,写入是同一套 API 的镜像操作。写文件用 LittleFS.open("/xxx.txt", "w"),拿到 File 对象后调 file.print() 或 file.println() 写入内容,再 close 落盘。追加模式是第二个参数换成 "a",新内容会接在文件尾部,适合做运行日志。中途想改游标位置,还有 file.seek() 可用。这些接口和 SD 库的 File 类几乎同构,写过 SD 卡日志的可以直接平移经验。

不过要提醒一句:插件上传的 data 文件夹里的文件,和运行时程序自己写出来的文件,共用同一块分区。前面说过上传是整盘覆盖,所以调试期反复上传镜像会把程序运行时写的日志抹掉,两边别混着用,日志文件名和数据文件名分开管理。

踩坑提示

分区大小取决于烧录时选的分区表方案,默认给文件系统的空间不大,塞大图或音频前先在 Tools 菜单里确认分区方案,别传到一半空间爆了。

总结一下链路:装 esp32fs 插件 → 草稿目录建 data 放文件 → Tools 菜单选 LittleFS 上传 → 代码里 LittleFS.begin() 挂载 → open/print/read/close 读写追加。装完这个插件,ESP32 就有了最朴素的"硬盘",后面做网页服务器存 HTML 文件、做配置存档,都是在这块地基上盖楼。


作者:开源复现员
链接:https://www.aiddithome.com/p/4a45083cbd6ca.html
本作版权归作者所有,未经允许请勿转载。若存在违规行为,您可以点击 “举报”。


登录 后发表评论
4条评论
只看不说话
1楼 · 2026-11-13 13:19:14

提醒一句串口监视器一定先关,不然报串口占用错误,新手容易卡在这。

线比代码多
2楼 · 2026-11-13 13:19:14

追加写日志用 open("a") 挺顺的,跟 SD 库的 File 接口几乎一样,从 SD 卡项目平移过来毫无成本。

老张装机
3楼 · 2026-11-13 13:19:13

LittleFS 相比 SPIFFS 最实用的就是断电保护这块,之前用 SPIFFS 存传感器日志,遇到过几次断电后整个分区挂载失败只能 begin(true) 格式化重来的情况,数据全丢。换 LittleFS 之后日志一致性明显好一些,写入也更快,新项目直接上 LittleFS 没毛病。

胶佬憨憨
4楼 · 2026-11-13 13:19:13

插件那个目录结构一层都不能放错,我第一次就是直接把 jar 扔 tools 下了,重启 IDE 死活不出菜单,后来逐层建 ESP32FS/tool 才好。