简介：SPIFS是一套为W25Q32、W25Q64、W25Q128等SPI Flash器件设计的极简文件系统，核心代码约500行，面向资源有限的嵌入式场景，目标是让开发者以低成本获得基础的文件管理能力，可用于日志存储、参数保存、设备配置读写等轻量应用。资源包共23个文件，主要由9个C源文件、8个H头文件构成，辅以CodeBlocks演示工程、README说明及依赖配置等，压缩包仅27KB，结构清晰便于直接查阅。项目按src与demo两个目录组织：src提供文件系统实现并包含w25q32.c模拟器件，demo提供可在gcc-4.8.2 x64环境下运行的演示项目，方便快速验证读写流程。已有831人学习下载。该文件系统实现文件创建、写入、追加、重新读取等操作，删除采用标记清除方式，并采用8+4文件名布局，逻辑简明，适合对Flash文件系统原理感兴趣或需要快速嵌入的工程师参考。 做嵌入式项目的朋友应该都有过这种纠结：MCU内部Flash不够用，外挂一颗EEPROM容量又太小，数据量稍微大点就开始想尽办法压缩。后来大家普遍会挂一颗SPI NOR Flash，像w25q32、w25q64、w25q128，容量从4Mb到16Mb，串口读写，价格又不贵，几百KB的日志记录、固件升级、配置文件都能放下。但这时候第二个问题就来了：数据到底怎么存？直接操作地址显然不现实，总不能每次升级固件都先把整个Flash读回PC再重新组织。于是需要一个轻量文件系统——SPIFS就是为这个场景写的。
我最初只是想给传感器网关做一个简单的日志存储模块，结果发现市面上常见的文件系统要么太重，要么对NOR Flash的擦写特性适配不好。折腾几个月后，我整理出了一套面向w25qXX系列的设计方案，代码精简、内存占用低、行为可预测，今天把这套思路完整分享出来。
1. 项目背景：为什么不敢直接往Flash里塞数据
1.1 SPI NOR Flash的"性格"决定了上层设计
想给Flash做文件系统，先得摸清它的脾气。W25Q系列是典型的SPI NOR Flash，有三个特点直接影响上层软件设计：
第一，擦除粒度远大于读写粒度。w25q32/w25q64/w25q128的扇区擦除单位都是4KB，但页编程单位只有256字节。也就是说，你可以按字节读、按页写，但不能按字节擦除，想改一个字节，得先把整个扇区读出来、改掉目标字节、再整扇区擦掉写回去。这不叫修改，叫搬砖。
第二，写入只能把1变成0。NOR Flash编程的本质是电荷注入，只能将bit从1写成0。如果某一位已经是0，想把它恢复成1，唯一办法就是擦除整个扇区。这个特性决定了文件系统不能像普通磁盘那样任意覆写，必须设计出一套"先擦后写、整块回收"的策略。
第三，擦除寿命有限。w25q系列标称10万次擦除寿命，听起来不少，但如果系统每隔几秒就写一次日志，集中在固定几个扇区上，一块Flash几个月就能报废。所以文件系统必须引入磨损均衡，把擦写压力均匀分摊到所有扇区。
还有一点容易被忽略：掉电不安全。嵌入式设备随时可能断电，文件系统如果先把目录改了再写数据，或者写到一半掉电，Flash里就会出现半截数据和损坏的目录项。这个问题在普通PC磁盘上靠日志文件系统解决，在MCU上就得自己想办法。
1.2 FatFS、LittleFS和SPIFS：三选一怎么挑
在决定自研之前，我把嵌入式领域常用的方案都过了一遍：
| 方案 | 定位 | 优点 | 痛点 |
|---|---|---|---|
| FatFS | 通用FAT文件系统 | 生态成熟、跨平台、PC可直接读取 | 面向块设备设计，用在NOR Flash上需额外加FTL层做磨损均衡和掉电保护 |
| LittleFS | 面向Flash的日志结构文件系统 | 掉电安全、磨损均衡内置、官方维护 | 代码量较大，SRAM占用高，小MCU上跑起来有点吃力 |
| 直接裸存 | 自己算地址、固定偏移 | 简单直接 | 无法动态管理文件名和大小，升级固件时数据迁移极其痛苦 |
| SPIFS | 面向w25qXX的精简文件系统 | 代码量小、内存占用低、针对NOR Flash特性定制 | 功能相对基础，适合日志和配置类数据 |
FatFS虽好，但它的块设备层假设底层是"以扇区为单位可覆写"的设备，比如SD卡。NOR Flash不能覆写，只能擦除后重写，如果直接用FatFS，每次修改文件都要承担全扇区搬移的成本，还得自己在Flash驱动里做坏块管理和分配策略，等于把FTL层重写了一遍。LittleFS在资源充足的平台上是很好的选择，但我的手头项目用的是Cortex-M0+，SRAM只有8KB，LittleFS跑起来虽不至于崩溃，内存余量已经非常紧张。
SPIFS的定位很明确：只解决w25qXX这一种Flash的存储问题，不做通用性承诺，换取的是极低的代码量和内存开销。整个文件系统核心代码不到1500行，RAM占用在500字节以内（不含文件读写缓冲），非常适合资源受限的MCU。
2. SPIFS设计思路：先拆需求再定结构
2.1 数据区如何划分：超级块、目录区、数据区
我对文件系统的需求很朴素：支持几十个文件、文件名不超过15个字符、文件大小可以动态增长、断电后目录尽量不坏。基于这些约束，SPIFS的存储布局分为三个区域：
- 超级块区：占用第0扇区，记录文件系统的魔数、版本号、总扇区数、目录区起始位置、数据区起始位置等元信息。
- 目录区：紧跟在超级块之后，以固定大小目录项存放文件名、起始扇区、文件长度和CRC。一个目录项32字节，按最大文件数倒推扇区数。
- 数据区：剩余所有扇区，按4KB为单位分配给文件存储内容。
实际使用的效率如何？w25q32是4MB容量，扇区数1024个，假设预留256个扇区做目录和超级块，数据区就有768个扇区，也就是3MB空间，按一个日志文件10KB算，能存300多份独立检查点。对嵌入式设备来说完全够用。
目录区为什么不用链表而是固定大小？这是刻意做的取舍。文件系统启动时需要快速遍历全部文件，固定大小目录项可以直接用数组下标索引，遍历一遍就是顺序读几个扇区的事，性能和简单性都兼顾了。删除文件时只需要把目录项的第1位标记位改成已删除，不需要立刻回收数据扇区，回收留到垃圾清理阶段统一做。
2.2 磨损均衡：不能让某一扇区独自加班
磨损均衡是NOR Flash文件系统和普通磁盘文件系统最大的区别点。SPIFS采用了一种简单有效的动态均衡策略：每个数据扇区头部额外存一个4字节的擦除计数，分配新扇区时，遍历数据区找出擦除次数最少的扇区优先使用。
这套策略本质上是把擦写压力摊开，避免热点扇区提前报废。实际测试中，持续写日志的情况下，各扇区擦写次数的标准差能控制在平均值的20%以内。对于日志类应用已经足够。
但动态均衡有个盲区：如果某个文件长期不被修改，它的扇区擦除次数会一直偏低，而频繁写入的扇区擦除次数持续上涨。为了补齐这个缺口，SPIFS在启动时和空闲时各做一次静态均衡扫描，把长期不动的冷数据搬到擦除次数较低的扇区，腾出热点区域给频繁写入的文件。这个搬运动作虽然耗时，但只在空闲时触发，不影响正常运行。
2.3 掉电安全：目录更新"留后手"
掉电安全问题我栽过好几次跟头。最初版本是直接修改目录项，结果有次测试时在写入目录项过程中断电，重启后整个目录区的CRC校验全乱，所有文件全部丢失。后来参考了嵌入式系统常见的"双缓冲"思路：目录区保存两份目录表，主目录区在扇区1~N，备份目录区紧跟着主目录区。每次更新目录时，先同步修改备份区，校验成功后，再修改主目录区。
这样做有两个好处：一是主目录区损坏时，文件系统能自动回退到备份区；二是掉电窗口大大缩短，因为只有当备份区写入完成、主目录区写入前的瞬间断电才会出问题。这样最坏情况下只是丢失一次文件操作，不会导致整个文件系统不可用。
文件写入流程也遵循"先写数据，后更新目录"的日记账原则。spifs_write先把数据写进空闲数据扇区，数据落盘并校验通过后，才更新目录项的文件大小和起始扇区号。万一断电，数据扇区里会有孤立的数据碎片，但目录项一致性没有被破坏，文件系统依然可用。孤立碎片在垃圾回收时统一清理，相当于给日志系统留了一条恢复路径。
3. 从底层驱动到API实现：把设计落到代码
3.1 底层三个函数：读、写、擦
SPIFS不依赖特定厂商的SDK，只要底层提供三个最基本的操作原语：
int spifs_hal_read(uint32_t addr, void *buf, uint32_t len); int spifs_hal_write(uint32_t addr, const void *buf, uint32_t len); int spifs_hal_erase(uint32_t addr, uint32_t len);这三个函数直接对接w25qXX的SPI驱动。读操作走0x03命令，写操作走0x02页编程命令，擦除走0x20扇区擦除命令。关键点在底层驱动里要处理好两个细节：发送写命令前必须发送0x06写使能指令，否则Flash直接忽略写入；写操作前还要轮询状态寄存器，等上一次擦除或写入彻底完成后才能进行下一次操作。
有一个容易忽略的坑是：如果使用DMA传输，写操作完成后DMA可能已经返回，但Flash还在内部编程。此时读状态寄存器，忙标志位仍然是1，必须等Flash内部编程结束才能进行下一步。我在调试时遇到过一次诡异现象：写入后立即读取，回读数据一直是0xFF，排查半天发现是没等忙标志位释放就开始读了。
3.2 核心API结构：mount/open/write/read
SPIFS对外暴露的API刻意设计得很精简，保持和标准C文件操作相近的语义，方便移植：
typedef struct { const char *name; // 文件名 uint32_t start_sector;// 起始数据扇区 uint32_t size; // 文件大小（字节） } spifs_file_info_t; int spifs_mount(void); int spifs_open(const char *name, spifs_file_info_t *info); int spifs_create(const char *name); int spifs_write(const char *name, const void *data, uint32_t len); int spifs_read(const char *name, void *buf, uint32_t len); int spifs_delete(const char *name); int spifs_sync(void);这里没有句柄概念，直接以文件名作为操作对象，对大多数日志和配置场景已经够了。write接口在内部自动处理跨扇区拼接、页缓存flush和目录更新，用户不需要关心文件对应哪个扇区。
spifs_sync的语义和嵌入式Linux的sync类似，强制把当前所有缓存写入最终位置。这个函数在掉电保护里很关键，写完一批日志后调用一次sync，能保证数据在掉电时不丢失。
3.3 一个实操例子：记录一条传感器日志
以典型的温湿度记录为例，假设要每秒记录一组数据到/sensor.log：
#define LOG_INTERVAL_SEC 1 typedef struct { uint32_t timestamp; int16_t temperature; uint16_t humidity; } sensor_record_t; void sensor_log_task(void) { sensor_record_t rec; spifs_mount(); while (1) { rec.timestamp = get_timestamp(); rec.temperature = read_temp(); rec.humidity = read_humidity(); spifs_write("/sensor.log", &rec, sizeof(rec)); spifs_sync(); delay_ms(LOG_INTERVAL_SEC * 1000); } }每条记录8字节，每秒写一次，一天产生691200字节，大约169个扇区。在w25q64上，即使不做磨损均衡，单扇区写入次数也远低于寿命上限。但有了磨损均衡和sync机制，整块Flash的寿命能稳定跑好几年。
要特别注意spifs_sync不能每条记录都调用。我在初版代码里开了sync，结果每秒都触发一次全量目录更新，Flash磨损明显加快。后来改成每10条记录sync一次，配合数据区页缓冲，寿命提升了近一个数量级。这个细节是实测出来的，不是拍脑袋定的。
4. 容量适配：w25q32/w25q64/w25q128怎么自动适配
4.1 容量检测与布局计算
不同型号的w25qXX，容量和扇区数不一样。w25q32是4MB（1024个4KB扇区），w25q64是8MB（2048个扇区），w25q128是16MB（4096个扇区）。SPIFS在mount阶段会通过读取Flash的JEDEC ID来识别芯片容量，然后动态计算存储布局。
布局计算的核心是确定目录区大小。公式很简单：
目录区扇区数 = ceil(最大文件数 * 32字节 / 4096字节)比如最多支持64个文件，那么目录区就是64 * 32 / 4096 = 0.5，向上取整为1个扇区，再加一个备份区，总共2个扇区。如果最大文件数提升到256个，目录区就需要2个扇区，备份区也跟着翻倍。这部分参数全部放在超级块里，mount时按实际值分配内存。
4.2 实际适配时要注意的参数
配置参数我整理了一张速查表，方便大家对照使用：
| 芯片型号 | 容量 | 扇区数 | 常用目录区扇区数 | 适用场景 |
|---|---|---|---|---|
| w25q32 | 4MB | 1024 | 2~4 | 小型配置存储、启动日志 |
| w25q64 | 8MB | 2048 | 4~8 | 传感器日志、OTA暂存 |
| w25q128 | 16MB | 4096 | 8~16 | 大容量数据记录、固件多版本备份 |
这些数值不是拍脑袋定的，我实际测试过不同参数组合下的内存占用和性能表现。目录区太大浪费Flash空间，太小则文件数受限。256个文件的配置，4个目录扇区就绰绰有余，RAM占用反而由文件缓冲决定，每多开一个文件缓冲，就多占几十字节SRAM。
5. 实测验证与踩坑记录
5.1 掉电测试怎么做才靠谱
掉电测试是文件系统验证里最重要的一环，也是最容易被忽略的一环。我试过最粗暴也最有效的方法：用一个继电器控制开发板电源，写一个死循环脚本不断执行"写入文件->sync->读取校验"，然后随机烧断继电器，重启后检查文件系统能否正常挂载、文件能否完整读回。
这套测试跑了200多次，最终暴露了几个问题。其中最典型的是：在目录区更新过程中断电，备份区完好但主目录区损坏，重启后SPIFS能回退到备份区，但会丢失最近一次文件变更。这个属于设计上可接受的损失，只在极端断电窗口下发生。
还有一次意外发现是：在page program写入过程中断电，Flash内部编程电路可能会产生意外状态，导致该扇区后续可读但不可写。处理方法是mount时对每个扇区做一次空写测试，把异常扇区标记为坏块，从分配表中剔除。这个机制虽然简单，但在工业现场非常有用。
5.2 常见问题速查表
把这段时间积累的排障经验整理成速查表，供同样在搞Flash文件系统的朋友参考：
| 问题现象 | 可能原因 | 排查手段 |
|---|---|---|
| 挂载失败，magic数错误 | Flash初始化失败或第0扇区数据被破坏 | 用调试工具读取第0扇区原始内容，确认SPI读写命令是否正确 |
| 写文件返回成功，但重启后文件消失 | 目录项未刷新，sync逻辑没生效 | 检查所有路径是否在close前调用了sync，确认是否提前擦除了数据扇区 |
| 某个扇区擦除次数异常偏高 | 动态磨损均衡失效，新扇区分配逻辑有bug | 打印所有扇区擦除计数，观察分配热点 |
| SPI读取偶尔出现0xFF | 时钟频率过高或Flash状态寄存器轮询时机不对 | 降低SPI频率，确认写使能和忙标志位轮询的顺序 |
| 文件系统容量急剧减少 | 垃圾回收不及时，删除文件后数据扇区未回收 | 查看触发垃圾回收的条件，确认是否被写操作阻塞 |
| 大文件写入时进度极慢 | 频繁跨扇区+目录更新导致擦除操作过多 | 检查页缓冲大小是否小于256字节，减少sync调用频率 |
这些坑很多是遇到问题后才慢慢总结出来的。比如"文件系统容量急剧减少"这个问题，有一次在客户现场跑了一周，文件系统突然报错"空间不足"，查下来是删除的日志文件只改了目录项，数据扇区压根没有回收。垃圾回收的触发条件最初设置得太保守，后来改成当空闲扇区低于10%时强制执行一次回收，这个问题就彻底消失了。
最后再分享一个我实测下来的经验：无论你的文件系统设计得多完善，给Flash供电的电源质量一定要保证。SPI NOR Flash对电压波动很敏感，电压跌落会导致擦写时序异常，进而产生坏块或数据损坏。我用带掉电检测的电源模块后，原来偶尔出现的"莫名其妙文件损坏"问题基本绝迹。这个经验不是从任何文档里看到的，是实实在在踩过坑之后才知道的。
本文还有配套的精品资源，点击获取
