ESP32 partitions csv 分区表文件完整讲解

一、核心作用

partitions.csv 是 ESP-IDF 分区表配置文件，用来定义 ESP32 Flash（闪存）的空间如何切分、每个分区名称、类型、子类型、起始地址、大小、标志位。
芯片上电后，bootloader 读取分区表，根据分区地址找到应用程序、数据存储区。

Flash 物理上是一块连续存储空间，分区表就是 Flash 的「分区规划图纸」。

二、文件格式（CSV逗号分隔）

标准列定义（顺序不能乱）：

# Name,   Type, SubType, Offset,  Size, Flags
  1. Name：分区名称（程序内通过名字查找分区）
  2. Type：分区大类
    • app：应用程序分区（存放固件 bin）
    • data：数据分区（nvs、spiffs、fatfs、otadata 等）
  3. SubType：子类型，细分用途
  4. Offset：分区起始地址；留空 → 自动紧跟上一个分区末尾
  5. Size：分区大小，支持 0x十六进制 / 十进制 / KB MB
  6. Flags：标志，常用 encrypted（开启分区加密）

三、常见分区类型说明

1. app 应用分区（固件运行区域）

  • factory：出厂固件分区（单固件方案使用）
  • ota_0、ota_1：OTA A/B 双分区（无线升级必备）

OTA原理：运行 ota_0，新固件下载写入 ota_1，校验成功后切换启动分区。

2. data 数据分区

  • nvs：非易失性存储，保存参数、WiFi账号、配置（最常用）
  • otadata：OTA 分区标记区，记录当前启动哪个 ota 分区
  • phy_init：射频校准参数（WiFi/蓝牙PHY配置，必须保留，不要删除）
  • spiffs：SPI 文件系统，存放网页、静态资源、日志
  • fat：FAT32 文件系统

四、使用vscode ESP-IDF 创建方法

按下“Ctrl+Shift+P”快捷键打开命令面板，并在搜索栏内输入“打开分区表编辑器”，进入分区表编辑器页面
image

我们按下“Add New Row”选项添加子分区条目，然后设置条目的类型、偏移和大小，最后按下“Save”选项保存退出
image 1

五、举一份典型OTA分区示例

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x6000,
otadata,  data, ota,     0xf000,  0x2000,
phy_init, data, phy,     0x11000, 0x1000,
factory,  app,  factory, 0x12000, 1M,
ota_0,    app,  ota_0,   ,        1M,
ota_1,    app,  ota_1,   ,        1M,
spiffs,   data, spiffs,  ,        0x50000,
  • Offset为空：自动连续排布，不用手动计算地址，推荐写法
  • Flash总大小必须大于所有分区总和，否则编译报错

六、开发中常见注意事项

  1. 分区总和不能超过Flash大小
    ESP32常用 4MB Flash，分区总和不能超过4MB；超出会编译报错。
  2. 不能删除 phy_init
    丢失会导致WiFi/蓝牙无法正常工作。
  3. NVS分区大小最小建议 0x3000（12KB），过小容易存不下参数。
  4. 使用文件系统(spiffs/fat)时，分区大小必须符合文件系统对齐要求。
  5. OTA项目必须配套 otadata 分区，否则无法切换OTA分区。
  6. 修改分区表后：最好全片擦除Flash再下载，旧分区残留数据容易引发异常。