vscode 依赖 arduino-cli 实现编译、上传与串口通信，插件仅为界面层；未安装 cli 或路径配置错误将导致 upload 按钮灰显、arduino.h 找不到、板型不识别等全链路失败，必须手动配置 arduino.path、安装对应 core、授权串口权限并补全 c/c++ 头文件路径。
VSCode 本身不带 Arduino 编译能力，所有烧录、验证、串口通信都依赖 arduino-cli；插件只是界面层，没装 CLI 或路径错，后续全卡死。
arduino-cli 没被 VSCode 真正识别，Upload 按钮直接灰掉
图形界面启动 VSCode（双击图标）在 macOS/Linux 下不加载 .zshrc 或 .bashrc，即使终端里 arduino-cli version 能跑，VSCode 也找不到它。
- macOS：必须在终端执行
code --new-window启动 VSCode；或手动在设置里填arduino.path为/usr/local/bin/arduino-cli（Homebrew 安装）或/opt/homebrew/bin/arduino-cli（Apple Silicon） - Windows：安装 Arduino IDE 时务必勾选 “Add arduino-cli to system PATH”；手动加环境变量极易因反斜杠
\或大小写出错 - Linux：运行
which arduino-cli查路径，然后在 VSCode 设置中搜arduino.path，填绝对路径（如/home/xxx/.arduino15/arduino-cli），不能是软链接 - 验证方式：VSCode 中按
Ctrl+Shift+P→ 输入Arduino: Initialize，能弹出选项框才算识别成功
选了 Uno 却报 Arduino.h not found，核心库根本没装
插件初始化项目只写 board 字段，不会自动装 arduino:avr 这类底层支持包。缺核心 = 没头文件 = 编译器直接罢工。
- 先更新索引：
arduino-cli core update-index - 再按板子装核心：
arduino-cli core install arduino:avr（Uno/Nano）、arduino-cli core install esp32:esp32（ESP32）、arduino-cli core install raspberry-silicon:rp2040（Pico） - 第三方板（如 XIAO ESP32C3）需先查其
package_index.json，再执行arduino-cli core install xiaoice:xiaoice - 装完必须完全重启 VSCode，否则新板型不会出现在
Arduino: Select Board Type列表里
串口监视器点开就报 Port not found 或输出乱码
VSCode 插件自带的串口按钮（插头图标）在上传后会主动断开串口，导致连不上；乱码则大概率是波特率不一致，或驱动在高波特率下不稳定。
- 别依赖插件按钮，改用终端命令：
arduino-cli monitor -p /dev/ttyUSB0 -b 9600（Linux/macOS）或arduino-cli monitor -p COM3 -b 9600（Windows） - macOS Ventura+：进「系统设置 → 隐私与安全性 → 完全磁盘访问」，把 VSCode 加进去
- Linux：执行
sudo usermod -a -G dialout $USER，然后**完全退出 VSCode 并重开**（仅 Reload Window 不生效） - CH340 芯片在 macOS 14+ 或高波特率（115200）下易丢数据，优先降为
9600或19200
智能提示失效、库引用报 no such file or directory
VSCode 的 C/C++ 扩展不自动继承 arduino-cli 的 include 路径，c_cpp_properties.json 必须手动补全，否则 #include <arduino.h></arduino.h> 就标红。
- 在项目根目录打开命令面板，运行
C/C++: Edit Configurations (UI) - 在
Include path里添加：${env:HOME}/.arduino15/packages/arduino/hardware/avr/*/cores/arduino（macOS/Linux）或C:/Users/${env:USERNAME}/AppData/Local/Arduino15/packages/arduino/hardware/avr/*/cores/arduino（Windows） - 第三方库（如
Adafruit_NeoPixel）要用arduino-cli lib install "Adafruit NeoPixel"全局安装，本地解压到libraries/文件夹无效 - 路径含中文会导致
avrdude ENOENT，整个项目路径必须是纯英文
最常被忽略的是：所有配置（CLI 路径、核心安装、串口权限、c_cpp_properties.json）都必须在 Arduino: Initialize 之后完成，且每次换板、换芯片、换系统都要重新验证——没有一劳永逸的配置。
