xiaozhi-esp32存储扩展实战指南：从零开始自定义唤醒词分区

2026-03-14 02:44:27作者：邬祺芯Juliet

痛点场景：当唤醒词遇到存储空间瓶颈

"我刚添加了第三个自定义唤醒词，设备就提示存储空间不足了！"这是社区用户@maker_john在项目讨论区的求助帖。类似的问题在开发者中普遍存在——默认4MB Flash配置下，当同时部署"小爱同学"、"你好小智"和"天猫精灵"三个唤醒词模型时，系统会频繁出现SPIFFS full错误。更棘手的是，OTA升级时常常因分区大小限制导致更新失败，严重影响开发效率。

图1：典型的ESP32开发板接线场景，唤醒词模型存储在板载Flash中

核心原理：认识Flash分区的底层逻辑

存储架构图解

xiaozhi-esp32的存储系统采用分层架构，主要包含四个功能区域：

┌─────────────┬─────────────┬─────────────┬─────────────┐
│  NVS存储区  │  OTA数据区  │  唤醒词模型 │  应用程序区  │
│  (配置数据)  │  (更新信息)  │  (SPIFFS)   │  (OTA 0/1)  │
└─────────────┴─────────────┴─────────────┴─────────────┘

MCP协议在存储扩展中扮演关键角色，它通过标准化接口实现设备与云服务的双向通信，其中system.storage.info方法可实时查询分区使用状态：

图2：MCP协议架构示意图，展示存储管理与设备控制的关系

分区方案对比分析

配置文件	总容量	唤醒词分区大小	可存储唤醒词数量	适用场景
partitions/v1/4m.csv	4MB	1MB	2-3个基础模型	入门体验
partitions/v1/8m.csv	8MB	2MB	5-6个标准模型	家庭应用
partitions/v1/16m_custom_wakeword.csv	16MB	4MB	10-12个扩展模型	商业项目
partitions/v1/32m.csv	32MB	8MB	20+个专业模型	企业开发

零基础操作：三步完成存储扩展

准备工作（5分钟）

环境检查：确认设备Flash容量

esptool.py flash_id  # 查看Flash芯片信息，确认容量≥16MB

文件准备：复制分区模板到工作目录

cp partitions/v1/16m_custom_wakeword.csv partitions/custom/advanced.csv

核心操作（10分钟）

修改分区配置 编辑partitions/custom/advanced.csv，调整唤醒词分区大小：

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,    0x4000,
otadata,  data, ota,     0xd000,    0x2000,
phy_init, data, phy,     0xf000,    0x1000,
model,    data, spiffs,  0x10000,   0x7f0000,  # 扩展为8MB唤醒词存储
ota_0,    app,  ota_0,   0x800000,  4M,        # 调整应用区大小
ota_1,    app,  ota_1,   0xc00000,  4M

生成分区资产

python scripts/spiffs_assets/build_all.py \
  --mode custom_wakewords \
  --partition partitions/custom/advanced.csv \
  --output build/assets.bin

操作目的：根据新分区配置打包唤醒词模型
执行效果：在build目录生成包含扩展分区信息的assets.bin

烧录分区表

idf.py -p /dev/ttyUSB0 partition-table-flash  # Linux系统
# 或在Windows系统使用：idf.py -p COM3 partition-table-flash

操作目的：将新分区配置写入设备Flash
执行效果：设备重启后应用新的存储布局

验证方法（3分钟）

查询存储状态：通过MCP协议发送查询命令

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "system.storage.info",
    "arguments": {}
  },
  "id": 1
}

检查返回结果：确认model分区大小变为8MB

{
  "result": {
    "partitions": [
      {"name": "model", "size": 8388608, "used": 1048576}
    ]
  }
}

效率提升：高级扩展技巧

展开查看：自定义超大分区配置

对于需要存储超过8MB模型的专业场景，可通过以下步骤实现：

修改分区文件，将model分区设置为16MB：

model,    data, spiffs,  0x10000,   0xff0000,  # 16MB唤醒词存储

调整SPIFFS配置参数：

# 在sdkconfig.defaults中添加
CONFIG_SPIFFS_MAX_PARTITION_SIZE=0x1000000

重新编译烧录：
```
idf.py fullclean && idf.py build flash
```

常见问题速查

Q1: 如何确认我的设备支持16MB Flash？
A1: 使用esptool.py flash_id命令，若返回Detected flash size: 16MB或更大数值则支持。

Q2: 分区调整后原有唤醒词会丢失吗？
A2: 会。建议在操作前通过tools/backup命令导出模型： json {"method": "tools/call", "params": {"name": "storage.backup", "arguments": {"path": "models/"}}}

Q3: 烧录分区表后设备无法启动怎么办？
A3: 可能是分区大小计算错误，可通过UART恢复模式重新烧录默认分区： bash idf.py -p /dev/ttyUSB0 erase_flash idf.py -p /dev/ttyUSB0 flash