vscode需依赖独立安装的arduino-cli实现arduino开发，必须正确配置path并安装对应core，否则插件报错、板型不识别、串口监视器失效或库引用失败。
VSCode 本身不支持 Arduino 开发，必须靠 arduino-cli 提供底层编译与烧录能力，再由官方 Arduino 插件桥接操作。跳过 CLI 安装或路径配错，插件会直接报 “arduino-cli not found”，后续所有步骤都无效。
arduino-cli 必须独立安装且 PATH 可达
插件不自带编译器，也不复用 Arduino IDE 的工具链——它只调用系统 PATH 下的 arduino-cli 可执行文件。
- macOS：推荐用
brew install arduino-cli；若手动下载二进制，务必chmod +x并放到/usr/local/bin/，否则 VSCode 找不到 - Windows：安装 Arduino IDE 时必须勾选 “Add arduino-cli to system PATH”，没勾就重装；别试图手动把
arduino-cli.exe路径加进系统变量——插件对反斜杠\和大小写敏感，极易失败 - Linux：用
which arduino-cli确认路径，然后在 VSCode 设置里搜arduino.path，填绝对路径（如/home/xxx/.arduino15/arduino-cli），不能带符号链接 - 验证是否成功：终端运行
arduino-cli version有输出才算过关；没输出就别往下走
板型识别失败？先确认 core 是否已安装
VSCode 插件不会自动下载开发板支持包。选板型时看到空白、只有 arduino:avr:uno 或压根没你的 ESP32/RP2040，说明对应 core 没装。
- 运行
arduino-cli core update-index同步最新板卡索引 - 装 AVR 板（Uno/Nano）：
arduino-cli core install arduino:avr - 装 ESP32：
arduino-cli core install esp32:esp32 - 装 RP2040（Pico）：
arduino-cli core install raspberry-silicon:rp2040 - 装完后必须重启 VSCode，否则新板型不会出现在
Arduino: Board Config列表里
串口监视器乱码或连不上，问题大概率不在波特率
9600 波特率下 Serial.print() 出乱码，第一反应是调监视器波特率——但更常踩的坑是插件上传后自动断开串口，导致内置监视器连不上设备。
- 先用 Arduino IDE 打开串口监视器，确认硬件和接线没问题
- VSCode 内置的“插头图标”监视器不可靠；改用终端命令：
arduino-cli monitor -p /dev/ttyUSB0 -b 9600（Linux/macOS）或arduino-cli monitor -p COM3 -b 9600（Windows） - 如果仍乱码，检查 USB 转串口芯片：CH340 在 macOS 14+ 上高波特率（115200）易丢数据，降回 19200 或 9600 更稳
- 拔插设备后，VSCode 不会自动刷新串口列表；必须手动执行
Arduino: Select Serial Port重新选一次
第三方库报 “no such file or directory”，不是路径放错就是安装方式不对
插件不读取 Arduino IDE 的 libraries 文件夹，也不识别 ZIP 解压到项目里的随意命名目录。
- 全局安装最稳妥：
arduino-cli lib install "Adafruit NeoPixel"，之后新建项目就能直接#include <adafruit_neopixel.h></adafruit_neopixel.h> - 若需本地引用，必须把库文件夹（名必须是
Afafruit_NeoPixel，不能简写成neopixel）放在项目根目录同级的libraries文件夹里（即和项目文件夹平级，不是项目内部） - 库文件夹内必须含
library.properties或keywords.txt，否则插件认为它不符合 Arduino Library Specification，直接忽略 - 中文路径会导致编译失败，整个工作区路径、Arduino IDE 安装路径、库路径，全部必须是纯英文
最常被忽略的一点：每次更换开发板型号或串口后，右下角状态栏显示的板型和端口必须和实际一致；灰色或空缺状态代表配置未生效，此时上传必然失败——不要跳过这一步肉眼确认。
