vscode装好platformio插件后必须重启才能启用pio命令、显示蚂蚁图标并打开向导；缺python（需3.8–3.11）、cmake或git会导致首次pio run卡在下载工具链；串口监视器默认波特率9600常与代码serial.begin(115200)不匹配，需手动在platformio.ini中配置monitor_speed=115200。
VSCode 装好 PlatformIO 插件 ≠ 能直接编译 ESP32 项目，缺 Python、CMake、Git 中任意一个，首次 pio run 都会卡在“Downloading toolchain”或报 Python not found 错误。
PlatformIO 插件安装后必须重启 VSCode
插件安装完成时 VSCode 只提示“请重启”，但很多人点“稍后提醒”或直接忽略。不重启会导致：pio 命令不可用、左侧蚂蚁图标不响应、新建项目向导打不开。重启不是可选动作，是强制步骤。Windows 用户注意：若安装时没勾选“Add to PATH”，重启后仍可能在终端里执行 pio --version 报“command not found”，此时需手动添加 VSCode 安装目录下的 bin（Windows 是 Code\bin）到系统 PATH，或改用 VSCode 内置终端（它自动继承插件环境）。
Python 版本和路径必须手动验证
PlatformIO 官方明确要求 Python 3.8–3.11（64 位），而 Windows 应用商店默认装的是 3.12+，macOS Homebrew 默认也倾向新版本。装错版本会导致 idf.py submodules 失败、platformio.ini 中 framework = espidf 项目直接编译中断。
- 运行
python --version确认输出形如3.11.9 - 运行
where python（Windows）或which python（macOS/Linux）确认路径指向你装的 3.11 版本，而非系统自带或应用商店版 - 如果已装错，卸载后从 python.org 下载 3.11.9 MSI 安装包，安装时务必勾选
Add Python to PATH
第一次创建项目时下载慢，别乱点取消
点击 New Project → 选完板子和框架后，PlatformIO 会自动拉取整个工具链（含 Xtensa 编译器、ESP-IDF、Arduino-ESP32 core），总大小超 1GB。国内用户常因超时误点取消，结果留下损坏的缓存，再建项目会反复报 Invalid platform archive 或卡在 Extracting...。
- 耐心等至少 10–20 分钟（取决于网络）
- 若实在超时，先删掉
~/.platformio/platforms/espressif32和~/.platformio/packages/toolchain-xtensa-esp32目录（Windows 是%USERPROFILE%\.platformio\...） - 再打开 VSCode 终端，执行
pio platform install espressif32 --with-package toolchain-xtensa-esp32手动重装，该命令支持断点续传
串口监视器默认波特率不对，必须改 platformio.ini
新建项目生成的 platformio.ini 默认不设 monitor_speed，串口监视器（小插头图标）会以 9600 波特率启动，但绝大多数 ESP32 示例代码用的是 Serial.begin(115200)，导致串口输出乱码或无响应。
必须手动在 [env:xxx] 段下加一行：
[env:esp32dev] platform = espressif32 board = esp32dev framework = arduino monitor_speed = 115200
这个值要和代码里 Serial.begin() 的参数严格一致，否则看不到打印。
真正卡住人的地方从来不是“怎么点下一步”，而是 Python 路径没对上、工具链下载一半被中断、串口波特率配错这三处——它们不会报明显错误，只会让整个流程静默失败。
