从零定制：在PlatformIO中为ESP32-S3创建专属开发板配置

关注

原创 2026-03-08 04:11:28 520 阅读 AI 写同款· GEO 优化 ›

使用 PlatformIO 将文件上传到 ESP32-S3 的 SPIFFS 文件系统 PlatformIO 是一个流行的开发平台，用于编写、构建和上传嵌入式项目。ESP32-S3 是 Espressif 推出的一款功能强大的嵌入式开发板，具有丰富的外设和通信接口。本文将介绍如何使用 PlatformIO 将文件上传到 ESP32-S3 的 SPIFFS（SPI Flash File System）文件系统中。阅读详情

1. 为什么我们需要创建专属开发板配置？

如果你玩过ESP32-S3，或者任何一款乐鑫的开发板，大概率在PlatformIO的Board列表里直接搜型号就能找到，点一下就能用，非常方便。但不知道你有没有遇到过这种情况：你买了一块特别小众的模块，或者自己画了一块板子，上面的Flash大小、PSRAM配置、甚至USB模式都和官方开发板不一样。这时候，你在PlatformIO里选哪个板子都觉得不对劲，编译上传后各种奇奇怪怪的问题就来了，比如程序跑着跑着重启了，或者USB CDC端口死活识别不出来。

我最近就踩了这么一个坑。我手头有一块定制的ESP32-S3模组，用的是16MB的Flash，但官方列表里只有4MB和8MB的选项。一开始我偷懒，选了esp32-s3-devkitc-1，然后在platformio.ini里试图用board_build.flash_size = 16MB来覆盖。结果呢？编译是没问题，但程序一上传，运行起来就各种内存错误，调试了半天才发现分区表根本没变，还是用的8MB默认配置，后半截Flash空间完全没用到。这时候我才明白，有些核心参数，尤其是牵扯到链接脚本和分区表的，光在项目配置文件里改是没用的，必须深入到开发板定义文件里去。

所以，“创建专属开发板配置”这件事，本质上就是告诉PlatformIO和背后的编译工具链：“我这块板子长这样，请按我的规矩来办事。” 它不是什么高深莫测的黑魔法，而是一个很实在的工程化需求。特别是当你需要：

定制Flash/PSRAM大小：你的硬件可能用了非标容量。
修改分区方案：你想用更大的OTA分区，或者给文件系统（如LittleFS、SPIFFS）留更多空间。
启用特殊硬件功能：比如你的板子外置了PSRAM，需要特定的初始化代码。
适配不同的核心与变体：虽然都用ESP32-S3，但不同模组可能对应不同的variant（引脚定义文件）。
统一团队开发环境：确保所有成员都用完全相同的板级配置，避免“在我机器上是好的”这种问题。

这个过程就像给你的硬件办一张“身份证”，PlatformIO看到这张身份证，才知道该用什么编译器参数、什么链接脚本、什么上传命令。下面，我就带你从零开始，手把手搞定这张“身份证”。

2. 找到并理解开发板配置的“模板仓库”

第一步，我们得找到PlatformIO存放所有开发板定义的地方。这些文件通常在你系统的用户目录下，PlatformIO安装时会自动克隆一整套下来。以Windows系统为例，路径一般是： C:\Users\<你的用户名>\.platformio\platforms\espressif32\boards

如果你用的是macOS或Linux，路径也类似，在用户主目录下的.platformio文件夹里。打开这个boards文件夹，你会看到一堆.json文件，每个文件都对应PlatformIO支持的一款ESP32系列开发板。这些文件就是我们的“模板库”。

这里有个小技巧，你可以直接在VSCode的终端里用命令快速打开这个目录（以Mac为例）：

open ~/.platformio/platforms/espressif32/boards

面对这么多文件，我们该选哪个作为模板呢？最好的方法是找一个与你目标硬件最接近的官方开发板。对于ESP32-S3，常见的有：

esp32-s3-devkitc-1.json：对应ESP32-S3-DevKitC-1，这是最通用的型号。
esp32-s3-usb-otg.json：如果板子侧重USB功能。
esp32-s3-box.json：对应带屏幕和音频的盒子类开发板。

我建议，如果你不确定，就选esp32-s3-devkitc-1.json，它的配置最为中庸和标准，适合大多数定制场景。选中它，复制一份，准备进行我们的魔改。但在动手前，我们得先看懂这个JSON文件里到底在说些什么。别看它一堆参数，其实结构很清晰，主要分几个大块：

