vscode无法选择开发板等故障主因是arduino-cli未被正确识别或核心未安装：需通过终端启动vscode（macos/linux）、验证path配置、手动安装对应核心（如arduino-cli core install arduino:avr），并完全重启vscode生效。
装了插件却选不了开发板、点上传没反应、串口监视器打不开——根本不是插件坏了，而是 VSCode 没真正“看见” arduino-cli，或者它虽然看见了，但核心没装、权限没给、路径写错了一处。
arduino-cli 找不到：PATH 不是万能的，启动方式才是关键
VSCode 图形界面启动时（比如双击图标），macOS 和 Linux 下压根不加载你的 .zshrc 或 .bashrc，所以即使 arduino-cli 在终端里能跑，VSCode 也找不到它。
- macOS：别点图标，改用终端运行
code --new-window启动 VSCode - Windows：安装
arduino-cli时务必勾选 “Add arduino-cli to system PATH”，否则手动加环境变量容易因大小写或反斜杠出错 - Linux：用
which arduino-cli查到绝对路径，然后在 VSCode 设置里搜arduino.path，填进去，例如/home/xxx/bin/arduino-cli - 验证是否生效：VSCode 里按
Ctrl+Shift+P→ 输入Arduino: Initialize，能弹出选项框才算成功
选了板子却编译报 Arduino.h not found
插件不自动装核心，arduino-cli 默认只带一个空壳。你选的是 arduino:avr:uno，就得手动装 arduino:avr 核心，否则连最基本的头文件都找不到。
- 先更新索引：
arduino-cli core update-index - 再装核心：AVR 板用
arduino-cli core install arduino:avr，ESP32 板用arduino-cli core install esp32:esp32 - 第三方板（如 XIAO ESP32C3）需额外加包源，查对应 GitHub 的
package_index.json，再执行arduino-cli core install xiaoice:xiaoice - 确认项目已运行过
Arduino: Initialize，且生成的.vscode/arduino.json中"board"字段值准确无误（大小写、冒号、拼写全敏感）
串口监视器点开就报 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 不生效） - 乱码时先降波特率：代码里是
Serial.begin(115200)，监视器却设成 9600？改成一致；还不行就换 19200，尤其 CH340/CP2102 芯片对 115200 支持不佳
第三方库提示 no such file or directory
Arduino 插件不读项目内 libraries/ 子文件夹，也不同步 Arduino IDE 的库目录。它只认符合规范的顶层库目录，且要求有 library.properties 或 keywords.txt。
- 优先用 CLI 全局安装：
arduino-cli lib install "Adafruit NeoPixel"，插件立刻识别 - 若必须本地引用：把库文件夹（如
Afafruit_NeoPixel）放到项目**同级**的libraries文件夹里，不是项目内部；名字必须和库名完全一致（不能叫neopixel） - Windows 用户特别注意：路径不能含中文、空格或括号，否则
arduino-cli会静默失败
最常被忽略的一点：所有配置变更后，VSCode 必须**完全重启**（不是 Reload Window），尤其是涉及用户组权限（dialout / 完全磁盘访问）或 PATH 变更时，缓存不会自动刷新。
