刚玩ESP32那会儿我用的是最早一批WROOM-32开发板Flash总共4MB。程序、字库、网页资源一塞剩余空间基本见底。当时想做一个带网页配置和简单日志上报的小设备数据量虽然不大但架不住Flash不够用。后来才想明白一件事ESP32本身就不是为了“存放大量数据”设计的想拥有海量存储空间最省事、成本最低、通用性最强的方案就是外挂一张SD卡。这篇文章把读写SD卡这件事从头到尾捋一遍。硬件怎么接、代码怎么写、初始化为什么失败、数据为什么会丢这些零基础容易卡住的地方都会讲到。文章基于ESP32 Arduino开发环境适合刚把ESP32跑起来、想让它保存更多数据的玩家。看完你不仅能写出“创建文件、写日志、读配置”这类基础操作还能避开不少我踩过的坑。1. 为什么要给ESP32外接SD卡先算一笔存储账1.1 板载Flash到底能装多少东西ESP32开发板上的Flash大小常见有4MB、8MB、16MB听起来好像不小但真正能用的是打折后的。一个Arduino工程编译出来带WiFi、BLE、HTTP Server的固件动辄1~2MB如果再开OTA升级又要额外留一个同等大小的分区。也就是说你买了一块16MB Flash的开发板实际留给文件存储的可能也就几MB甚至在某些默认分区表下只有几百KB。SPIFFS和LittleFS虽然能挂载到内部Flash但它们给用户用的空间本来就是从整个Flash里抠出来的。你在IDE里选择分区方案时会看到“Huge APP”“Minimal SPIFFS”这类选项选择恐惧症直接犯了。而且Flash是有擦写寿命的频繁写入日志对Flash并不友好数据量一大整个方案就站不住脚。1.2 SD卡在存储扩展方案里的定位给ESP32扩存储市面上其实有几条路内部Flash的LittleFS、外部SPI Flash芯片、SD卡。三者各有各的用途但SD卡的优势非常明显容量可以做到几十GB级别拔下来插电脑就能直接读取格式化也方便成本只有几块钱到十几块钱。对于数据采集、日志记录、离线素材存放、Web服务器静态文件这类场景SD卡是最合适的“仓库盘”。SD卡不是用来跑程序的而是用来“装东西”的。理解这一点很重要。你不会想把代码里频繁查找的配置数据库放SD卡上但你会想把几十MB的传感器历史数据、图片素材、音频文件放上去。搞清楚这个定位后面的技术选型就顺了。2. 硬件准备与SPI接线第一道门槛2.1 模块选型自带电平转换的模块最省心SD卡本身是3.3V逻辑工作电压也是3.3V。但很多零基础玩家手里可能只有5V输出的模块或者直接把裸卡座往面包板上一插结果SD卡要么不识别要么频繁出错。这里建议直接买“Micro SD卡模块”尽量选带3.3V稳压器和电平转换电路的版本。这种模块通常有4到6个引脚VCC、GND、CS、SCK、MOSI、MISO有的还引出CD卡检测引脚后面会细说。模块上有没有电平转换芯片可以看板子上的丝印常见的有“74LVC245”“TXS0108”等字样的芯片。如果模块只是几个电阻直接连出来那你就得把它当成裸卡座对待老老实实只接3.3V并自己处理电平兼容。零基础阶段别给自己加戏直接买“带电平转换”的模块能少踩一半坑。卡的种类也建议用正规品牌的TF卡容量在2GB到32GB之间初始阶段别拿那种“路边送的杂牌卡”来测试否则你会以为是代码问题其实是卡本身就有问题。2.2 接线表与引脚选择逻辑ESP32的SPI接口有两组VSPI和HSPI。Arduino环境下默认用的是VSPI引脚分布为SCKGPIO18、MISOGPIO19、MOSIGPIO23、SSGPIO5。这个组合也是最常见的接法零基础直接照着接就行。接线表如下SD卡模块引脚ESP32开发板引脚VCC3.3V或者模块规格书注明的5V输入GNDGNDCSGPIO5SCKGPIO18MOSIGPIO23MISOGPIO19有人会问为什么不用ESP32自带的SDMMC接口那玩意儿速度快4-bit模式能跑到几十MB/s但它有几个引脚和启动配置位有关比如GPIO12在上电时的电平会影响Flash工作电压接错之后可能直接导致开发板上电失败或Flash异常。零基础阶段用SPI模式稳定、代码简单、网上资料最多速度对日志和配置文件来说绰绰有余。CS引脚其实可以换只要避开启动关键引脚就行。比如GPIO15TDO默认上电时需要保持低电平你硬把CS接上去可能没大问题但如果卡上电时把线拉高就不太好了。建议就用GPIO5这个引脚被SD卡示例默认绑定省心。2.3 供电细节与上拉电阻SD卡在读写时的瞬时电流可以达到100mA以上虽然ESP32开发板上的3.3V LDO通常能提供几百mA但如果你同时接了OLED屏幕、传感器、舵机等一堆外设3.3V总线上电压可能被拉低出现“卡挂载成功但读写出错”的诡异问题。我的建议是模块的VCC单独接3.3VGND共地如果外设太多考虑用外部3.3V稳压模块给SD卡单独供电或者至少别把所有大电流设备都堆在同一路LDO上。关于上拉电阻很多模块没有给MISO加上拉。SD卡在SPI模式下MISOD0信号线建议通过10kΩ电阻上拉到3.3V避免卡未选中时信号悬空产生干扰。如果你的模块没有明确标注内置上拉自己在MISO与3.3V之间焊一个10kΩ电阻。这不是玄学而是SD卡规范的要求。你可能觉得不加上拉也能跑但偶尔读取出错的“偶发性问题”往往就出在这种细节上。3. 初始化SD卡从格式化到代码跑通3.1 先把卡格式化成FAT32SD卡不是插上就能用文件系统得对上号。ESP32的SD库默认支持FAT32这是最稳妥的选择。新买的卡或者是旧手机上拆的卡可能格式是exFAT或者是NTFSESP32不一定认所以第一步就是在电脑上把卡格式化成FAT32。Windows资源管理器自带的格式化工具最大只支持到32GB容量超过32GB的卡界面里根本看不到FAT32选项。这种情况可以用SD协会官方的SD Card Formatter工具或者命令行执行format /FS:FAT32 X:X是卡符但大容量卡全盘格式化会有点久。macOS用户用“磁盘工具”格式选“MS-DOS (FAT)”即可。Linux下用mkfs.vfat -F 32 /dev/sdX1。格式化会清空卡上所有数据操作前注意备份。3.2 最小初始化代码代码方面Arduino IDE需要先装好ESP32开发板支持包然后在工程里包含FS.h、SD.h、SPI.h三个头文件。我整理了一份最精简的初始化代码#include FS.h #include SD.h #include SPI.h #define SD_CS 5 #define SPI_SCK 18 #define SPI_MISO 19 #define SPI_MOSI 23 void setup() { Serial.begin(115200); SPI.begin(SPI_SCK, SPI_MISO, SPI_MOSI, SD_CS); if (!SD.begin(SD_CS)) { Serial.println(SD Card Mount Failed); return; } uint8_t cardType SD.cardType(); if (cardType CARD_NONE) { Serial.println(No SD card attached); return; } Serial.println(SD Card Mounted); Serial.printf(Total space: %llu MB\n, SD.totalBytes() / (1024 * 1024)); Serial.printf(Used space : %llu MB\n, SD.usedBytes() / (1024 * 1024)); } void loop() {}上电后打开串口监视器波特率115200如果能看到“SD Card Mounted”以及容量信息说明硬件和初始化已经没问题。如果你的开发板引脚被占用需要自定义SPI引脚SPI.begin第一个参数是SCK第二个是MISO第三个是MOSI第四个是CS顺序别搞反了很多新手在这一步把MISO和MOSI接反导致初始化失败。SD.begin(SD_CS)内部的默认SPI时钟频率不算太高对于普通杜邦线接线是够用的。如果线路比较长或模块质量一般也可以手动压低SPI频率来换取稳定写成SD.begin(SD_CS, SPI, 10000000)就是10MHz再不行就4MHz。稳定压倒一切别急着追求速度。3.3 初始化失败时的排查顺序遇到“Card Mount Failed”不要慌这是一步一步排查的事。下面是我自己反复用过很多遍的排查链路建议按顺序来不要跳步先确认CS引脚在代码里和实际接线一致。GPIO5就是GPIO5别看着丝印是D5就真的接5号引脚不同开发板的丝印规则乱七八糟。把SD卡重新插拔一次确保卡座金属弹片接触良好。插卡时要听到“咔哒”一声插到底。检查卡是否已经格式化为FAT32。在电脑上重新格式化别用exFAT。换一张已知正常的SD卡再试。这一步能快速排除“卡本身是坏的”这种最让人绝望的情况。用万用表测模块VCC对GND电压确保在3.3V左右。如果电压低到3.0V以下检查供电。在MISO线上加上10kΩ上拉电阻如果模块没内置这一步经常能救回来。把SPI时钟降到4MHz再试通过SD.begin(SD_CS, SPI, 4000000)。检查杜邦线长度。十几厘米的线已经是极限线越长信号越差波形越丑。换一块开发板或者换一个SD卡模块排除硬件个体差异。这套流程走一遍90%以上的初始化问题都能暴露出来。最怕的是“偶尔能挂载偶尔不能挂载”这种问题多半是接触不良或供电不稳跟代码关系不大。4. 文件读写实战从建文件到日志记录4.1 打开文件的几种模式SD库提供了一套类似C语言FILE的操作接口最常用的打开模式有四种FILE_READ、FILE_WRITE、FILE_APPEND以及通过字符串方式指定r、w、a。它们之间的区别直接决定了文件内容会不会被覆盖这一点必须搞清楚。打开模式行为常用场景FILE_READ以只读方式打开文件文件不存在则失败读取配置、读取日志FILE_WRITE以写方式打开从文件头开始覆盖写创建/重写配置文件FILE_APPEND以写方式打开从文件尾部追加追加日志、累积数据点r同FILE_READ兼容写法w同FILE_WRITE兼容写法a同FILE_APPEND兼容写法有个零基础很容易踩的坑在ESP32的SD库中FILE_WRITE并不像某些其他平台那样是“追加写”而是覆盖写。如果你打开一个已有文件写入比原文件短的内容部分固件版本不会自动把旧文件截断文件尾部会出现“原来的残留数据”看起来就像文件损坏了。所以我的习惯是如果是彻底重写一个文件先执行SD.remove(path)再写如果想不清空原文件只往后面加内容一定用FILE_APPEND。4.2 写入数据print、println、write、flush写入文本数据最常用的就是file.print()和file.println()用法和Serial.print几乎一样。写入二进制数据则用file.write(buf, len)。一段完整的写入操作长这样File file SD.open(/hello.txt, FILE_WRITE); if (!file) { Serial.println(Failed to open file for writing); return; } file.println(Hello, SD Card!); file.print(Temperature: ); file.println(26.5); file.write((uint8_t*)\x01\x02\x03, 3); file.flush(); file.close();这里要特别强调flush的作用。SD卡的数据不是写一个字节就立即落盘一字节文件系统会先把数据放进缓冲区缓冲区满了或者收到flush/close命令才真正写入物理介质。这不只是速度优化更是数据安全的一部分。如果你写完不调用close就突然断电最后写入的那部分数据大概率丢失甚至可能导致文件系统元数据损坏。关于这一点后面单独开一节细说。4.3 读取数据逐字节、按行、分块读取文件的套路也很固定。逐字节读取适用于小文件按行读取适用于CSV这类文本配置分块读取适用于大文件。先看一个按行读取CSV日志的例子File dataFile SD.open(/log.csv, FILE_READ); if (!dataFile) { Serial.println(Failed to open file for reading); return; } while (dataFile.available()) { String line dataFile.readStringUntil(\n); Serial.println(line); } dataFile.close();readStringUntil适合读文本行但如果文件很大或者每行非常长用String去接会占用不少RAMESP32虽然内存比普通ATmega大不少但也不是无底洞。处理大文件时更好的做法是用固定缓冲区分块读File f SD.open(/big.bin, FILE_READ); if (!f) return; uint8_t buf[512]; int n; while ((n f.read(buf, sizeof(buf))) 0) { // 每次处理512字节 } f.close();这种方式无论文件多大内存占用始终不超过512字节是处理音频、图片等大文件时的标准姿势。零基础阶段可以先把逐字节和按行读法练熟分块读法是接下来进阶的必经之路。4.4 做一个真实可用的日志系统下面放到实际场景里。假设你要做一个环境数据记录器每隔一段时间把温湿度写到SD卡上的CSV文件里要求不能覆盖历史数据。代码可以这样写float readTemp() { // 接DHT11/DHT22时替换成真实读取代码 return 26.5 random(-30, 30) / 10.0; } float readHumi() { // 接DHT11/DHT22时替换成真实读取代码 return 60.0 random(-50, 50) / 10.0; } void logData() { // 检查文件是否存在不存在则先写表头 if (!SD.exists(/log.csv)) { File header SD.open(/log.csv, FILE_WRITE); if (header) { header.println(time,temp,humi); header.close(); } } File logFile SD.open(/log.csv, FILE_APPEND); if (!logFile) { Serial.println(Open log.csv failed); return; } logFile.print(millis()); logFile.print(,); logFile.print(readTemp()); logFile.print(,); logFile.println(readHumi()); logFile.close(); } void setup() { Serial.begin(115200); SPI.begin(18, 19, 23, 5); if (!SD.begin(5)) { Serial.println(SD Card Mount Failed); return; } } void loop() { logData(); delay(5000); }这套代码里有一个小细节值得注意写表头之前先调用SD.exists(/log.csv)判断文件是否存在。因为文件打开用FILE_WRITE会覆盖所以“建表头”和“写数据”必须分开处理不能让每次跑日志都先创建一个新文件覆盖旧数据。实际跑起来后拔卡插到电脑上用Excel或Notepad打开log.csv就能看到一行行的数据记录。这个操作流程跑通说明你已经掌握了SD卡读写最核心的链路。5. 数据可靠性经验掉电、长文件名、大文件这些细节决定成败5.1 flush和close别让最后一条数据悄悄消失我在做室外采集设备时遇到过一件特别恼火的事设备断电重启后日志文件最后几条数据经常消失有时候甚至整个文件变成0字节。排查到最后绝大多数原因都是没有正确调用close或flush。SD库的写入有缓冲区print和write只是把数据放进了内存缓冲真正写进卡里需要等到缓冲区满、显式调用flush或close。flush负责把缓冲区的数据送到卡上close在flush的基础上还会关闭文件、更新文件目录项比如文件长度、修改时间这些信息。长期记录数据的设备写完一条就close一次比较稳妥代价是频繁开关文件会让写入速度变慢对卡的磨损也略大。我的折中方案是重要数据每条都flush每隔一段时间或者批量写完再close低频率的日志系统直接每条写完后close简单可靠。原则就一个任何情况下别在没调用close之前直接断电。5.2 追加模式和长期记录的正确姿势日志系统要长期运行必然涉及“只往文件尾部添加内容”的需求。FILE_APPEND就是为此设计的。但追加模式也有讲究每次打开文件都是以追加方式打开写完关闭下次再打开继续追加。这个模式适合低频写入每次需要打开、定位到尾部、写入、关闭有一点点开销但对绝大多数日志场景完全够用。如果是高频记录比如每秒写几十条甚至上百条频繁开关文件的开销会变大。这时候可以打开文件后保持不关闭持续往里面写但一定别忘了周期性调用flush。这里要注意如果设备意外断电保持打开状态的文件可能丢失最后一段未flush的数据甚至目录项来不及更新。对于高频记录场景建议在内存里再缓存一批数据凑够一定条数或者每隔几秒批量写一次既减少写入次数也降低数据丢失的风险。5.3 文件名与目录规范避开中文和特殊符号SD卡上的文件名不是随便起的。FAT32文件系统支持长文件名但ESP32的FATFS底层在处理某些中文编码时容易出问题。你在电脑上建了一个“测试数据.txt”拿到ESP32上可能能读出来但ESP32自己创建中文文件名再插回电脑大概率出现乱码。这不是某块板子的毛病而是字符编码转换的老问题。稳妥的做法是统一使用英文字母、数字、下划线、中划线例如log_20240101.csv、config.ini、data.bin不要带空格和中文。另一个容易忽略的是目录。SD.open(/data/log.txt, FILE_APPEND)需要/data目录已经存在否则打开文件会失败。目录得先创建if (!SD.exists(/data)) { SD.mkdir(/data); }养成好习惯文件路径里的每一级目录要么已经存在要么先显式创建别指望库函数自动帮你补一个目录出来。5.4 大文件分块读写与空间判断前面提到了分块读取写入也一样。当你要把一块大的数据写入SD卡时不要写一个几百KB甚至几MB的数组然后一次性write出去。ESP32虽然内存有几百KB可用但也不能这么挥霍。正确做法是分块写入比如每次写512字节或1024字节写完后立即继续下一块。写入前最好判断一下卡上的剩余空间。SD.totalBytes()和SD.usedBytes()返回总容量和已用容量相减就是剩余空间。这个函数不是免费的计算量不小别在循环里频繁调用。比较好的做法是每次写入前调用一次剩余空间低于某个阈值就开始清理旧文件或者停止记录避免写满后出现错误。5.5 山寨卡与磨损均衡的隐患很多人喜欢买“白菜价”SD卡结果就是读写速度忽快忽慢偶尔出现坏块甚至格式化完没几天又出问题。SD卡内部其实有主控和Flash正品卡的主控有磨损均衡、坏块管理逻辑山寨卡可能什么都没有或者做得很差。SD卡作为可插拔介质本来就不适合长期高频写入但这不代表它不靠谱关键是选卡。买卡的时候尽量选择主流品牌别贪便宜。如果项目对可靠性要求很高建议在硬件设计上做掉电保护比如在SD卡供电端加一个容量稍大的电容给文件系统留出完成写入的时间。这个细节在工业现场能救命。6. 高频踩坑速查与进阶方向6.1 高频踩坑速查表把零基础玩家最常见的SD卡问题整理成了一张表照着排查能省不少时间现象常见原因处理方法串口输出Card Mount Failed卡未格式化、接触不良、CS接错重新格式化FAT32、插紧卡、核对CS引脚挂载成功但打不开文件目录不存在、文件名非法先SD.mkdir建目录文件名改英文短名文件打开成功但写入内容丢失没调close/flush、供电不足写完必须flush/close检查3.3V电压数据写了一半卡死SPI线太长、时钟太快降低SPI频率缩短杜邦线卡在电脑上正常但ESP32不认文件系统是exFAT/NTFS重新格式化为FAT32偶尔能挂载偶尔失败供电不稳、MISO缺上拉补10kΩ上拉电阻外设分开供电日志尾部有旧数据FILE_WRITE覆盖写不截断先SD.remove再写或用FILE_APPEND中文文件名乱码编码不兼容全部改用英文数字下划线这张表是我自己在项目里反复踩坑总结出来的不一定覆盖所有问题但覆盖了绝大多数零基础玩家会遇到的状况。6.2 再往前走SD卡还能这么玩读写SD卡只是第一步。把基础稳定之后可以做的事情很多每条都值得单独开一篇来讲。比如把ESP32配置成一个小型Web服务器网页文件放在SD卡上通过浏览器访问ESP32的IP就能直接浏览文件列表、下载日志、甚至上传新文件。再比如配合音频解码模块从SD卡读取MP3或WAV文件做语音播放做一个能定时播报的闹钟或语音提示器。数据采集方向可以做得更深把传感器数据按天存到不同CSV文件定期清理过期数据写一个简单的FATFS巡检逻辑保证SD卡长时间运行不出错。我个人在实际项目中的体会是SD卡读写初看简单但真正决定一个设备是“能跑”还是“能稳定跑”的往往是细节。比如代码里有没有养成“文件不使用了就close”的习惯硬件上有没有把供电和上拉做扎实选卡时有没有多花几块钱买一张正经卡。这些经验不是看文档能看出来的是踩坑踩出来的。最后再分享一个小技巧调试SD卡问题的时候别老盯着代码看。用串口把SD.cardType()、SD.totalBytes()、SD.usedBytes()打出来先确认物理层和文件系统层是通的再去分析文件操作逻辑。很多莫名其妙的“代码问题”最后都回到了“卡没插紧”或者“供电不够”这种最朴素的根因上。SD卡这个外设只要能稳住电源、稳住信号、稳住文件关闭时机基本就能稳稳陪你很久。