build：这是核心中的核心，定义了编译时的一切。包括芯片型号(mcu)、CPU频率(f_cpu)、Flash频率和模式、额外的编译标志(extra_flags)，以及最重要的——链接脚本(ldscript)和分区表(partitions)。
upload：定义了上传程序时的参数，比如Flash总大小(flash_size)、最大可编程大小(maximum_size)、上传波特率(speed)等。这里的大小必须和build里的分区表匹配，否则会出错。
debug：配置调试工具，通常用默认的esp-builtin就好。
frameworks：支持哪些开发框架，比如Arduino和ESP-IDF。
name和vendor：开发板的显示名称和厂商，这个我们会改成自己的。

理解了这个结构，修改起来就有了地图，不会迷路。

3. 动手修改：打造你的专属配置JSON文件

现在，我们把复制好的esp32-s3-devkitc-1.json重命名，比如叫my_custom_esp32s3_16mb.json。然后用任何文本编辑器（VSCode就行）打开它，开始关键的修改步骤。我会结合一个具体案例来讲解：将一块默认8MB Flash的ESP32-S3开发板，改为支持16MB Flash，并使用自定义分区表。

3.1 修改基础标识信息

首先，找到最顶层的"name"字段。这是你的开发板在PlatformIO下拉列表里显示的名字。把它改成你想要的，比如"My Custom ESP32-S3 (16MB Flash)"。这样在选板子的时候一眼就能认出来。"vendor"可以改成你自己的名字或团队名，比如"My Workshop"。"url"字段可以指向你的硬件文档页面，如果暂时没有，保留原样或删掉都行。

3.2 调整核心编译参数

接下来是重头戏，"build"对象里的内容。

"mcu": 对于ESP32-S3，这个就是"esp32s3"，一般不用动。
"f_cpu"和"f_flash": CPU主频和Flash运行频率。ESP32-S3通常是240MHz和80MHz，除非你的硬件特殊，否则别动。
"flash_mode": Flash的通信模式，比如"qio"（四线SPI）。这需要根据你板子上Flash芯片的硬件连接来确定，常见的是"dio"或"qio"，不确定的话可以参考模组手册。
"hwids": 硬件USB识别ID。这是一个数组，包含了USB厂商ID和产品ID。如果你希望你的板子通过USB连接电脑时有一个独特的名字，可以修改这里。但大多数情况下，特别是为了兼容Arduino的USB CDC串口驱动，我们保持原样不动。随意修改可能导致电脑无法识别出串口。

最关键的修改在"arduino"对象里（如果你主要用Arduino框架）：

"ldscript": 链接脚本文件。它决定了代码、数据在内存中的布局。对于不同的Flash大小，有时需要不同的链接脚本。对于ESP32-S3，常见的是esp32s3_out.ld。对于16MB Flash，我们通常继续使用这个脚本，因为链接脚本本身是通用的，具体内存布局由分区表和编译参数共同决定。除非你有极其特殊的内存布局需求，否则不要改。
"partitions": 这是必须修改的字段！ 它指定了分区表CSV文件的名称。PlatformIO在~/.platformio/packages/framework-arduinoespressif32/tools/partitions目录下预置了很多分区表文件，比如default_8MB.csv、huge_app.csv等。对于16MB Flash，官方没有直接提供default_16MB.csv。所以，你有两个选择：
1. 复制并修改一个现有的：把default_8MB.csv复制一份，重命名为my_custom_16mb.csv，然后修改里面每个分区的大小，确保总和为16MB（1610241024=16777216字节）。例如，把app分区从0x100000（1MB）扩大到0x200000（2MB）。
2. 使用现有的“大容量”分区表：有时你可以直接使用huge_app.csv或no_ota.csv，但需要检查其总大小是否接近16MB。最稳妥的方法是方案一。
假设我们采用了方案一，创建了my_custom_16mb.csv，那么这里就应该改为："partitions": "my_custom_16mb.csv"。
"extra_flags": 额外的GCC编译选项。这里预定义了一些宏，比如-DARDUINO_ESP32S3_DEV。非常重要的一点：如果你修改了Flash大小，特别是增大后，必须在这里添加一个宏定义来告知编译器。对于16MB Flash，你需要添加：-DBOARD_HAS_PSRAM（如果你的板子有PSRAM）和最关键的一个：-DCONFIG_SPIRAM=y？等等，不对，对于Arduino框架，Flash大小的宏通常是-DFLASH_SIZE=16。但更准确地说，ESP32的Arduino核心是通过sdkconfig和boards.txt来管理这些的，直接在这里加宏可能不生效。实际上，对于简单的容量变更，更重要的修改在下一节的upload部分，extra_flags通常保持原样即可，除非你需要启用像PSRAM这样的特定功能，那就加上-DBOARD_HAS_PSRAM。

