PlatformIO 基础配置文件 platformio.ini 详解

default_envs - 默认环境

• 指定运行 pio run 时默认编译的环境，无需 -e 参数。

[platformio]
default_envs = esp32_prod

[env:esp32_dev]
; ...

[env:esp32_prod]
; ...

extra_configs - 额外配置文件

引入其他配置文件，支持通配符，便于模块化配置。

[platformio]
extra_configs = variants/*/platformio.ini
secrets.ini ; 敏感信息单独存放

目录结构自定义

• 默认目录结构：

project/
├── src/ # 源代码
├── lib/ # 项目库
├── include/ # 头文件
├── data/ # 文件系统数据
├── test/ # 测试代码
├── boards/ # 自定义开发板定义
└── platformio.ini

可通过全局配置修改：

[platformio]
src_dir = firmware/src
lib_dir = firmware/lib
include_dir = firmware/include
data_dir = firmware/data

环境配置

平台与框架

┌─────────────────────────────────────────────────────────┐
│ PlatformIO 项目                                         │
└─────────────────────────────────────────────────────────┘
│ ▼
┌─────────────────────────────────────────────────────────┐
│ platform (平台)                                         │
│ └─ 决定：工具链、编译器、调试器、上传协议               │
│ └─ 示例：espressif32, ststm32, nordicnrf52              │
└─────────────────────────────────────────────────────────┘
│ ▼
┌─────────────────────────────────────────────────────────┐
│ framework (框架)                                        │
│ └─ 决定：API、库、编程模型                              │
│ └─ 示例：arduino, espidf, mbed, zephyr                  │
│ └─ 必须是 platform 支持的框架                           │
└─────────────────────────────────────────────────────────┘
│ ▼
┌─────────────────────────────────────────────────────────┐
│ board (开发板)                                          │
│ └─ 决定：引脚、内存、时钟、外设配置                     │
│ └─ 示例：esp32dev, bluepill_f103c8, rpipico             │
│ └─ 必须与 platform 兼容                                 │
└─────────────────────────────────────────────────────────┘

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino

platform - 目标硬件平台

; 方式 1: 使用最新稳定版
platform = espressif32
; 方式 2: 指定具体版本
platform = espressif32@6.11.0
; 方式 3: 使用 GitHub 仓库
platform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.12/platform-espressif32.zip
; 方式 4: 使用开发版
platform = https://github.com/platformio/platform-espressif32.git

• 常见平台列表：

framework - 开发框架

framework = arduino

• 平台与框架的兼容关系

board - 具体开发板型号

board = esp32dev

• 板级定义内容：每个 board 在 PlatformIO 中对应一个 JSON 文件，包含：

{"build":{"core":"arduino","extra_flags":"-D ARDUINO_ESP32_DEV","f_cpu":"240000000L","mcu":"esp32","variant":"esp32"},"connectivity":["wifi","bluetooth"],"debug":{"tool":"esp-prog"},"frameworks":["arduino","espidf"],"name":"Espressif ESP32 Dev Module","platform":"espressif32","upload":{"flash_size":"4MB","maximum_ram_size":327680,"maximum_size":4194304,"protocol":"esptool"},"url":"https://espressif.com","vendor":"Espressif"}

完整配置示例

• 示例 1: ESP32 + Arduino

[env:esp32]
platform = espressif32@6.11.0
framework = arduino
board = esp32dev
monitor_speed = 115200

• 示例 2: STM32 + Arduino

[env:stm32]
platform = ststm32@19.1.0
framework = arduino
board = bluepill_f103c8
upload_protocol = stlink

• 示例 3: NRF52 + Arduino

[env:nrf52]
platform = nordicnrf52
framework = arduino
board = nrf52840_mdk

• 示例 4: RP2040 + Arduino

[env:rp2040]
platform = raspberrypi
framework = arduino
board = rpipico
upload_protocol = picotool

• 示例 5: ESP32 + ESP-IDF

[env:esp32_idf]
platform = espressif32
framework = espidf
board = esp32dev

构建选项

build_flags = -D VERSION=1.0 -w ; 禁用警告
-D LORA_FREQ=868.0

库依赖管理

lib_deps = SPI Wire adafruit/Adafruit_BME280 @ ^2.3.0
https://github.com/user/repo.git
file://local/library

上传与监控

配置继承 (extends)

• 可以定义基础配置模板如 base_config，其他环境继承它，避免重复：

[base_config]
framework = arduino
monitor_speed = 115200
lib_deps = SPI, Wire

[env:esp32]
extends = base_config
platform = espressif32
board = esp32dev

[env:stm32]
extends = base_config
platform = ststm32
board = bluepill_f103c8

变量与表达式

[common]
build_flags = -D MY_VAR=1

[env:esp32]
build_flags = ${common.build_flags} -D EXTRA=1

自定义脚本

extra_scripts = pre:build_script.py # 编译前执行
post:build_script.py # 编译后执行

常用命令

pio init # 初始化项目
pio run # 编译所有环境
pio run -e env_name # 编译指定环境
pio run -t upload # 编译并上传
pio run -t clean # 清理构建文件
pio device list # 列出可用串口
pio device monitor # 打开串口监视器
pio lib install # 安装依赖库
pio lib update # 更新依赖库

完整示例

; PlatformIO 项目配置示例
[platformio]
default_envs = esp32

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_speed = 921600
lib_deps = SPI Wire adafruit/Adafruit_BME280 @ ^2.3.0
build_flags = -w -D DEBUG=1 -D LORA_FREQ=868.0

参考资料

• 配置详解：https://docs.platformio.org/page/projectconf.html
• 平台列表：https://platformio.org/platforms
• 库搜索：https://platformio.org/lib/search