【MicroPython ESP32】SPI总线驱动SD卡：从硬件连接到文件系统挂载实战
1. ESP32与MicroPython开发环境搭建
第一次接触ESP32和MicroPython的朋友可能会觉得有点懵，其实这就像给手机刷机一样简单。我刚开始玩ESP32的时候，花了一整天时间折腾环境配置，现在把最顺手的方案分享给大家。
首先需要准备硬件：一块ESP32开发板（推荐NodeMCU-32S这种带USB接口的）、一张MicroSD卡（建议用8GB以下的，兼容性更好）、SD卡模块（淘宝上5块钱的那种SPI接口的就行）。软件方面需要Thonny IDE，这是目前对MicroPython支持最好的开发工具。
安装固件时有个坑要注意：一定要选择带SPI支持的MicroPython固件。我推荐使用官方v1.19.1版本，这个版本对SD卡的支持最稳定。刷机步骤很简单：
- 下载ESP32的MicroPython固件
- 用esptool.py工具写入开发板
- 连接Thonny后就能看到交互式命令行
# 检查固件版本 import os os.uname() # 应该看到类似这样的输出： # (sysname='esp32', nodename='esp32', release='1.19.1', version='v1.19.1...')2. 硬件连接与SPI总线配置
ESP32有两个SPI总线：HSPI和VSPI。实测下来VSPI（默认引脚）对SD卡的兼容性更好。接线时最容易出错的是电平问题，3.3V的ESP32要接3.3V的SD卡模块，5V的模块需要电平转换。
具体接线方案：
- SD模块的CLK接GPIO18（实测这个引脚最稳定）
- MOSI接GPIO23
- MISO接GPIO19
- CS接GPIO5（这个可以自定义）
- 电源接3.3V和GND
这里有个隐藏知识点：ESP32的SPI时钟频率可以到80MHz，但SD卡初始化时必须用低速（400kHz以下），初始化完成后再提升速度。我遇到过因为时钟频率设置不当导致SD卡无法识别的问题，后来发现是模块质量问题，换了更好的模块就稳定了。
3. SD卡驱动加载与文件系统挂载
MicroPython内置了sdcard模块，但需要手动加载。这里分享一个我优化过的代码模板：
import machine, os from machine import Pin, SPI import sdcard # 初始化SPI总线 sd_spi = SPI(2, sck=Pin(18), mosi=Pin(23), miso=Pin(19)) # 初始化SD卡 sd = sdcard.SDCard(sd_spi, Pin(5)) # 挂载为文件系统 vfs = os.VfsFat(sd) os.mount(vfs, "/sd") # 测试挂载 print(os.listdir("/sd")) # 应该看到SD卡根目录文件列表常见问题排查：
- 如果报错"no SD card"，检查接线和电源
- 出现"invalid block size"可能是文件系统格式问题，需要在电脑上格式化为FAT32
- "OSError: timeout"通常是SPI时钟频率过高，尝试降低到100kHz
4. 文件操作实战技巧
挂载成功后，就可以像操作普通文件系统一样使用SD卡了。分享几个实用技巧：
大文件写入优化：ESP32的内存有限，写大文件时要分块：
def write_large_file(filename, data, chunk_size=512): with open(f"/sd/{filename}", "wb") as f: for i in range(0, len(data), chunk_size): f.write(data[i:i+chunk_size]) f.flush() # 确保数据写入物理存储中文文件名处理：MicroPython默认不支持中文路径，需要额外处理：
def safe_filename(name): return name.encode('ascii', 'ignore').decode('ascii')掉电保护技巧：突然断电可能导致文件损坏，重要操作后应该同步：
import gc def safe_operation(): try: # 文件操作代码... finally: os.sync() gc.collect()5. 性能优化与高级应用
经过多次测试，我发现这些参数组合性能最好：
- SPI时钟：初始化后可以提升到20MHz
- 缓冲区大小：512字节对齐时速度最快
- 文件缓存：适当增加缓存能提升小文件读写速度
# 高性能配置示例 sd_spi.init(baudrate=20000000) # 20MHz sd = sdcard.SDCard(sd_spi, Pin(5), baudrate=20000000)对于需要实时数据记录的项目，可以结合定时器实现自动保存：
from machine import Timer def log_sensor_data(t): with open("/sd/data.csv", "a") as f: f.write(f"{time.ticks_ms()},{sensor.read()}\n") tim = Timer(0) tim.init(period=1000, mode=Timer.PERIODIC, callback=log_sensor_data)6. 常见问题解决方案
问题1：SD卡频繁掉线
- 检查电源是否稳定（最好单独供电）
- 缩短接线长度（建议小于10cm）
- 在CS引脚加10k上拉电阻
问题2：写入速度慢
- 确保使用高品质SD卡（Class10以上）
- 关闭文件系统实时同步
os.umount("/sd") os.mount(vfs, "/sd", readonly=False, sync=False)问题3：文件系统损坏
- 准备修复工具函数：
def repair_filesystem(): os.umount("/sd") os.VfsFat.mkfs(sd) # 重新格式化 os.mount(vfs, "/sd")最后提醒大家，操作完成后一定要安全卸载：
os.umount("/sd") # 防止数据丢失