核心问题是arduino-cli是否可用、板型是否注册、串口是否被正确识别，三者缺一不可；需确保CLI在PATH中且能响应version命令，板型标识精确匹配，串口手动选择并避免占用。
VSCode 用 Arduino 插件上传固件，核心问题不在插件本身，而在 arduino-cli 是否可用、板型是否注册、串口是否被正确识别——三者缺一不可，否则上传必然失败。
arduino-cli 必须在 PATH 中且能响应 version 命令
VSCode 的 Arduino 插件（Microsoft 官方版）不自带编译器，完全依赖系统 PATH 中的 arduino-cli 可执行文件。它不是调用图形 IDE 后台服务，而是直接 shell 调用 CLI 工具链。
- Windows：解压下载的
arduino-cli_*.zip后，把arduino-cli.exe所在目录加进系统环境变量PATH；验证方式：终端运行arduino-cli version应输出类似0.42.2 - macOS/Linux：推荐用
brew install arduino-cli（macOS）或手动放入/usr/local/bin/并chmod +x；避免用 GitHub release 下载后直接扔进~/Downloads就完事——插件根本找不到 - 首次运行必须初始化：
arduino-cli config init，否则插件读不到板型索引和库路径，后续Arduino: Board Config会为空或报错
板型必须显式安装并完整匹配标识符
插件下拉菜单里显示的 “Arduino Uno” 实际对应的是平台+架构+型号三段式标识，比如 arduino:avr:uno。只搜 “uno” 很容易选错，尤其 ESP32 或 RP2040 类板子默认不带。
- ESP32 板子需先运行：
arduino-cli core install esp32:esp32，再重启 VSCode，Arduino: Board Config才会出现 “ESP32 Dev Module” 等选项 - Arduino Nano Every 属于
megaavr架构，对应标识是arduino:megaavr:nona4809，不是arduino:avr:nano—— 选错会导致编译通过但 upload 后板子无反应 - 某些国产兼容板（如 CH340 芯片 Nano）需额外安装驱动，macOS 上还要执行
sudo kextunload /Library/Extensions/usbserial.kext（旧系统）或允许内核扩展（Sequoia）
串口选择不是“自动检测”，必须手动触发且注意权限
VSCode 插件不会像 Arduino IDE 那样后台轮询串口设备。拔插 USB 后，必须主动执行 Arduino: Select Serial Port，否则状态栏仍显示旧端口或 “No serial port available”。
- Windows 端口名形如
COM3；macOS 是/dev/cu.usbserial-XXXX（不是tty.开头，后者常被系统占用）；Linux 多为/dev/ttyUSB0或/dev/ttyACM0 - macOS Sequoia 默认禁止非签名驱动访问串口，若
ls /dev/cu.*有输出但插件选不到，需去「系统设置 → 隐私与安全性 → 完全磁盘访问」中给 VSCode 授权 - 上传前务必关闭串口监视器（包括 Arduino IDE 自带的、或者 VSCode 内置的 Terminal 中正在运行的
screen/minicom），否则upload会卡在 “Opening port…”
上传失败时最该看的不是错误弹窗，而是输出面板的 CLI 日志
插件 UI 报错往往模糊（如 “Upload failed”），真正线索藏在 VSCode 底部的 OUTPUT 面板 → 切换到 Arduino 标签页，里面是原始 arduino-cli upload 命令输出。
- 出现
Permission denied on /dev/cu.usbmodem...：说明串口被占或权限不足，不是板子问题 - 出现
Failed to connect to ESP32: Timed out waiting for packet header：大概率是 USB 线仅充电、没数据线功能，或 ESP32 没按住 BOOT 再按 RST 进入下载模式（部分型号需要） - 出现
Board arduino:avr:uno not found：说明arduino-cli core list未返回该板型，需重装 core 或检查arduino-cli.yaml中的board_manager配置
真正卡点往往不在代码写得对不对，而在于 CLI 工具链是否就位、硬件抽象层是否加载、操作系统是否放行——这些底层细节一旦出错，上传按钮就只是个摆设。
