ESP-IDF SPIFFS 文件系统完全指南从分区挂载到镜像生成与故障恢复【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfSPIFFSSPI Flash File System是专为嵌入式 SPI NOR Flash 设计的高可靠性文件系统在 ESP-IDF 中作为官方存储组件提供支持磨损均衡wear levelling与文件系统一致性检查。本文以 docs/en/api-reference/storage/spiffs.rst 为骨架结合 components/spiffs 组件源码与storage/spiffs、storage/spiffsgen两个示例工程完整讲解 SPIFFS 的设计约束、分区配置、esp_spiffs.h高层 API、以及spiffsgen.py与mkspiffs两种镜像生成工具的使用方法帮助你掌握分区 → 挂载 → 读写 → 镜像预生成 → 故障恢复的全链路实践。概述为什么在 ESP32 上选择 SPIFFSSPIFFS 是为嵌入式目标上的 SPI NOR Flash 设备设计的文件系统。它具备两个区别于传统文件系统的核心能力磨损均衡wear levelling均匀分布 Flash 块的擦写次数延长存储介质寿命文件系统一致性检查通过esp_spiffs_check等机制在异常掉电后修复文件系统。在 ESP-IDF 中SPIFFS 通过 VFSVirtual File System层与 C 标准库 / POSIX API 无缝衔接应用代码可以像操作普通文件一样使用fopen、fprintf、rename、stat、unlink等函数参见 examples/storage/spiffs/main/spiffs_example_main.c。使用 SPIFFS 前必须了解的设计约束SPIFFS 的简单与可靠建立在若干明确的设计取舍之上官方文档对此有非常清晰的说明实际选型时必须逐条评估不支持目录只产生扁平结构。如果 SPIFFS 挂载在/spiffs下那么创建路径为/spiffs/tmp/myfile.txt的文件实际会在 SPIFFS 中生成名为/tmp/myfile.txt的文件而不是在/spiffs/tmp目录下创建myfile.txt。不是实时文件系统。一次写操作可能比另一次写操作耗时长得多的多不适合对单次操作延迟有硬性要求的场景。当前版本不检测也不处理坏块bad blocks。SPIFFS 只能可靠利用所分配分区空间的约 75%。分区规划时必须预留余量避免看似空间足够、实际无法写入的窘境。空间耗尽时垃圾回收GC会非常缓慢。当文件系统空间不足时垃圾回收器会多次扫描整个文件系统来寻找空闲空间根据所需空间的大小单次写函数调用可能耗时数秒。这是 SPIFFS 自身设计所致只能通过 SPIFFS 配置项部分缓解见下文GC 与配置项。GC 单次回收能力有限。垃圾回收器每次扫描默认通常为 10 次由SPIFFS_GC_MAX_RUNS配置项控制只能释放一个块block。如果 GC 最大运行次数设为n那么可供数据写入的空间最多为n × block_size若尝试写入的数据超过该上限写入操作可能失败并返回错误。掉电可能导致文件系统损坏。在文件系统操作过程中掉电可能造成 SPIFFS 损坏但通常仍可通过esp_spiffs_check函数恢复详见官方 SPIFFS FAQ。这些约束决定了 SPIFFS 适合数据量可控、以读取为主、小文件居多的存储场景如 Web 静态资源、配置文件而不适合大文件频繁写入或强实时场景。在 ESP-IDF 中启用并挂载 SPIFFS 分区分区表配置首先需要在分区表partition table中为 SPIFFS 划分区域类型为data、子类型为spiffs。参考示例 examples/storage/spiffs/partitions_example.csv 中的写法# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, storage, data, spiffs, 0x110000,0x100000,注意分区大小必须是 SPIFFS 块大小的整数倍spiffsgen.py会校验img_size % block_size 0见 components/spiffs/spiffsgen.py 中的SpiffsFS.__init__。高层 APIesp_spiffs.hSPIFFS 的高层接口全部集中在 components/spiffs/include/esp_spiffs.h共 7 个函数构成了完整的注册-挂载-使用-卸载生命周期函数作用关键返回码esp_vfs_spiffs_register初始化并挂载 SPIFFS同时注册到 VFSESP_OK/ESP_ERR_NO_MEM/ESP_ERR_INVALID_STATE已挂载或分区被加密/ESP_ERR_NOT_FOUND未找到分区/ESP_FAIL挂载或格式化失败esp_vfs_spiffs_unregister卸载 SPIFFS 并从 VFS 注销ESP_OK/ESP_ERR_INVALID_STATE未注册esp_spiffs_mounted查询指定分区是否已挂载true/falseesp_spiffs_format格式化 SPIFFS 分区ESP_OK/ESP_FAILesp_spiffs_info获取文件系统总大小与已用字节数ESP_OK/ESP_ERR_INVALID_STATE未挂载esp_spiffs_check检查文件系统完整性并尝试修复ESP_OK/ESP_ERR_INVALID_STATE/ESP_FAILesp_spiffs_gc主动触发垃圾回收保证至少释放指定字节ESP_OK/ESP_ERR_NOT_FINISHED/ESP_ERR_INVALID_STATE/ESP_FAIL其中挂载配置结构体esp_vfs_spiffs_conf_t的四个字段直接决定了挂载行为base_path与该文件系统关联的路径前缀VFS 挂载点partition_label要使用的 SPIFFS 分区标签设为NULL时使用第一个subtypespiffs的分区max_files同一时刻最多能打开的文件数format_if_mount_failed若为true挂载失败时自动格式化文件系统。最小可运行挂载代码以下代码取自 examples/storage/spiffs/main/spiffs_example_main.c展示了标准挂载流程及错误处理esp_vfs_spiffs_conf_t conf { .base_path /spiffs, .partition_label NULL, .max_files 5, .format_if_mount_failed true }; esp_err_t ret esp_vfs_spiffs_register(conf); if (ret ! ESP_OK) { if (ret ESP_FAIL) { ESP_LOGE(TAG, Failed to mount or format filesystem); } else if (ret ESP_ERR_NOT_FOUND) { ESP_LOGE(TAG, Failed to find SPIFFS partition); } else { ESP_LOGE(TAG, Failed to initialize SPIFFS (%s), esp_err_to_name(ret)); } return; }挂载成功后即可用 C 标准库 / POSIX API 操作文件。示例演示了完整读写闭环// 1. 创建并写入文件 FILE* f fopen(/spiffs/hello.txt, w); fprintf(f, Hello World!\n); fclose(f); // 2. 重命名前用 stat 检查目标是否存在存在则 unlink 删除 struct stat st; if (stat(/spiffs/foo.txt, st) 0) { unlink(/spiffs/foo.txt); } // 3. 重命名 rename(/spiffs/hello.txt, /spiffs/foo.txt); // 4. 读取回验 f fopen(/spiffs/foo.txt, r); fgets(line, sizeof(line), f); fclose(f); // 5. 卸载 esp_vfs_spiffs_unregister(conf.partition_label);完整性检查与故障恢复文档明确指出掉电损坏的文件系统仍可能通过esp_spiffs_check恢复。在示例中esp_spiffs_check有两种典型用法启动时主动检查通过CONFIG_EXAMPLE_SPIFFS_CHECK_ON_START开关控制挂载后立即调用esp_spiffs_check验证文件系统完整性一致性异常时触发修复当esp_spiffs_info返回的used total已用字节大于总大小时说明文件系统状态不一致调用esp_spiffs_check修复并可清理未引用页面unreferenced pages。主动垃圾回收esp_spiffs_gc当应用需要一次性腾出较大空间时可调用esp_spiffs_gc(partition_label, size_to_gc)。其核心语义见 esp_spiffs.h 的详细注释是若无法回收请求的空间文件系统中空闲或已删除页面不足返回ESP_ERR_NOT_FINISHED若经过CONFIG_SPIFFS_GC_MAX_RUNS次 GC 迭代仍无法回收所需空间同样返回ESP_ERR_NOT_FINISHED每次 GC 迭代只会擦除一个逻辑块4 kB因此CONFIG_SPIFFS_GC_MAX_RUNS应至少设置为size_to_gc / 4096。例如应用预期腾出 1 MB 空间并调用esp_spiffs_gc(label, 1024 * 1024)则CONFIG_SPIFFS_GC_MAX_RUNS至少应为 256代价是增大CONFIG_SPIFFS_GC_MAX_RUNS会同步增大任意一次 SPIFFS GC 或写操作可能阻塞的最长时间。这正好呼应了文档中GC 每次扫描只释放一个块、写入超过 n × block_size 会失败的约束从 API 层面给出了主动规避手段。SPIFFS 配置项详解menuconfigSPIFFS 的全部可配置项集中在 components/spiffs/Kconfig通过idf.py menuconfig的 SPIFFS Configuration 菜单配置。其中影响镜像兼容性与运行行为的关键项如下配置项默认值范围说明SPIFFS_MAX_PARTITIONS31–10可同时挂载的最大分区数SPIFFS_CACHEy-启用核心文件系统操作的读缓存SPIFFS_CACHE_WRy-启用文件描述符写缓存依赖SPIFFS_CACHESPIFFS_PAGE_CHECKy-访问每个页时始终检查页头以保证状态一致开启会增加 Flash 读取次数禁用缓存时尤其明显SPIFFS_GC_MAX_RUNS101–10000GC 达到目标空闲页的最大运行次数SPIFFS_PAGE_SIZE256256–1024逻辑页大小必须是 Flash 页大小通常 256 字节的整数倍。大页降低大文件存储开销并提升大文件读取性能小页降低小文件小于页大小的存储开销SPIFFS_OBJ_NAME_LEN321–256对象名最大长度包含结尾的\0即文件名最多SPIFFS_OBJ_NAME_LEN - 1个字符。且SPIFFS_OBJ_NAME_LEN SPIFFS_META_LENGTH不应超过SPIFFS_PAGE_SIZE - 64SPIFFS_FOLLOW_SYMLINKSn-创建分区镜像时是否考虑符号链接SPIFFS_USE_MAGICy-启用文件系统魔数挂载时在所有扇区中查找魔数以判断是否为有效 SPIFFSSPIFFS_USE_MAGIC_LENGTHy-魔数同时依赖文件系统长度例如为 4 MB 配置并格式化的文件系统不会被 2 MB 的配置接受挂载SPIFFS_META_LENGTH4-每个文件头额外存储的元数据字节数可应用自定义至少 4 字节才能支持保存文件修改时间SPIFFS_USE_MTIMEy-使用每文件元数据前 4 字节保存 mtime可通过stat/fstat访问文件被打开时更新SPIFFS_MTIME_WIDE_64_BITSn-mtime 字段在镜像中占用 64 位而非 32 位需SPIFFS_META_LENGTH 8。注意若芯片上已有 32 位 mtime 的 SPIFFS 镜像该选项无法直接应用必须先擦除为彻底解决 Y2K38 问题还需使用支持 64 位time_t的工具链SPIFFS_DBG/SPIFFS_API_DBG/SPIFFS_GC_DBG/SPIFFS_CACHE_DBG/SPIFFS_CHECK_DBGn-各类调试信息输出开关Debug Configuration 菜单SPIFFS_USE_MAGIC与SPIFFS_USE_MAGIC_LENGTH尤其重要它们不仅影响挂载时的合法性判定还直接决定spiffsgen.py生成的镜像格式见下文魔数与字节序。工具一spiffsgen.py 生成 SPIFFS 镜像components/spiffs/spiffsgen.py 是一个只写write-only的纯 Python SPIFFS 实现用于从主机文件夹的内容创建文件系统镜像。其优点是无需任何 C/C 编译器即可运行。命令行独立调用在终端中运行python spiffsgen.py image_size base_dir output_file三个必填参数image_size镜像将要烧录到的分区大小字节base_dir需要生成 SPIFFS 镜像的目录output_file输出的 SPIFFS 镜像文件。运行python spiffsgen.py --help可查看全部可选参数。这些可选参数与 SPIFFS 构建配置一一对应要生成正确的镜像必须使用与构建 SPIFFS 时相同的参数/配置help 输出中标明了每个参数对应的 SPIFFS 配置项未指定时使用 help 中显示的默认值。各参数与 Kconfig 的对应关系依据 spiffsgen.py 源码的 CLI 定义spiffsgen.py 参数默认值对应配置项 / 说明--page-size256逻辑页大小取CONFIG_SPIFFS_PAGE_SIZE相同值--block-size4096逻辑块大小与 Flash 芯片扇区大小g_rom_flashchip.sector_size一致--obj-name-len32文件完整路径最大长度取CONFIG_SPIFFS_OBJ_NAME_LEN相同值--meta-len4文件元数据长度取CONFIG_SPIFFS_META_LENGTH相同值--use-magic/--no-magicTrue对应CONFIG_SPIFFS_USE_MAGIC--use-magic-len/--no-magic-lenTrue对应CONFIG_SPIFFS_USE_MAGIC_LENGTH--follow-symlinksFalse创建镜像时考虑符号链接对应CONFIG_SPIFFS_FOLLOW_SYMLINKS--big-endianFalse目标架构是否大端不指定则假定小端--aligned-obj-ix-tablesFalse使用对齐的对象索引表对应SPIFFS_ALIGNED_OBJECT_INDEX_TABLES魔数与字节序镜像兼容性的底层原理spiffsgen.py的SpiffsBuildConfig类spiffsgen.py完整复刻了 SPIFFS 的页/块布局计算包括每块查找页数LU pages、对象索引页表项上限等。其中两个细节对镜像兼容性影响深远魔数magicSpiffsObjLuPage._calc_magic精确复刻spiffs_nucleus.h中SPIFFS_MAGIC宏的计算方式0x20140529 ^ page_size并在use_magic_len开启时再异或(blocks_lim - bix)即魔数随块在镜像中的位置变化。这正是CONFIG_SPIFFS_USE_MAGIC_LENGTH能防止把 4 MB 配置的镜像当 2 MB 挂载的底层原因。对象 ID 高位标志对象索引页在查找页中登记时其obj_id会异或最高位SpiffsObjLuPage.to_binary中obj_id ^ 1 (obj_id_len*8 - 1)用于区分索引页与数据页。如果镜像生成参数与固件编译配置不一致如页大小、魔数开关不匹配挂载时会因魔数校验失败而无法识别文件系统。从构建系统调用spiffs_create_partition_image除命令行独立运行外更推荐在构建系统中直接调用 CMake 函数spiffs_create_partition_image其实现位于 components/spiffs/project_include.cmakespiffs_create_partition_image(partition base_dir [FLASH_IN_PROJECT] [DEPENDS dep dep dep...])相比独立调用这种方式更便捷因为构建配置会自动传递给工具确保生成的镜像对该构建有效。典型示例独立调用必须指定image_size而使用该函数时只需分区名partition—— 镜像大小会自动从项目的分区表中获取。调用约束与可选参数必须在某个组件的CMakeLists.txt中调用FLASH_IN_PROJECT指定后镜像会随应用二进制、分区表等一起在idf.py flash时自动烧录例如spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)若不指定或未设置SPIFFS_IMAGE_FLASH_IN_PROJECT镜像仍会生成但需要你用esptool、parttool.py或自定义构建目标手动烧录DEPENDS当基础目录的内容本身是在构建时生成时用DEPENDS或SPIFFS_IMAGE_DEPENDS指定需要在镜像生成前执行的目标add_custom_target(dep COMMAND ...) spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)从 project_include.cmake 的实现可以看到其内部工作流通过partition_table_get_partition_info读取分区大小与偏移将CONFIG_SPIFFS_USE_MAGIC、CONFIG_SPIFFS_USE_MAGIC_LENGTH、CONFIG_SPIFFS_FOLLOW_SYMLINKS、CONFIG_SPIFFS_PAGE_SIZE、CONFIG_SPIFFS_OBJ_NAME_LEN、CONFIG_SPIFFS_META_LENGTH等配置逐一映射为spiffsgen.py的命令行参数并注册自定义目标spiffs_${partition}_bin。值得注意的是由于 SPIFFS 不支持加密该函数向esp_partition_register_target传递了ALWAYS_PLAINTEXT参数。spiffsgen 示例工程examples/storage/spiffsgen 演示了完整的构建时自动生成镜像流程目录 spiffs_image 是镜像源内容含hello.txt与sub/alice.txtmain/CMakeLists.txt 中调用spiffs_create_partition_image(storage ../spiffs_image FLASH_IN_PROJECT)为storage分区在构建时生成镜像镜像输出到构建目录下的storage.bin执行idf.py -p PORT flash monitor后应用发现storage分区中已存在与spiffs_image目录一致的有效 SPIFFS 文件系统可直接读取文件。示例输出注意used: 171935表明镜像中的文件已被占用空间I (110) example: Partition size: total: 896321, used: 171935 I (110) example: Reading hello.txt I (110) example: Read from hello.txt: Hello World! I (330) example: Computed MD5 hash of alice.txt: deeb71f585cbb3ae5f7976d5127faf2a工具二mkspiffs 生成与烧录镜像mkspiffs是另一款创建 SPIFFS 分区镜像的工具。与spiffsgen.py类似它可以从给定文件夹创建镜像再用esptool烧录。使用前需要获取以下参数Block Size块大小4096SPI Flash 标准值Page Size页大小256SPI Flash 标准值Image Size镜像大小分区大小字节可从分区表获取Partition Offset分区偏移分区起始地址可从分区表获取。将文件夹打包为 1 MB 镜像mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin烧录镜像到目标芯片偏移 0x110000 处esptool --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write-flash -z 0x110000 spiffs.bin若需将 SPIFFS 数据写入外部 SPI Flash 芯片可配置esptool的write-flash命令使用--spi-connection CLK,Q,D,HD,CS选项只需指定分配给外部 Flash 的 GPIO 引脚例如esptool write-flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin如何选择spiffsgen.py 还是 mkspiffs两个工具功能非常相似但各有适用场景。官方文档给出的选择建议如下优先使用spiffsgen.py希望在构建过程中简单地生成 SPIFFS 镜像 ——spiffsgen.py直接通过构建系统提供函数/命令集成非常方便主机上没有 C/C 编译器 ——spiffsgen.py是纯 Python 实现无需编译。优先使用mkspiffs除了生成镜像还需要解包unpackSPIFFS 镜像 —— 目前spiffsgen.py只支持写入不支持解包环境中有主机编译器但没有 Python 解释器或者使用预编译的mkspiffs二进制。不过mkspiffs没有构建系统集成需要自行完成相应工作在构建时编译mkspiffs若不用预编译二进制、为输出文件创建构建规则/目标、向工具传递正确参数等。实操示例storage/spiffs 完整读写闭环examples/storage/spiffs 是使用 SPIFFS 的入门示例完整覆盖文档描述的核心 API 路径。其执行流程用一站式函数esp_vfs_spiffs_register初始化 SPIFFS、挂载文件系统挂载失败时按配置格式化、并注册到 VFS用fopen创建文件、fprintf写入用stat检查重命名目标是否存在存在则unlink删除然后rename打开重命名后的文件fgets读回内容并打印。在format_if_mount_failed true、SPIFFS 未格式化的情况下首次挂载会失败并自动格式化典型输出为I (324) example: Initializing SPIFFS W (324) SPIFFS: mount failed, -10025. formatting... I (19414) example: Partition size: total: 896321, used: 0 I (19504) example: File written I (19544) example: Renaming file I (19584) example: Read from file: Hello World! I (19584) example: SPIFFS unmounted如需彻底擦除 SPIFFS 分区内容重新测试可运行idf.py erase-flash后重新烧录。相关文档分区表配置详解参见 分区表文档用于正确划分 SPIFFS 分区的大小与偏移。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-IDF SPIFFS 文件系统完全指南：从分区挂载到镜像生成与故障恢复
ESP-IDF SPIFFS 文件系统完全指南从分区挂载到镜像生成与故障恢复【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfSPIFFSSPI Flash File System是专为嵌入式 SPI NOR Flash 设计的高可靠性文件系统在 ESP-IDF 中作为官方存储组件提供支持磨损均衡wear levelling与文件系统一致性检查。本文以 docs/en/api-reference/storage/spiffs.rst 为骨架结合 components/spiffs 组件源码与storage/spiffs、storage/spiffsgen两个示例工程完整讲解 SPIFFS 的设计约束、分区配置、esp_spiffs.h高层 API、以及spiffsgen.py与mkspiffs两种镜像生成工具的使用方法帮助你掌握分区 → 挂载 → 读写 → 镜像预生成 → 故障恢复的全链路实践。概述为什么在 ESP32 上选择 SPIFFSSPIFFS 是为嵌入式目标上的 SPI NOR Flash 设备设计的文件系统。它具备两个区别于传统文件系统的核心能力磨损均衡wear levelling均匀分布 Flash 块的擦写次数延长存储介质寿命文件系统一致性检查通过esp_spiffs_check等机制在异常掉电后修复文件系统。在 ESP-IDF 中SPIFFS 通过 VFSVirtual File System层与 C 标准库 / POSIX API 无缝衔接应用代码可以像操作普通文件一样使用fopen、fprintf、rename、stat、unlink等函数参见 examples/storage/spiffs/main/spiffs_example_main.c。使用 SPIFFS 前必须了解的设计约束SPIFFS 的简单与可靠建立在若干明确的设计取舍之上官方文档对此有非常清晰的说明实际选型时必须逐条评估不支持目录只产生扁平结构。如果 SPIFFS 挂载在/spiffs下那么创建路径为/spiffs/tmp/myfile.txt的文件实际会在 SPIFFS 中生成名为/tmp/myfile.txt的文件而不是在/spiffs/tmp目录下创建myfile.txt。不是实时文件系统。一次写操作可能比另一次写操作耗时长得多的多不适合对单次操作延迟有硬性要求的场景。当前版本不检测也不处理坏块bad blocks。SPIFFS 只能可靠利用所分配分区空间的约 75%。分区规划时必须预留余量避免看似空间足够、实际无法写入的窘境。空间耗尽时垃圾回收GC会非常缓慢。当文件系统空间不足时垃圾回收器会多次扫描整个文件系统来寻找空闲空间根据所需空间的大小单次写函数调用可能耗时数秒。这是 SPIFFS 自身设计所致只能通过 SPIFFS 配置项部分缓解见下文GC 与配置项。GC 单次回收能力有限。垃圾回收器每次扫描默认通常为 10 次由SPIFFS_GC_MAX_RUNS配置项控制只能释放一个块block。如果 GC 最大运行次数设为n那么可供数据写入的空间最多为n × block_size若尝试写入的数据超过该上限写入操作可能失败并返回错误。掉电可能导致文件系统损坏。在文件系统操作过程中掉电可能造成 SPIFFS 损坏但通常仍可通过esp_spiffs_check函数恢复详见官方 SPIFFS FAQ。这些约束决定了 SPIFFS 适合数据量可控、以读取为主、小文件居多的存储场景如 Web 静态资源、配置文件而不适合大文件频繁写入或强实时场景。在 ESP-IDF 中启用并挂载 SPIFFS 分区分区表配置首先需要在分区表partition table中为 SPIFFS 划分区域类型为data、子类型为spiffs。参考示例 examples/storage/spiffs/partitions_example.csv 中的写法# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, storage, data, spiffs, 0x110000,0x100000,注意分区大小必须是 SPIFFS 块大小的整数倍spiffsgen.py会校验img_size % block_size 0见 components/spiffs/spiffsgen.py 中的SpiffsFS.__init__。高层 APIesp_spiffs.hSPIFFS 的高层接口全部集中在 components/spiffs/include/esp_spiffs.h共 7 个函数构成了完整的注册-挂载-使用-卸载生命周期函数作用关键返回码esp_vfs_spiffs_register初始化并挂载 SPIFFS同时注册到 VFSESP_OK/ESP_ERR_NO_MEM/ESP_ERR_INVALID_STATE已挂载或分区被加密/ESP_ERR_NOT_FOUND未找到分区/ESP_FAIL挂载或格式化失败esp_vfs_spiffs_unregister卸载 SPIFFS 并从 VFS 注销ESP_OK/ESP_ERR_INVALID_STATE未注册esp_spiffs_mounted查询指定分区是否已挂载true/falseesp_spiffs_format格式化 SPIFFS 分区ESP_OK/ESP_FAILesp_spiffs_info获取文件系统总大小与已用字节数ESP_OK/ESP_ERR_INVALID_STATE未挂载esp_spiffs_check检查文件系统完整性并尝试修复ESP_OK/ESP_ERR_INVALID_STATE/ESP_FAILesp_spiffs_gc主动触发垃圾回收保证至少释放指定字节ESP_OK/ESP_ERR_NOT_FINISHED/ESP_ERR_INVALID_STATE/ESP_FAIL其中挂载配置结构体esp_vfs_spiffs_conf_t的四个字段直接决定了挂载行为base_path与该文件系统关联的路径前缀VFS 挂载点partition_label要使用的 SPIFFS 分区标签设为NULL时使用第一个subtypespiffs的分区max_files同一时刻最多能打开的文件数format_if_mount_failed若为true挂载失败时自动格式化文件系统。最小可运行挂载代码以下代码取自 examples/storage/spiffs/main/spiffs_example_main.c展示了标准挂载流程及错误处理esp_vfs_spiffs_conf_t conf { .base_path /spiffs, .partition_label NULL, .max_files 5, .format_if_mount_failed true }; esp_err_t ret esp_vfs_spiffs_register(conf); if (ret ! ESP_OK) { if (ret ESP_FAIL) { ESP_LOGE(TAG, Failed to mount or format filesystem); } else if (ret ESP_ERR_NOT_FOUND) { ESP_LOGE(TAG, Failed to find SPIFFS partition); } else { ESP_LOGE(TAG, Failed to initialize SPIFFS (%s), esp_err_to_name(ret)); } return; }挂载成功后即可用 C 标准库 / POSIX API 操作文件。示例演示了完整读写闭环// 1. 创建并写入文件 FILE* f fopen(/spiffs/hello.txt, w); fprintf(f, Hello World!\n); fclose(f); // 2. 重命名前用 stat 检查目标是否存在存在则 unlink 删除 struct stat st; if (stat(/spiffs/foo.txt, st) 0) { unlink(/spiffs/foo.txt); } // 3. 重命名 rename(/spiffs/hello.txt, /spiffs/foo.txt); // 4. 读取回验 f fopen(/spiffs/foo.txt, r); fgets(line, sizeof(line), f); fclose(f); // 5. 卸载 esp_vfs_spiffs_unregister(conf.partition_label);完整性检查与故障恢复文档明确指出掉电损坏的文件系统仍可能通过esp_spiffs_check恢复。在示例中esp_spiffs_check有两种典型用法启动时主动检查通过CONFIG_EXAMPLE_SPIFFS_CHECK_ON_START开关控制挂载后立即调用esp_spiffs_check验证文件系统完整性一致性异常时触发修复当esp_spiffs_info返回的used total已用字节大于总大小时说明文件系统状态不一致调用esp_spiffs_check修复并可清理未引用页面unreferenced pages。主动垃圾回收esp_spiffs_gc当应用需要一次性腾出较大空间时可调用esp_spiffs_gc(partition_label, size_to_gc)。其核心语义见 esp_spiffs.h 的详细注释是若无法回收请求的空间文件系统中空闲或已删除页面不足返回ESP_ERR_NOT_FINISHED若经过CONFIG_SPIFFS_GC_MAX_RUNS次 GC 迭代仍无法回收所需空间同样返回ESP_ERR_NOT_FINISHED每次 GC 迭代只会擦除一个逻辑块4 kB因此CONFIG_SPIFFS_GC_MAX_RUNS应至少设置为size_to_gc / 4096。例如应用预期腾出 1 MB 空间并调用esp_spiffs_gc(label, 1024 * 1024)则CONFIG_SPIFFS_GC_MAX_RUNS至少应为 256代价是增大CONFIG_SPIFFS_GC_MAX_RUNS会同步增大任意一次 SPIFFS GC 或写操作可能阻塞的最长时间。这正好呼应了文档中GC 每次扫描只释放一个块、写入超过 n × block_size 会失败的约束从 API 层面给出了主动规避手段。SPIFFS 配置项详解menuconfigSPIFFS 的全部可配置项集中在 components/spiffs/Kconfig通过idf.py menuconfig的 SPIFFS Configuration 菜单配置。其中影响镜像兼容性与运行行为的关键项如下配置项默认值范围说明SPIFFS_MAX_PARTITIONS31–10可同时挂载的最大分区数SPIFFS_CACHEy-启用核心文件系统操作的读缓存SPIFFS_CACHE_WRy-启用文件描述符写缓存依赖SPIFFS_CACHESPIFFS_PAGE_CHECKy-访问每个页时始终检查页头以保证状态一致开启会增加 Flash 读取次数禁用缓存时尤其明显SPIFFS_GC_MAX_RUNS101–10000GC 达到目标空闲页的最大运行次数SPIFFS_PAGE_SIZE256256–1024逻辑页大小必须是 Flash 页大小通常 256 字节的整数倍。大页降低大文件存储开销并提升大文件读取性能小页降低小文件小于页大小的存储开销SPIFFS_OBJ_NAME_LEN321–256对象名最大长度包含结尾的\0即文件名最多SPIFFS_OBJ_NAME_LEN - 1个字符。且SPIFFS_OBJ_NAME_LEN SPIFFS_META_LENGTH不应超过SPIFFS_PAGE_SIZE - 64SPIFFS_FOLLOW_SYMLINKSn-创建分区镜像时是否考虑符号链接SPIFFS_USE_MAGICy-启用文件系统魔数挂载时在所有扇区中查找魔数以判断是否为有效 SPIFFSSPIFFS_USE_MAGIC_LENGTHy-魔数同时依赖文件系统长度例如为 4 MB 配置并格式化的文件系统不会被 2 MB 的配置接受挂载SPIFFS_META_LENGTH4-每个文件头额外存储的元数据字节数可应用自定义至少 4 字节才能支持保存文件修改时间SPIFFS_USE_MTIMEy-使用每文件元数据前 4 字节保存 mtime可通过stat/fstat访问文件被打开时更新SPIFFS_MTIME_WIDE_64_BITSn-mtime 字段在镜像中占用 64 位而非 32 位需SPIFFS_META_LENGTH 8。注意若芯片上已有 32 位 mtime 的 SPIFFS 镜像该选项无法直接应用必须先擦除为彻底解决 Y2K38 问题还需使用支持 64 位time_t的工具链SPIFFS_DBG/SPIFFS_API_DBG/SPIFFS_GC_DBG/SPIFFS_CACHE_DBG/SPIFFS_CHECK_DBGn-各类调试信息输出开关Debug Configuration 菜单SPIFFS_USE_MAGIC与SPIFFS_USE_MAGIC_LENGTH尤其重要它们不仅影响挂载时的合法性判定还直接决定spiffsgen.py生成的镜像格式见下文魔数与字节序。工具一spiffsgen.py 生成 SPIFFS 镜像components/spiffs/spiffsgen.py 是一个只写write-only的纯 Python SPIFFS 实现用于从主机文件夹的内容创建文件系统镜像。其优点是无需任何 C/C 编译器即可运行。命令行独立调用在终端中运行python spiffsgen.py image_size base_dir output_file三个必填参数image_size镜像将要烧录到的分区大小字节base_dir需要生成 SPIFFS 镜像的目录output_file输出的 SPIFFS 镜像文件。运行python spiffsgen.py --help可查看全部可选参数。这些可选参数与 SPIFFS 构建配置一一对应要生成正确的镜像必须使用与构建 SPIFFS 时相同的参数/配置help 输出中标明了每个参数对应的 SPIFFS 配置项未指定时使用 help 中显示的默认值。各参数与 Kconfig 的对应关系依据 spiffsgen.py 源码的 CLI 定义spiffsgen.py 参数默认值对应配置项 / 说明--page-size256逻辑页大小取CONFIG_SPIFFS_PAGE_SIZE相同值--block-size4096逻辑块大小与 Flash 芯片扇区大小g_rom_flashchip.sector_size一致--obj-name-len32文件完整路径最大长度取CONFIG_SPIFFS_OBJ_NAME_LEN相同值--meta-len4文件元数据长度取CONFIG_SPIFFS_META_LENGTH相同值--use-magic/--no-magicTrue对应CONFIG_SPIFFS_USE_MAGIC--use-magic-len/--no-magic-lenTrue对应CONFIG_SPIFFS_USE_MAGIC_LENGTH--follow-symlinksFalse创建镜像时考虑符号链接对应CONFIG_SPIFFS_FOLLOW_SYMLINKS--big-endianFalse目标架构是否大端不指定则假定小端--aligned-obj-ix-tablesFalse使用对齐的对象索引表对应SPIFFS_ALIGNED_OBJECT_INDEX_TABLES魔数与字节序镜像兼容性的底层原理spiffsgen.py的SpiffsBuildConfig类spiffsgen.py完整复刻了 SPIFFS 的页/块布局计算包括每块查找页数LU pages、对象索引页表项上限等。其中两个细节对镜像兼容性影响深远魔数magicSpiffsObjLuPage._calc_magic精确复刻spiffs_nucleus.h中SPIFFS_MAGIC宏的计算方式0x20140529 ^ page_size并在use_magic_len开启时再异或(blocks_lim - bix)即魔数随块在镜像中的位置变化。这正是CONFIG_SPIFFS_USE_MAGIC_LENGTH能防止把 4 MB 配置的镜像当 2 MB 挂载的底层原因。对象 ID 高位标志对象索引页在查找页中登记时其obj_id会异或最高位SpiffsObjLuPage.to_binary中obj_id ^ 1 (obj_id_len*8 - 1)用于区分索引页与数据页。如果镜像生成参数与固件编译配置不一致如页大小、魔数开关不匹配挂载时会因魔数校验失败而无法识别文件系统。从构建系统调用spiffs_create_partition_image除命令行独立运行外更推荐在构建系统中直接调用 CMake 函数spiffs_create_partition_image其实现位于 components/spiffs/project_include.cmakespiffs_create_partition_image(partition base_dir [FLASH_IN_PROJECT] [DEPENDS dep dep dep...])相比独立调用这种方式更便捷因为构建配置会自动传递给工具确保生成的镜像对该构建有效。典型示例独立调用必须指定image_size而使用该函数时只需分区名partition—— 镜像大小会自动从项目的分区表中获取。调用约束与可选参数必须在某个组件的CMakeLists.txt中调用FLASH_IN_PROJECT指定后镜像会随应用二进制、分区表等一起在idf.py flash时自动烧录例如spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)若不指定或未设置SPIFFS_IMAGE_FLASH_IN_PROJECT镜像仍会生成但需要你用esptool、parttool.py或自定义构建目标手动烧录DEPENDS当基础目录的内容本身是在构建时生成时用DEPENDS或SPIFFS_IMAGE_DEPENDS指定需要在镜像生成前执行的目标add_custom_target(dep COMMAND ...) spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)从 project_include.cmake 的实现可以看到其内部工作流通过partition_table_get_partition_info读取分区大小与偏移将CONFIG_SPIFFS_USE_MAGIC、CONFIG_SPIFFS_USE_MAGIC_LENGTH、CONFIG_SPIFFS_FOLLOW_SYMLINKS、CONFIG_SPIFFS_PAGE_SIZE、CONFIG_SPIFFS_OBJ_NAME_LEN、CONFIG_SPIFFS_META_LENGTH等配置逐一映射为spiffsgen.py的命令行参数并注册自定义目标spiffs_${partition}_bin。值得注意的是由于 SPIFFS 不支持加密该函数向esp_partition_register_target传递了ALWAYS_PLAINTEXT参数。spiffsgen 示例工程examples/storage/spiffsgen 演示了完整的构建时自动生成镜像流程目录 spiffs_image 是镜像源内容含hello.txt与sub/alice.txtmain/CMakeLists.txt 中调用spiffs_create_partition_image(storage ../spiffs_image FLASH_IN_PROJECT)为storage分区在构建时生成镜像镜像输出到构建目录下的storage.bin执行idf.py -p PORT flash monitor后应用发现storage分区中已存在与spiffs_image目录一致的有效 SPIFFS 文件系统可直接读取文件。示例输出注意used: 171935表明镜像中的文件已被占用空间I (110) example: Partition size: total: 896321, used: 171935 I (110) example: Reading hello.txt I (110) example: Read from hello.txt: Hello World! I (330) example: Computed MD5 hash of alice.txt: deeb71f585cbb3ae5f7976d5127faf2a工具二mkspiffs 生成与烧录镜像mkspiffs是另一款创建 SPIFFS 分区镜像的工具。与spiffsgen.py类似它可以从给定文件夹创建镜像再用esptool烧录。使用前需要获取以下参数Block Size块大小4096SPI Flash 标准值Page Size页大小256SPI Flash 标准值Image Size镜像大小分区大小字节可从分区表获取Partition Offset分区偏移分区起始地址可从分区表获取。将文件夹打包为 1 MB 镜像mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin烧录镜像到目标芯片偏移 0x110000 处esptool --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write-flash -z 0x110000 spiffs.bin若需将 SPIFFS 数据写入外部 SPI Flash 芯片可配置esptool的write-flash命令使用--spi-connection CLK,Q,D,HD,CS选项只需指定分配给外部 Flash 的 GPIO 引脚例如esptool write-flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin如何选择spiffsgen.py 还是 mkspiffs两个工具功能非常相似但各有适用场景。官方文档给出的选择建议如下优先使用spiffsgen.py希望在构建过程中简单地生成 SPIFFS 镜像 ——spiffsgen.py直接通过构建系统提供函数/命令集成非常方便主机上没有 C/C 编译器 ——spiffsgen.py是纯 Python 实现无需编译。优先使用mkspiffs除了生成镜像还需要解包unpackSPIFFS 镜像 —— 目前spiffsgen.py只支持写入不支持解包环境中有主机编译器但没有 Python 解释器或者使用预编译的mkspiffs二进制。不过mkspiffs没有构建系统集成需要自行完成相应工作在构建时编译mkspiffs若不用预编译二进制、为输出文件创建构建规则/目标、向工具传递正确参数等。实操示例storage/spiffs 完整读写闭环examples/storage/spiffs 是使用 SPIFFS 的入门示例完整覆盖文档描述的核心 API 路径。其执行流程用一站式函数esp_vfs_spiffs_register初始化 SPIFFS、挂载文件系统挂载失败时按配置格式化、并注册到 VFS用fopen创建文件、fprintf写入用stat检查重命名目标是否存在存在则unlink删除然后rename打开重命名后的文件fgets读回内容并打印。在format_if_mount_failed true、SPIFFS 未格式化的情况下首次挂载会失败并自动格式化典型输出为I (324) example: Initializing SPIFFS W (324) SPIFFS: mount failed, -10025. formatting... I (19414) example: Partition size: total: 896321, used: 0 I (19504) example: File written I (19544) example: Renaming file I (19584) example: Read from file: Hello World! I (19584) example: SPIFFS unmounted如需彻底擦除 SPIFFS 分区内容重新测试可运行idf.py erase-flash后重新烧录。相关文档分区表配置详解参见 分区表文档用于正确划分 SPIFFS 分区的大小与偏移。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考