# ESP32PartitionBuilder

**Repository Path**: eegithub/esp32-partition-builder

## Basic Information

- **Project Name**: ESP32PartitionBuilder
- **Description**: Esp32 分区查看和编辑工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32 分区构建器 Web 应用程序

ESP32 Partition Builder 是一个基于浏览器的工具，用于设计 ESP32 分区表 CSV 文件。

Web 应用程序可在此处访问：[ESP32 Partition Builder](https://gitee.com/eegithub/esp32-partition-builder)。

## 教程

[<img src="https://github.com/thelastoutpostworkshop/images/blob/main/Custom%20Partitions.png" width="300">](https://blog.csdn.net/cos12a/article/details/156298530?fromshare=blogdetail&sharetype=blogdetail&sharerId=156298530&sharerefer=PC&sharesource=cos12a&sharefrom=from_link)

<a href="https://esp32.taobao.com" target="_blank">
<img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="购买模块测试">
</a>

## 功能特性

- 从引导预设或单个分区行构建分区表。
- 导入、粘贴、复制和下载 ESP-IDF 分区 CSV 文件。
- 可视化已使用和未使用的闪存空间。
- 配置闪存大小和分区表偏移量。
- 导入 CSV 布局时保留固定偏移量。
- 添加自定义分区行，支持可编辑的类型、子类型、偏移量、大小和标志。
- 使用内置的 ESP-IDF Zigbee 预设，包含 `zb_storage` 和 `zb_fct` 分区。
- 检查 OTA 支持和 NVS 要求。
- 查看常见 ESP32 系列芯片的目标芯片烧录提示。
- 从资源区打开相关 Maker Tools。

## 快速工作流程

1. 为您的开发板选择正确的闪存大小。
2. 选择一个内置分区预设或手动添加分区。
3. 当您希望表格自动对齐分区时，将偏移量留空。
4. 使用可视化工具和可用闪存指示器检查布局。
5. 复制或下载生成的 `partitions.csv`。
6. 在您的 ESP-IDF、Arduino、PlatformIO 或相关 ESP32 构建流程中使用该 CSV。

## CSV 和自定义分区

该应用程序支持 ESP-IDF 分区 CSV 格式：

```csv
# Name,   Type, SubType, Offset,  Size, Flags
nvs,data,nvs,0x9000,0x5000,
factory,app,factory,0x10000,0x100000,
```

偏移量可以是固定的，也可以留空。留空的偏移量将使用所选的分区表偏移量和 ESP-IDF 对齐规则重新计算。

自定义行对于特定框架的布局非常有用，例如 Zigbee、Matter、制造数据、证书或其他供应商定义的分区。自定义行支持可编辑的名称、数字或命名类型、子类型、大小、偏移量以及 `encrypted` 或 `readonly` 等标志。

## Zigbee 分区

对于 ESP-IDF Zigbee 项目，使用 `Zigbee ESP-IDF` 内置预设。它包含所需的 Zigbee 存储分区：

```csv
zb_storage,data,nvs,,16K,
zb_fct,data,fat,,1K,
```

对于 Arduino 或 PlatformIO Zigbee 项目，请确认您使用的框架版本的分区要求。一些较旧的基于 Arduino 的示例将 `zb_storage` 用作 `fat`，而较新的 ESP-IDF Zigbee 指南使用 `nvs`。

## 烧录

该应用程序创建 CSV 分区表，不会烧录开发板。

对于 ESP-IDF 项目，请配置您的项目使用生成的自定义分区 CSV，并让构建系统生成二进制分区表。

对于手动烧录，请先将 CSV 转换为二进制分区表：

```sh
python gen_esp32part.py partitions.csv partition-table.bin
```

目标芯片选择器显示所选 ESP32 系列芯片的预期 `esptool` 命令格式。请确保引导加载程序、分区表和应用程序镜像偏移量与您的项目配置匹配。

## 故障排除

> 不要忘记在 Arduino IDE 或 Visual Studio Code 的 Arduino Workshop 扩展中正确设置开发板选项中的闪存大小。

> 如果您使用 Wi-Fi、BLE 或 Preferences API，NVS 分区是必需的。

如果闪存大小在开发板选项中不可用，您可能需要调整开发板定义中的最大上传大小。IDE 无法读取自定义分区，请参阅此[问题](https://github.com/espressif/arduino-esp32/issues/9831)。

默认情况下，开发板定义中的许多自定义分区的最大上传大小为 16 MB。如果您的开发板的闪存小于 16 MB（例如 4 MB），编译器可能会报告您的草图占用了错误的空间。

要解决此问题，请编辑 Espressif 的 `boards.txt` 文件，该文件通常位于：

```text
[您的驱动器]\[您的用户名]\AppData\Local\Arduino15\packages\esp32\hardware\esp32\[esp32 核心版本]
```

搜索您的特定开发板并更改相应行，例如对于 ESP32S3 Dev Module：

```text
esp32s3.menu.PartitionScheme.custom.upload.maximum_size=16777216
```

改为：

```text
esp32s3.menu.PartitionScheme.custom.upload.maximum_size=4194304
```

适用于具有 4 MB 闪存的微控制器。

> 当 IDE 更新开发板，或您卸载并重新安装它时，您将需要重新进行更改。

### 分区表偏移量 / 大型引导加载程序

使用侧边栏中的 `分区表偏移量` 控件（默认为 0x8000；对于较大的引导加载程序为 0x18000）。当偏移量留空时，应用程序将自动重新对齐分区。请记住在 `sdkconfig` 中使用相同的 `PARTITION_TABLE_OFFSET` 构建引导加载程序和应用程序，并保持该值为 0x1000 的倍数。

## 贡献

欢迎贡献。有关本地设置、测试和发布说明期望，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

本项目根据 [LICENSE](LICENSE) 中的条款进行许可。