3.3 配置上传与Flash参数

"upload"对象里的参数直接影响esptool.py上传工具的行为。

"flash_size": 明确写成"16MB"。这告诉上传工具目标Flash的总容量。
"maximum_size": 这是应用程序分区（通常是app0）的最大可烧写大小。这个值必须与你分区表CSV文件中app分区的大小完全一致。如果你在my_custom_16mb.csv里把app分区设为了0x200000（2MB），那么这里就应该是2097152（2MB的字节数）。千万不能错，否则上传时可能会报“尺寸超出”的错误，或者导致OTA失败。
"maximum_ram_size": 最大RAM大小，对于ESP32-S3通常是327680（320KB），这个一般不用改。
"speed": 上传波特率。460800是平衡了速度和稳定性的常用值。如果你的USB转串口芯片很稳定，可以尝试提高到921600来加快上传速度。

3.4 一个完整的修改示例

假设我们基于esp32-s3-devkitc-1.json，创建了一个16MB Flash、使用自定义分区表、并启用了PSRAM的配置。修改后的关键部分可能如下所示：

{
  "build": {
    "arduino": {
      "ldscript": "esp32s3_out.ld",
      "partitions": "my_custom_16mb.csv"
    },
    "core": "esp32",
    "extra_flags": [
      "-DARDUINO_ESP32S3_DEV",
      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_USB_CDC_ON_BOOT=1", // 确保USB CDC在启动时启用
      "-DBOARD_HAS_PSRAM", // 假设板子有PSRAM
      "-mfix-esp32-psram-cache-issue" // 如果启用PSRAM，可能需要这个编译选项
    ],
    "f_cpu": "240000000L",
    "f_flash": "80000000L",
    "flash_mode": "qio",
    "hwids": [
      ["0x303A", "0x1001"]
    ],
    "mcu": "esp32s3",
    "variant": "esp32s3"
  },
  "name": "My Workshop ESP32-S3 16MB+PSRAM",
  "upload": {
    "flash_size": "16MB",
    "maximum_ram_size": 327680,
    "maximum_size": 2097152, // 与分区表中app分区大小匹配
    "require_upload_port": true,
    "speed": 921600
  },
  "vendor": "My Workshop"
  // ... 其他部分如connectivity, debug, frameworks通常保持不变
}

4. 在项目中应用你的自定义开发板

配置文件改好了，怎么用起来呢？有两种主要方式。

方法一：全局放置（推荐用于团队或个人多项目） 将你修改好的my_custom_esp32s3_16mb.json文件，放回最开始的那个boards目录（~/.platformio/platforms/espressif32/boards/）。这样，它就和所有官方板子一样，出现在PlatformIO的板型选择列表里了。重启VSCode或重新加载PlatformIO项目，你就可以在platformio.ini里直接通过名字调用了：

[env:my_custom_board]
platform = espressif32
board = my_custom_esp32s3_16mb  ; 这里就是你的JSON文件名（不带后缀）
framework = arduino
monitor_speed = 115200

方法二：项目内放置（适合单项目或快速测试） 你也可以不污染全局目录，把JSON文件放在你的PlatformIO项目根目录下，比如创建一个boards文件夹放进去。然后在platformio.ini中，使用board_build.ldscript、board_build.partitions等选项来逐个覆盖JSON文件中的设置。但这本质上又回到了最初的问题——对于复杂的定制，你需要覆盖的选项太多，容易遗漏。而方法一是一次定义，处处使用。

验证是否生效：创建或切换到一个使用该板型配置的环境，执行pio run（编译）。在编译输出的开头，PlatformIO会显示它使用的板型信息。更直接的方法是，编译完成后，查看生成的.pio/build/<env-name>/目录下的firmware.elf和分区表文件，确认Flash布局是否符合你的预期。上传程序后，可以在Arduino的setup()里通过Serial.println(ESP.getFlashChipSize());来打印检测到的Flash大小，确认是否是16MB。

