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

先认识模块:6 个引脚的 SPI 卡座
市面上兼容 ESP32 的 microSD 模块不少,原教程用的是最常见的 SPI 接口款:一块小 PCB,上面一个卡座,边上一排 6 根针。它走 SPI 协议通信,除了 ESP32,同样兼容 Arduino 和 ESP8266 NodeMCU,属于"一个模块三块板通用"的类型。
引脚定义如下,这是后面接线的全部依据:
| 模块引脚 | 接 ESP32 |
|---|---|
| 3V3 | 3.3V |
| CS | GPIO 5 |
| MOSI | GPIO 23 |
| CLK | GPIO 18 |
| MISO | GPIO 19 |
| GND | GND |

接线与一张原理图就够
接线用 ESP32 的默认 VSPI 引脚,四根信号线加两根电源线,面包板插完大概一分钟。需要注意的只有一个点:这个模块是 3.3V 供电,不要接到 5V/ VIN 上,卡座和电平转换电路都是按 3.3V 设计的。
对照下面这张原理图插线即可,信号线顺序记成"MOSI 上 23、MISO 下 19、CLK 18、CS 5"基本不会错。

动手前两件小事:格式化与开发环境
第一件,把 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!" 被读回打印,像下面这样:

想换引脚:自定义 SPI 四件套
默认引脚被别的器件占了也没关系,SD 库支持自定义 SPI 引脚。原教程给出的写法是自己起一个 SPIClass 实例,把四个引脚定义出来再传入 begin:
#define SCK 17
#define MISO 19
#define MOSI 23
#define CS 5SPIClass 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 的组合。存储这关过了,机器人的日志才算真正有了自己的黑匣子。











Card Mount Failed 这条我太熟了,上次折腾一晚上最后发现是 MOSI/MISO 插反,引脚表看了三遍都没看出来。文中把排查点按命中率排这个思路很实在,新手照着过一遍真能省半天。
FAT32 这步是劝退大户,32G 以上的卡 Windows 自带工具不给格,我第一次就卡在这
追加日志那段写得好,FILE_APPEND 比 FILE_WRITE 适合数据记录场景,很多人不知道区别结果每次开机都覆盖上一轮数据,传感器日志直接清零,血泪教训。
80MHz 这个速率想提醒一句,我之前用杂牌卡座在 80M 下偶发挂载失败,降到 20M 就稳了,线长和卡质量都有影响,新手求稳可以先降速跑通再往上加。
SD_Test 示例里 testFileIO 那个读写测速函数也值得跑一下,能直接看到卡的吞吐,选卡的时候有个数。