ESP32接MicroSD卡模块:SPI读写与数据记录实操

2026-11-09 10:54:05 121阅读 所属项目:ESP32 开发板

给机器人做数据记录,绕来绕去最后都会撞上同一个问题:SPIFFS 太小、断电就丢,日志往哪放。ESP32 自带的 SPIFFS 只有几 MB,而一张 microSD 卡动辄 32GB,加上几十块钱就能买到的 SPI 接口卡模块,是最省事的外置存储方案。我把 Random Nerd Tutorials 那篇 MicroSD 教程的示例码完整拆了一遍,这篇按"接线、初始化、读写、追加日志、排错"的顺序理顺,代码全部逐字符搬运自原教程与 Arduino IDE 自带的 SD_Test 示例,新手可以放心照抄。

ESP32与MicroSD卡模块读写指南

先认识模块:6 个引脚的 SPI 卡座

市面上兼容 ESP32 的 microSD 模块不少,原教程用的是最常见的 SPI 接口款:一块小 PCB,上面一个卡座,边上一排 6 根针。它走 SPI 协议通信,除了 ESP32,同样兼容 Arduino 和 ESP8266 NodeMCU,属于"一个模块三块板通用"的类型。

引脚定义如下,这是后面接线的全部依据:

模块引脚接 ESP32
3V33.3V
CSGPIO 5
MOSIGPIO 23
CLKGPIO 18
MISOGPIO 19
GNDGND

MicroSD卡模块外观与引脚

接线与一张原理图就够

接线用 ESP32 的默认 VSPI 引脚,四根信号线加两根电源线,面包板插完大概一分钟。需要注意的只有一个点:这个模块是 3.3V 供电,不要接到 5V/ VIN 上,卡座和电平转换电路都是按 3.3V 设计的。

对照下面这张原理图插线即可,信号线顺序记成"MOSI 上 23、MISO 下 19、CLK 18、CS 5"基本不会错。

ESP32与MicroSD模块接线原理图

动手前两件小事:格式化与开发环境

第一件,把 microSD 卡格式化成 FAT32。Windows 下在资源管理器里右键 SD 卡选"格式化",文件系统选 FAT32 点开始即可;Mac 用户可以直接用 SD Memory Card Formatter 这类工具。超过 32GB 的大卡 Windows 自带工具不给格 FAT32,得借助第三方格式化工具。

第二件,Arduino IDE 里装好 ESP32 开发板支持包(Boards Manager 里搜 esp32 安装 Espressif 官方包),用 PlatformIO 也一样。这两步原教程都有专门的引导,属于一次配置长期受益的环境活。

SD 库初始化与卡信息读取

ESP32 的 Arduino 核心里有两套库:SD.h 和 SD_MMC.h。前者走 SPI 控制器,配的就是上面这种 SPI 模块;后者用 ESP32 内置的 SD/SDIO/MMC 控制器,配的是直接走 SDIO 的卡座(比如某些开发板板载卡槽)。本文全篇用 SD 库。头文件三行:

#include "FS.h"
#include "SD.h"
#include "SPI.h"

初始化在 setup 里做,挂载失败直接 return,然后读卡类型和容量:

Serial.begin(115200);
if(!SD.begin()){
  Serial.println("Card Mount Failed");
  return;
}
uint8_t cardType = SD.cardType();

if(cardType == CARD_NONE){
  Serial.println("No SD card attached");
  return;
}
Serial.print("SD Card Type: ");
if(cardType == CARD_MMC){
  Serial.println("MMC");
} else if(cardType == CARD_SD){
  Serial.println("SDSC");
} else if(cardType == CARD_SDHC){
  Serial.println("SDHC");
} else {
  Serial.println("UNKNOWN");
}

容量一行搞定,单位换算成 MB:

uint64_t cardSize = SD.cardSize() / (1024 * 1024);
Serial.printf("SD Card Size: %lluMB\n", cardSize);

写文件、追加日志、读回验证

文件操作的原型函数都在 File > Examples > SD(esp32) > SD_Test 示例里,核心逻辑不长。写文件用 FILE_WRITE 模式打开,写完必须 close,否则数据可能停留在缓冲区没落到卡上:

void writeFile(fs::FS &fs, const char * path, const char * message){
  Serial.printf("Writing file: %s\n", path);

  File file = fs.open(path, FILE_WRITE);
  if(!file){
    Serial.println("Failed to open file for writing");
    return;
  }
  if(file.print(message)){
    Serial.println("File written");
  } else {
    Serial.println("Write failed");
  }
  file.close();
}

追加日志用 FILE_APPEND 模式打开同一个文件,新内容接在末尾,这正是数据记录场景最常用的姿势:

void appendFile(fs::FS &fs, const char * path, const char * message){
  Serial.printf("Appending to file: %s\n", path);

  File file = fs.open(path, FILE_APPEND);
  if(!file){
    Serial.println("Failed to open file for appending");
    return;
  }
  if(file.print(message)){
      Serial.println("Message appended");
  } else {
    Serial.println("Append failed");
  }
  file.close();
}