5. 进阶：处理分区表与链接脚本的深度定制

有时候，你的定制需求可能更复杂，比如你不仅改了Flash大小，还彻底重新规划了分区结构，或者需要链接脚本把某些函数非常精确地放到IRAM或DRAM的特定位置。这就涉及到对分区表文件和链接脚本本身的修改。

分区表定制：分区表CSV文件是一个纯文本表格。前面提到，你可以从Arduino ESP32框架的包目录里找一个模板复制修改。一个典型的default_8MB.csv开头几行是这样的：

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x6000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 1M,

修改时，你需要确保：

分区之间不能有重叠（Offset + Size <= 下一个分区的Offset）。
第一个分区的Offset通常不是0x0，因为前面有引导程序（bootloader）和分区表本身的位置。
所有分区大小的总和不能超过upload.flash_size。
如果你做OTA，通常会有两个应用程序分区（app0, app1）和一个otadata分区来记录当前OTA状态。

创建好自定义CSV文件后，除了在JSON里指定，还需要确保PlatformIO能找到它。如果放在项目根目录，需要在platformio.ini中指定完整路径：board_build.partitions = my_custom_16mb.csv。如果放在框架的默认目录，则只需写文件名。

链接脚本定制（高级）：链接脚本（.ld文件）控制着代码段（.text）、数据段（.data、.bss）、只读数据段（.rodata）等在内存（IRAM、DRAM、Flash映射地址）中的具体位置。除非你有极特殊的性能优化需求（比如把某个关键函数强制放到IRAM以提升中断响应速度），或者你的硬件有非标准的内存布局，否则强烈不建议新手直接修改链接脚本。Arduino框架提供的默认脚本已经为常见用例做了良好优化。

如果你确实需要，可以到~/.platformio/packages/framework-arduinoespressif32/tools/sdk/esp32s3/ld目录下找到esp32s3_out.ld，复制一份进行修改，并在JSON文件中指向你的新文件。修改链接脚本需要对编译链接过程有较深理解，否则很容易导致程序无法运行。

6. 避坑指南与常见问题排查

自己定制开发板配置的过程不会总是一帆风顺，这里分享几个我踩过的坑和解决办法：

编译通过，但上传失败，提示“Invalid head of packet”或“Failed to connect”：
- 可能原因：upload.speed波特率设置过高，你的USB转串口芯片或线缆质量不稳定。
- 解决：尝试降低波特率，比如从921600降到460800甚至115200。同时检查硬件连接，确保TX/RX线连接正确且牢固。
程序上传成功，但重启后不断崩溃或重启：
- 可能原因A：upload.maximum_size与分区表中app分区大小不匹配。工具试图写入超过分区容量的数据，破坏了分区表或后续分区。
- 解决：仔细核对并修正这两个值，确保完全一致。
- 可能原因B：Flash模式（flash_mode）设置错误。比如你的硬件是dio，但配置成了qio。
- 解决：查阅你的ESP32-S3模组的数据手册，确认正确的Flash模式。
- 可能原因C：extra_flags中缺少关键宏定义，或者partitions指定的文件不存在。
- 解决：检查编译输出日志的最开始部分，看PlatformIO加载了哪些分区表和链接脚本。确保文件路径和名称正确。
自定义板子名称在PlatformIO下拉列表中不显示：
- 可能原因：JSON文件格式错误，或者放错了位置。
- 解决：使用在线的JSON格式验证器检查你的文件是否有语法错误（比如多余的逗号）。确保文件放在正确的boards目录下，并重启了VSCode。
启用PSRAM后程序运行异常：
- 可能原因：ESP32-S3的PSRAM需要特定的初始化代码和缓存处理。
- 解决：除了在extra_flags中添加-DBOARD_HAS_PSRAM，通常还需要添加-mfix-esp32-psram-cache-issue这个编译选项。在Arduino代码中，你可能还需要调用psramInit()函数（对于某些版本的框架）。
如何为同一块硬件创建多个配置（如不同分区方案）？
- 解决：复制多份JSON文件，分别命名，例如my_board_8mb_ota.json和my_board_16mb_no_ota.json。在platformio.ini中创建不同的环境（[env:...]），每个环境指定不同的board值即可。这样可以在一个项目中灵活切换配置。