PlatformIO 安装与部署

二、安装与部署

PlatformIO 有两种使用形态：命令行（Core） 与 编辑器扩展（VSCode 扩展最常用）。无论哪种，核心都是同一套 Core，配置也共用同一份 platformio.ini。建议至少把命令行跑通，这样 CI 与本地行为才一致。

1. 准备 Python。Core 是 Python 程序，需要一个可用的 Python 环境。建议装在独立的虚拟环境里，避免污染系统 Python。
2. 安装 Core。用 pip install platformio 安装，安装完成后 pio --version 能输出版本即成功。
3. （可选）装编辑器扩展。VSCode 里搜索官方 PlatformIO 扩展安装，扩展会自动带上 Core；也可以配置它使用系统已有的 Core。
4. 创建工程。命令行用 pio project init --board <板子标识>，编辑器里用图形向导选板子与框架。
5. 首次构建会下载平台包。这一步会拉取对应平台的工具链与框架，体积较大，国内网络下通常需要配置代理或镜像加速。这是新手最容易卡住的一步。
6. 接线与驱动。ESP32 系列常见串口芯片驱动（CP210x / CH34x）；STM32 用 ST-LINK 要装驱动；确认设备在系统里可见。
7. 编译、烧录、监视。三条命令走完闭环。
8. 多环境与 CI。把 platformio.ini 提交版本管理，CI 里用同一份配置构建，保证本地与流水线一致。

# 1) 安装 Core（建议在虚拟环境里）
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -U pip
pip install platformio
pio --version

# 2) 查询板子标识（不要凭记忆写 board 名）
pio boards ststm32 | head -30
pio boards espressif32 | grep -i devkit

# 3) 建工程
mkdir blink && cd blink
pio project init --board <板子标识> --project-option "framework=arduino"

# 4) 编译 / 烧录 / 串口监视
pio run                                     # 编译
pio run -t upload                           # 编译并烧录
pio device list                             # 列出可用串口
pio device monitor -b 115200                # 打开串口监视（退出：Ctrl + ]）

# 5) 清理与重建
pio run -t clean
pio run -t fullclean                        # 连平台包缓存一起清

# 6) 库管理
pio pkg search "json"                       # 搜索注册表里的库
pio pkg install --library "bblanchon/ArduinoJson"
pio pkg list                                # 列出当前工程已装依赖
pio pkg outdated                            # 检查可升级项

# 7) 单元测试（跑在真板上）
pio test -e <env 名>

依赖与环境要求

• Python：Core 的运行基础，版本要在官方支持范围内。
• 网络：首次使用需要联网拉取平台包与工具链；受限网络要配代理或使用离线包。
• 磁盘：每个平台的工具链几百 MB 级别，多平台共存时占用可观；缓存目录可配置到数据盘。
• 串口驱动：按开发板实际芯片安装。
• USB 权限：Linux 下需要串口与调试器访问权限，建议配置 udev 规则而不是每次 sudo。

常见报错与排查