读回验证就是逐字节往串口吐:

void readFile(fs::FS &fs, const char * path){
  Serial.printf("Reading file: %s\n", path);

  File file = fs.open(path);
  if(!file){
    Serial.println("Failed to open file for reading");
    return;
  }

  Serial.print("Read from file: ");
  while(file.available()){
    Serial.write(file.read());
  }
  file.close();
}

列目录、建删目录、改名、删文件在示例里也各有对应函数,主循环按这个顺序串起来跑一遍,等于把所有文件操作全验一遍:

listDir(SD, "/", 0);
createDir(SD, "/mydir");
listDir(SD, "/", 0);
removeDir(SD, "/mydir");
listDir(SD, "/", 2);
writeFile(SD, "/hello.txt", "Hello ");
appendFile(SD, "/hello.txt", "World!\n");
readFile(SD, "/hello.txt");
deleteFile(SD, "/foo.txt");
renameFile(SD, "/hello.txt", "/foo.txt");
readFile(SD, "/foo.txt");
testFileIO(SD, "/test.txt");
Serial.printf("Total space: %lluMB\n", SD.totalBytes() / (1024 * 1024));
Serial.printf("Used space: %lluMB\n", SD.usedBytes() / (1024 * 1024));

烧录后打开串口监视器(波特率 115200),能看到卡类型、容量、目录列表和 "Hello World!" 被读回打印,像下面这样:

串口监视器输出:SD卡读写测试结果

想换引脚:自定义 SPI 四件套

默认引脚被别的器件占了也没关系,SD 库支持自定义 SPI 引脚。原教程给出的写法是自己起一个 SPIClass 实例,把四个引脚定义出来再传入 begin:

#define SCK  17
#define MISO  19
#define MOSI  23
#define CS  5
SPIClass spi = SPIClass(VSPI);
spi.begin(SCK, MISO, MOSI, CS);
if (!SD.begin(CS,spi,80000000)) {
  Serial.println("Card Mount Failed");
  return;
}

注意第三个参数 80000000 是 SPI 时钟频率 80MHz,原教程实测这个速率可用;如果你的卡座线较长或卡比较老,可以降到 4000000 一档求稳。

Card Mount Failed 排查清单

这个模块最常见的翻车点就集中在初始化失败上,按命中率排:

  • 接线错位:MOSI/MISO 插反是最多发的,卡座不报错、就是不挂载。逐根对照引脚表复查一遍。
  • 供电不对:接了 5V 或者电源经面包板压降不足,模块稳压不工作。3V3 引脚直接接 ESP32 的 3.3V 输出。
  • 卡没格成 FAT32:NTFS/exFAT 的卡挂载必失败,格式化一次就好。
  • 卡本身的问题:劣质卡、老卡在高速 SPI 下不稳,换一张正规品牌的卡试试;返回 CARD_NONE 说明卡座检测不到卡,重点查卡是否插到底。
  • GPIO 冲突:CS 引脚选了被 SPIFlash 或 strapping 占用的脚位会挂载失败,默认方案用 GPIO 5 就别乱挪。

把这几个点过一遍,绝大多数 "Card Mount Failed" 都能在五分钟内定位。SD 卡挂载成功之后,往下走就是接 BME280 之类的传感器做定时数据记录,或者用 ESPAsyncWebServer 直接把卡里的文件做成网页服务器——这两条路原教程都有后续篇,骨架就是本文这套 appendFile + readFile 的组合。存储这关过了,机器人的日志才算真正有了自己的黑匣子。


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


登录 后发表评论
5条评论
锡点
1楼 · 2026-11-09 10:56:20

Card Mount Failed 这条我太熟了,上次折腾一晚上最后发现是 MOSI/MISO 插反,引脚表看了三遍都没看出来。文中把排查点按命中率排这个思路很实在,新手照着过一遍真能省半天。

天快亮了
2楼 · 2026-11-09 10:56:20

FAT32 这步是劝退大户,32G 以上的卡 Windows 自带工具不给格,我第一次就卡在这

下班才有空
3楼 · 2026-11-09 10:56:20

追加日志那段写得好,FILE_APPEND 比 FILE_WRITE 适合数据记录场景,很多人不知道区别结果每次开机都覆盖上一轮数据,传感器日志直接清零,血泪教训。

学生党玩机
4楼 · 2026-11-09 10:56:20

80MHz 这个速率想提醒一句,我之前用杂牌卡座在 80M 下偶发挂载失败,降到 20M 就稳了,线长和卡质量都有影响,新手求稳可以先降速跑通再往上加。

老张装机
5楼 · 2026-11-09 10:56:20

SD_Test 示例里 testFileIO 那个读写测速函数也值得跑一下,能直接看到卡的吞吐,选卡的时候有个数。