platformio项目不识别platformio.ini是因文件缺失或位置错误，必须置于项目根目录且命名严格为platformio.ini；烧录权限错误需将用户加入dialout/uucp组并重启；upload_port须用pio device list确认后显式填写。
PlatformIO插件装了但项目不识别 platformio.ini
VSCode 安装了 PlatformIO 插件后，打开已有嵌入式项目却看不到“PLATFORMIO”侧边栏，或终端里执行 pio run 报错找不到配置文件——大概率是项目根目录下缺少合法的 platformio.ini，或者文件名/位置不对。
-
platformio.ini必须放在项目最外层目录（即 VSCode 打开的文件夹根目录），不能在src/或config/子目录里 - 文件名必须严格为
platformio.ini，不是platformio.conf、pio.ini或大小写变体（Windows 有时不敏感，Linux/macOS 会直接失败） - 如果项目是从 Git 克隆的，检查是否漏掉了该文件（有些仓库把它加进了
.gitignore） - 首次创建项目建议用
pio project init命令生成，比手动新建更可靠
烧录时提示 Permission denied: '/dev/ttyUSB0'（Linux/macOS）
连接开发板后，VSCode 点击“Upload”报权限错误，本质是当前用户没被加入串口设备所属的用户组，和 PlatformIO 本身无关。
- 运行
ls -l /dev/ttyUSB*查看设备属组（常见为dialout或uucp） - 执行
sudo usermod -a -G dialout $USER（Ubuntu/Debian）或sudo usermod -a -G uucp $USER（Arch/macOS via Homebrew + serial drivers） - **必须重启终端或重新登录系统**，组权限不会热更新
- 若用 Docker 或 WSL2，串口设备默认不可见，需额外配置设备透传，这不是 PlatformIO 能解决的问题
platformio.ini 中 upload_port 怎么填才不报错
烧录失败常卡在“Connecting to programmer…”阶段，90% 是因为 upload_port 配置错误。PlatformIO 不会自动猜端口，尤其多设备插入时。
- 先拔掉所有其他 USB 设备，只留目标开发板，运行
pio device list查真实端口号（如/dev/ttyACM0或COM3） - 在
platformio.ini中显式写死，例如：upload_port = /dev/ttyACM0；不要留空、不要写成upload_port = auto（该值无效） - STM32（尤其是带 ST-Link 的板子）可能走
upload_protocol = stlink，这时upload_port可省略，但必须确认platform_packages包含tool-stm32duino或对应调试工具 - ESP32 使用 CP2102/CH340 芯片时，驱动未安装会导致端口根本不出现在
pio device list输出中
上传成功但板子没反应：时钟、Boot 引脚、供电问题更常见
VSCode 底部状态栏显示 “Success! Uploaded in 2.3s”，但 LED 不闪、串口无输出——这时候 PlatformIO 已完成烧录动作，问题出在硬件或启动配置上。
- 检查
board_build.f_cpu是否匹配实际晶振频率（比如把 8MHz 板子配成 16MHz，程序跑飞） - 某些 STM32 板需要手动拉低
BOOT0引脚才能进系统存储器启动模式，烧录完再拉高才能运行新固件 - 用万用表量
VCC/GND间电压，很多“烧录成功但不工作”其实是 USB 线供电不足，尤其接了 OLED 或电机模块后 - 串口监视器波特率必须和代码中
Serial.begin(115200)一致；PlatformIO 默认监视器波特率是 9600，得在platformio.ini加monitor_speed = 115200
platformio.ini 少个等号更难排查。
