platformio是vscode中开发arduino、esp32等单片机最实用的环境，通过platformio.ini声明式配置即可切换芯片、框架和版本，避免手动配置工具链与makefile。
PlatformIO 是当前在 VSCode 中写单片机 C 代码最实用、最省心的环境，尤其适合 Arduino、ESP32、STM32（部分型号）、nRF52 等主流平台。它不是“另一个 IDE 插件”，而是把底层工具链（编译器、烧录器、调试器）封装成可声明式配置的工程系统——你改几行 platformio.ini 就能切芯片、换框架、升版本，不用手动调路径、配 c_cpp_properties.json。
为什么不用纯 C/C++ 扩展 + 手动 Makefile？
可以，但容易卡在三个地方：
• arm-none-eabi-gcc 找得到，但 __weak、__packed 这类 CMSIS 关键字标红报错——因为 Microsoft 的 C/C++ 扩展不自动识别芯片专用属性，得手动补 defines 和 includePath，一漏就跳转失效；
• openocd 连不上 SWD：错误信息只显示 Cannot connect to target，但没告诉你到底是接线问题、复位引脚悬空、还是 openocd.cfg 里 adapter speed 设太高；
• 每换一块板子就得重写一遍 Makefile 和 tasks.json，BOARD=STM32F407VE 和 BOARD=STM32G071RB 的启动文件、链接脚本、时钟初始化全不一样，复制粘贴极易出错。
platformio.ini 必须填对的三处参数
这是整个项目的“操作系统内核”，写错直接编译失败或烧录后不运行：
• platform：不是芯片名，是 PlatformIO 官方平台名，比如 ststm32（不是 stm32），espressif32（不是 esp32），atmelavr（不是 arduino）；
• board：必须严格匹配 pio boards --platform ststm32 列出来的 ID，例如 bluepill_f103c8，而不是你买的开发板丝印上的 “STM32F103C8T6”；
• framework：选 arduino 还是 stm32cube 不只是风格问题——前者默认禁用 HAL_Delay() 的 SysTick 初始化，后者要求你手动在 MX_GPIO_Init() 前调 HAL_Init()，否则所有 HAL 函数返回 HAL_ERROR。
第一次编译失败，先查这三件事
别急着重装插件或删 .platformio：
• 运行 pio run -t upload 看完整日志，重点找 *** [.pio/build/xxx/firmware.bin] Error 1 上面那行——大概率是 ld 报 region `FLASH' overflowed（代码超了）或 undefined reference to `main'（src/main.c 没写 int main(void)）；
• 检查 USB 设备管理器里是否识别到串口（Windows 下是 COMx，macOS 是 /dev/cu.usbserial-xxxx），PlatformIO 默认用 upload_port = /dev/cu.usbserial-*，如果设备名不匹配，会静默跳过烧录；
• 确认项目根目录下有且仅有一个 src/ 文件夹，且里面至少有一个 .c 或 .cpp 文件——PlatformIO 不会自动扫描子目录，src/drivers/spi.c 不会被编译，除非你在 platformio.ini 里显式加 src_dir = src:drivers。
真正的麻烦往往不在安装，而在你改了 platformio.ini 后没意识到：同一份代码，在 framework = arduino 下 digitalWrite(2, HIGH) 能点亮 LED，换成 framework = stm32cube 就得先 __HAL_RCC_GPIOA_CLK_ENABLE() 再 HAL_GPIO_WritePin(GPIOA, GPIO_PIN_2, GPIO_PIN_SET)——函数名、初始化逻辑、甚至头文件路径全变了。这不是 PlatformIO 的缺陷，而是它诚实暴露了底层差异。
