1. 为什么ESP32编译会内存溢出最近在用VScode的PlatformIO插件开发ESP32项目时遇到了一个让人头疼的问题编译时提示内存不足。明明在Arduino IDE里编译得好好的怎么换到VScode就不行了这个问题困扰了我好几天直到发现是分区表配置的问题。ESP32的内存管理很特别它把闪存分成多个区域程序存储区、文件系统区、OTA升级区等。默认的分区表配置可能不适合你的具体开发板尤其是当你的开发板内存比较小比如4MB版本的时候。PlatformIO默认使用的分区表可能比Arduino IDE的更贪婪占用了太多空间导致你的程序没地方放了。我用的是一块4MB的ESP32 Dev Module开发板。在Arduino IDE里编译时一切正常但移植到VScode后就开始报内存错误。经过一番折腾发现关键在于PlatformIO使用的默认分区表不适合小内存的ESP32开发板。2. 理解ESP32的分区表2.1 分区表是什么想象你的ESP32闪存是一个大房子分区表就是这个房子的户型图。它规定了哪里放程序代码app哪里放文件系统spiffs哪里放OTA升级数据otadata等等。如果户型设计不合理比如客厅太大卧室太小住起来就不舒服了。ESP32的分区表通常是一个CSV文件包含以下几列Name分区名称Type分区类型app, data等SubType子类型Offset起始地址Size分区大小Flags标志位2.2 常见分区类型在ESP32项目中你会经常遇到这些分区类型nvs用于存储键值对数据otadataOTA升级时记录当前使用的固件app存放你的程序代码spiffs文件系统分区对于4MB的ESP32默认配置可能给app分区分配的空间不足这就是导致编译失败的原因。3. 创建自定义分区表3.1 新建分区表文件在你的项目根目录下创建一个CSV文件比如我命名为partition.csv。这个文件将覆盖PlatformIO的默认分区表配置。文件内容大致如下# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x300000, spiffs, data, spiffs, 0x310000, 0xF0000,这个配置适用于4MB的ESP32开发板我给app分区分配了3MB空间spiffs分区分配了约1MB。你可以根据自己项目的实际需求调整这些值。3.2 关键参数说明app分区大小这是存放你程序代码的地方。如果程序比较大就需要增加这个值。我的项目中设置为0x3000003MB比默认值大很多。spiffs分区用于存放网页文件、配置文件等。如果你的项目不需要文件系统可以把这个分区设小一点甚至完全去掉把空间让给app分区。偏移量(Offset)每个分区的起始地址必须正确设置不能重叠。通常保持默认的偏移量即可除非你很清楚自己在做什么。4. 配置PlatformIO使用自定义分区表4.1 修改platformio.ini找到项目中的platformio.ini文件添加以下配置[env:esp32dev] platform espressif32 board esp32dev framework arduino board_build.partitions partition.csv这行board_build.partitions partition.csv告诉PlatformIO使用我们自定义的分区表文件而不是默认的。4.2 验证配置修改完成后尝试重新编译项目。如果一切顺利你应该能看到编译成功的信息。如果还是报内存错误可能需要进一步调整分区表给app分区分配更多空间。我遇到的一个常见错误是忘记在platformio.ini中指定分区表文件或者文件路径写错了。确保你的CSV文件确实在项目根目录下并且文件名拼写正确。5. 针对不同内存ESP32的配置建议5.1 4MB ESP32配置对于4MB的ESP32开发板我推荐以下分区方案nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x300000, spiffs, data, spiffs, 0x310000, 0xF0000,这个配置给程序留出了3MB空间文件系统1MB。如果你的程序特别大可以考虑减少spiffs分区的大小甚至完全去掉它。5.2 8MB及以上ESP32配置如果你用的是8MB或更大内存的ESP32配置起来就轻松多了。下面是一个8MB开发板的示例配置nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x300000, app1, app, ota_1, 0x310000, 0x300000, spiffs, data, spiffs, 0x610000, 0x1F0000,这个配置允许OTA升级有两个app分区并且给文件系统分配了约2MB空间。8MB的ESP32可以更灵活地分配空间不容易出现内存不足的问题。6. 常见问题排查6.1 编译仍然失败怎么办如果按照上述步骤操作后还是编译失败可以尝试以下方法检查分区表文件是否正确加载在编译输出中搜索partition应该能看到PlatformIO加载了你自定义的分区表。增加app分区大小有时候我们低估了程序的实际大小试着把app分区再调大一些。清理项目运行pio run -t clean然后重新编译有时候能解决奇怪的问题。6.2 如何知道程序实际需要多大空间编译完成后PlatformIO会输出各个分区的大小和使用情况。重点关注app分区的使用率理想情况下应该不超过80%。如果接近100%说明你的程序太大了要么优化代码要么给app分区分配更多空间。7. 高级技巧动态调整分区表7.1 根据功能需求调整分区如果你的项目有特殊需求可以进一步优化分区表。比如如果你的项目不需要OTA功能可以去掉otadata分区和一个app分区节省空间。如果使用LittleFS而不是SPIFFS需要修改相应的分区类型。对于纯数据处理项目可以减小spiffs分区增大app分区。7.2 使用PlatformIO的高级配置PlatformIO支持更复杂的分区表配置比如[env:custom_partition] platform espressif32 board esp32dev board_build.partitions partitions_custom.csv build_flags -D CONFIG_PARTITION_TABLE_CUSTOMy -D CONFIG_PARTITION_TABLE_FILENAMEpartitions_custom.csv这种配置方式更灵活适合复杂的项目需求。
PlatformIO中自定义ESP32分区表优化VScode编译内存配置
发布时间：2026/6/6 16:28:59
1. 为什么ESP32编译会内存溢出最近在用VScode的PlatformIO插件开发ESP32项目时遇到了一个让人头疼的问题编译时提示内存不足。明明在Arduino IDE里编译得好好的怎么换到VScode就不行了这个问题困扰了我好几天直到发现是分区表配置的问题。ESP32的内存管理很特别它把闪存分成多个区域程序存储区、文件系统区、OTA升级区等。默认的分区表配置可能不适合你的具体开发板尤其是当你的开发板内存比较小比如4MB版本的时候。PlatformIO默认使用的分区表可能比Arduino IDE的更贪婪占用了太多空间导致你的程序没地方放了。我用的是一块4MB的ESP32 Dev Module开发板。在Arduino IDE里编译时一切正常但移植到VScode后就开始报内存错误。经过一番折腾发现关键在于PlatformIO使用的默认分区表不适合小内存的ESP32开发板。2. 理解ESP32的分区表2.1 分区表是什么想象你的ESP32闪存是一个大房子分区表就是这个房子的户型图。它规定了哪里放程序代码app哪里放文件系统spiffs哪里放OTA升级数据otadata等等。如果户型设计不合理比如客厅太大卧室太小住起来就不舒服了。ESP32的分区表通常是一个CSV文件包含以下几列Name分区名称Type分区类型app, data等SubType子类型Offset起始地址Size分区大小Flags标志位2.2 常见分区类型在ESP32项目中你会经常遇到这些分区类型nvs用于存储键值对数据otadataOTA升级时记录当前使用的固件app存放你的程序代码spiffs文件系统分区对于4MB的ESP32默认配置可能给app分区分配的空间不足这就是导致编译失败的原因。3. 创建自定义分区表3.1 新建分区表文件在你的项目根目录下创建一个CSV文件比如我命名为partition.csv。这个文件将覆盖PlatformIO的默认分区表配置。文件内容大致如下# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x300000, spiffs, data, spiffs, 0x310000, 0xF0000,这个配置适用于4MB的ESP32开发板我给app分区分配了3MB空间spiffs分区分配了约1MB。你可以根据自己项目的实际需求调整这些值。3.2 关键参数说明app分区大小这是存放你程序代码的地方。如果程序比较大就需要增加这个值。我的项目中设置为0x3000003MB比默认值大很多。spiffs分区用于存放网页文件、配置文件等。如果你的项目不需要文件系统可以把这个分区设小一点甚至完全去掉把空间让给app分区。偏移量(Offset)每个分区的起始地址必须正确设置不能重叠。通常保持默认的偏移量即可除非你很清楚自己在做什么。4. 配置PlatformIO使用自定义分区表4.1 修改platformio.ini找到项目中的platformio.ini文件添加以下配置[env:esp32dev] platform espressif32 board esp32dev framework arduino board_build.partitions partition.csv这行board_build.partitions partition.csv告诉PlatformIO使用我们自定义的分区表文件而不是默认的。4.2 验证配置修改完成后尝试重新编译项目。如果一切顺利你应该能看到编译成功的信息。如果还是报内存错误可能需要进一步调整分区表给app分区分配更多空间。我遇到的一个常见错误是忘记在platformio.ini中指定分区表文件或者文件路径写错了。确保你的CSV文件确实在项目根目录下并且文件名拼写正确。5. 针对不同内存ESP32的配置建议5.1 4MB ESP32配置对于4MB的ESP32开发板我推荐以下分区方案nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x300000, spiffs, data, spiffs, 0x310000, 0xF0000,这个配置给程序留出了3MB空间文件系统1MB。如果你的程序特别大可以考虑减少spiffs分区的大小甚至完全去掉它。5.2 8MB及以上ESP32配置如果你用的是8MB或更大内存的ESP32配置起来就轻松多了。下面是一个8MB开发板的示例配置nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x300000, app1, app, ota_1, 0x310000, 0x300000, spiffs, data, spiffs, 0x610000, 0x1F0000,这个配置允许OTA升级有两个app分区并且给文件系统分配了约2MB空间。8MB的ESP32可以更灵活地分配空间不容易出现内存不足的问题。6. 常见问题排查6.1 编译仍然失败怎么办如果按照上述步骤操作后还是编译失败可以尝试以下方法检查分区表文件是否正确加载在编译输出中搜索partition应该能看到PlatformIO加载了你自定义的分区表。增加app分区大小有时候我们低估了程序的实际大小试着把app分区再调大一些。清理项目运行pio run -t clean然后重新编译有时候能解决奇怪的问题。6.2 如何知道程序实际需要多大空间编译完成后PlatformIO会输出各个分区的大小和使用情况。重点关注app分区的使用率理想情况下应该不超过80%。如果接近100%说明你的程序太大了要么优化代码要么给app分区分配更多空间。7. 高级技巧动态调整分区表7.1 根据功能需求调整分区如果你的项目有特殊需求可以进一步优化分区表。比如如果你的项目不需要OTA功能可以去掉otadata分区和一个app分区节省空间。如果使用LittleFS而不是SPIFFS需要修改相应的分区类型。对于纯数据处理项目可以减小spiffs分区增大app分区。7.2 使用PlatformIO的高级配置PlatformIO支持更复杂的分区表配置比如[env:custom_partition] platform espressif32 board esp32dev board_build.partitions partitions_custom.csv build_flags -D CONFIG_PARTITION_TABLE_CUSTOMy -D CONFIG_PARTITION_TABLE_FILENAMEpartitions_custom.csv这种配置方式更灵活适合复杂的项目需求。
