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

PlatformIO 基础配置文件 platformio.ini 详解 | 极客日志

配置文件结构：核心配置 + 环境配置

配置结构

platformio.ini 采用 INI 格式，由多个 环境（Environment） 组成，每个环境用 [env:名称] 标识。

[platformio] ; 核心配置
[env:my_board] ; 特定环境配置

配置区块	作用范围	典型用途
`[platformio]`	整个项目	目录结构、默认环境、额外配置
`[env:xxx]`	单个编译环境	平台、板型、库依赖、编译标志

多环境支持

一个项目可定义多个编译目标：

[env:esp32_dev]
board = esp32dev
build_flags = -D DEBUG=1

[env:esp32_prod]
board = esp32dev
build_flags = -D RELEASE=1

[env:esp32_ota]
board = esp32dev
extra_scripts = pre:ota_script.py

使用方式：

pio run -e esp32_dev # 编译开发环境
pio run -e esp32_prod # 编译生产环境
pio run # 编译所有环境

核心配置项：[platformio]

全局配置 [platformio] 是项目的'总开关'，合理设置可以简化多环境管理和项目结构组织。

配置项	说明	示例
`default_envs`	默认编译环境（逗号分隔，不指定编译所有环境）	`default_envs = esp32, stm32`
`extra_configs`	额外配置文件	`extra_configs = variants/*/platformio.ini`
`data_dir`	数据文件目录	`data_dir = my_data`
`lib_dir`	项目库目录	`lib_dir = my_libs`
`src_dir`	源代码目录	`src_dir = my_src`
`include_dir`	头文件目录	`include_dir = my_include`
`test_dir`	测试代码目录	`test_dir = my_tests`
`boards_dir`	自定义开发板目录	`boards_dir = my_boards`

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

环境配置

平台与框架

配置项	说明	示例
`platform`	目标硬件平台	`espressif32`, `ststm32`, `nordicnrf52`
`framework`	开发框架	`arduino`, `espidf`, `mbed`, `zephyr`
`board`	具体开发板型号	`esp32dev`, `bluepill_f103c8`

┌─────────────────────────────────────────────────────────┐
│ 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

说明	详情
定义	指定目标硬件的底层平台
作用	决定使用哪个工具链、编译器、调试器、上传协议等
来源	PlatformIO Registry 或 GitHub 仓库

组件	说明
工具链	编译器 (gcc/clang)、链接器、汇编器
调试器	OpenOCD、J-Link、ST-Link 等支持
上传协议	esptool、stlink、jlink、picotool 等
SDK/框架	平台特定的 SDK 和框架支持
板级定义	预定义的开发板配置 (引脚、内存、时钟等)

常见平台列表：

平台名称	平台标识	适用芯片/系列	官方文档
Espressif 32-bit	`espressif32`	ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6	链接
Espressif 8266	`espressif8266`	ESP8266	链接
ST STM32	`ststm32`	STM32 F0/F1/F3/F4/F7/G0/G4/H7/L0/L1/L4/L5/U5 等	链接
Nordic nRF52	`nordicnrf52`	nRF52832, nRF52840, nRF52810 等	链接
Raspberry Pi RP2040	`raspberrypi`	RP2040 (Pico, Pico W)	链接
Atmel AVR	`atmelavr`	ATmega328P (Uno/Nano), ATmega2560 (Mega)	链接
Atmel SAM	`atmelsam`	SAMD21 (Zero), SAMD51 (M4)	链接
ESP32 Arduino (社区)	`https://github.com/pioarduino/...`	ESP32 Arduino 3.x	社区维护

framework - 开发框架

framework = arduino

说明	详情
定义	指定使用的软件开发框架/SDK
作用	决定可用的 API、库、编程模型
依赖	必须在 `platform` 支持的框架中选择

平台与框架的兼容关系

