PlatformIO 使用方式与典型场景

四、使用方式与典型场景

示例一：ESP32 与 STM32 共存的工程配置

; platformio.ini
[env]
; 所有环境共享的部分
monitor_speed = 115200
build_flags =
  -D APP_VERSION=\"1.0.0\"
  -Wall
build_unflags = -std=gnu++11
lib_deps =
  bblanchon/ArduinoJson@^7
  ; 版本号写清楚，别用 latest，否则明天构建结果就不一样了

; ---- ESP32 环境：Arduino 框架 ----
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
upload_speed = 921600
monitor_filters =
  esp32_exception_decoder     ; 把崩溃地址翻译成函数名，调试必备
build_flags =
  ${env.build_flags}
  -D BOARD_ESP32=1

; ---- STM32 环境：同样用 Arduino 框架，换板子即可 ----
[env:stm32f407]
platform = ststm32
board = <你的 STM32 板子标识>    ; 用 pio boards ststm32 查准确值
framework = arduino
upload_protocol = stlink
debug_tool = stlink
build_flags =
  ${env.build_flags}
  -D BOARD_STM32=1

; 业务代码里用条件编译区分硬件差异
; #if defined(BOARD_ESP32)
;   ... WiFi 相关 ...
; #elif defined(BOARD_STM32)
;   ... 外设相关 ...
; #endif

要点：${env.build_flags} 这种变量引用是多环境配置的核心写法，公共部分只写一次；monitor_filters 里的异常解码器能把 ESP32 的崩溃地址还原成函数名，省掉手工查表；库版本锁定则保证今天能编译的工程明天还能编译。

示例二：把一个工程接进 CI

# .github/workflows/build.yml 之类流水线的核心步骤（示意）
steps:
  - 拉代码
  - 安装 Python
  - pip install platformio
  - 缓存 PlatformIO 的包与构建缓存目录（加速后续构建）
  - pio run                       # 编译全部环境，任何环境失败即失败
  - pio run -e <env> -t size      # 输出体积报告，可用于卡体积阈值
  - 归档产物（.bin / .hex / .elf）

# 本地等价命令
pio run
pio run -e esp32dev -t size
# 产物位置（各平台略有差异）
ls .pio/build/esp32dev/

CI 的价值在于把「能不能编译」变成每次提交都验证的事。硬件项目常见的情况是「我本地能编译」，原因可能是本地多装了一个库、或者工具链版本不同；用配置文件锁住依赖与平台版本后，这类问题会大幅减少。

适合与不适合的场景

适合：需要同时维护多种芯片平台的项目；希望用一份配置文件复现构建结果的团队；想接 CI 做自动构建与体积检查；喜欢命令行与纯文本配置的工作流。

不适合：对芯片特性需要最前沿支持的项目（厂商自家工具往往先行）；需要深度定制链接脚本与构建流程到极致的情况（原生 CMake 更直接）；完全依赖图形化调试器高级功能（时序分析、实时变量采样）的调试场景；首次拉取工具链网络受限又无法解决的环境。