Platform	支持的 Framework
`espressif32`	`arduino`, `espidf`
`espressif8266`	`arduino`
`ststm32`	`arduino`, `mbed`, `zephyr`, `libopencm3`
`nordicnrf52`	`arduino`, `mbed`, `zephyr`
`raspberrypi`	`arduino`, `baremetal`
`atmelavr`	`arduino`
`atmelsam`	`arduino`, `mbed`

对比项	Arduino	ESP-IDF
代码结构	`setup()` + `loop()`	`app_main()`
编译体积	较大	较小
启动时间	较慢	较快
可用库	丰富	相对较少
调试支持	基础	完整

board - 具体开发板型号

board = esp32dev

说明	详情
定义	指定具体的开发板型号
作用	决定引脚定义、内存大小、时钟频率、外设配置等
来源	PlatformIO 板级数据库

板级定义内容：每个 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"

板名	芯片	闪存	PSRAM	说明
`esp32dev`	ESP32	4MB	可选	通用开发板
`esp32s3dev`	ESP32-S3	4MB	可选	带 AI 指令集
`esp32c3dev`	ESP32-C3	4MB	无	RISC-V 核心
`esp32c6dev`	ESP32-C6	4MB	无	支持 WiFi 6
`nodemcu-32s`	ESP32	4MB	有	NodeMCU 风格
`wemos_d1_mini32`	ESP32	4MB	有	Wemos D1 Mini 32

板名	芯片	闪存	RAM	说明
`bluepill_f103c8`	STM32F103C8	64KB	20KB	经典 Blue Pill
`blackpill_f103c8`	STM32F103C8	64KB	20KB	Black Pill
`nucleo_f401re`	STM32F401RE	512KB	96KB	Nucleo 开发板
`nucleo_f767zi`	STM32F767ZI	2MB	512KB	高性能 Nucleo

板名	芯片	闪存	RAM	说明
`nrf52832_mdk`	nRF52832	512KB	64KB	MakerDiary
`nrf52840_mdk`	nRF52840	1MB	256KB	带 USB
`nrf52_dk`	nRF52832	512KB	64KB	官方 DK

板名	芯片	闪存	RAM	说明
`rpipico`	RP2040	2MB	264KB	Raspberry Pi Pico
`rpipicow`	RP2040	2MB	264KB	Pico W (带 WiFi)
`waveshare_rp2040_zero`	RP2040	2MB	264KB	微缩版

完整配置示例

示例 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 DEBUG=1 -w`
`build_src_filter`	源文件过滤	`+<*.cpp> -<exclude/>`
`build_unflags`	移除默认标志	`-std=gnu++11`

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

库依赖管理

配置项	说明
`lib_deps`	项目依赖库
`lib_ignore`	忽略的库
`lib_ldf_mode`	库依赖查找模式

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

上传与监控

配置项	说明	示例
`upload_protocol`	上传协议	`esptool`, `stlink`, `picotool`
`upload_port`	上传端口	`COM3`, `/dev/ttyUSB0`
`upload_speed`	上传波特率	`921600`
`monitor_speed`	串口监控波特率	`115200`
`monitor_filters`	监控过滤器	`esp32_exception_decoder`

配置继承 (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

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

配置文件结构：核心配置 + 环境配置

配置结构

多环境支持

核心配置项：[platformio]

default_envs - 默认环境

extra_configs - 额外配置文件

目录结构自定义

环境配置

平台与框架

platform - 目标硬件平台

framework - 开发框架

board - 具体开发板型号

完整配置示例

构建选项

库依赖管理

上传与监控

配置继承 (extends)

变量与表达式

自定义脚本

常用命令

完整示例

参考资料

更多推荐文章

相关免费在线工具

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

配置文件结构：核心配置 + 环境配置

配置结构

多环境支持

核心配置项：[platformio]

default_envs - 默认环境

extra_configs - 额外配置文件

目录结构自定义

环境配置

平台与框架

platform - 目标硬件平台

framework - 开发框架

board - 具体开发板型号

完整配置示例

构建选项

库依赖管理

上传与监控

配置继承 (extends)

变量与表达式

自定义脚本

常用命令

完整示例

参考资料

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具