vscode本身不运行arduino代码，仅调用arduino-cli编译烧录；必须手动安装cli并配置path、安装对应核心库、正确设置fqbn、选择串口并授予权限，否则upload失败或按钮灰显。
VSCode 本身不运行 Arduino 代码，它只调用 arduino-cli 编译并烧录——没装 CLI、没选对板子、没指定串口，点 Upload 就是白点。
arduino-cli 没装或路径不对，Upload 按钮直接灰掉
插件不是“自带编译器”，它只是个界面壳。你必须手动安装 arduino-cli，且 VS Code 能在 PATH 里找到它。
- 别信插件弹窗里的“自动下载”，经常失败或版本过旧；去 GitHub 官方 releases 下最新二进制
- Windows：解压后把含
arduino-cli.exe的文件夹加进系统 PATH；macOS/Linux：运行chmod +x arduino-cli && sudo ln -s $PWD/arduino-cli /usr/local/bin/arduino-cli - 终端执行
arduino-cli version能返回版本号，VS Code 才算真正识别成功 - 检查插件设置里的
arduino.path，它必须指向arduino-cli可执行文件（不是文件夹）
Board not found 或 Arduino.h 报错：核心库根本没装
选板 ≠ 装核心。插件初始化项目时只写 board 字段，不会帮你装 arduino:avr 或 esp32:esp32 这类底层支持包。
- 先运行
arduino-cli core update-index同步索引 - 再按需安装：如
arduino-cli core install arduino:avr（Uno/Nano）、arduino-cli core install esp32:esp32（ESP32） - 第三方板（如 XIAO ESP32C3）需查对应
package_index.json，运行arduino-cli core install xiaoice:xiaoice - 装完必须完全退出 VS Code 再重开，否则新板型不会出现在列表里
串口 Permission denied 或 avrdude: ser_open() 失败
VS Code 不会自动猜端口，也不会自动获取系统权限。上传前必须人工确认三件事：驱动、端口、权限。
- Windows：查 USB 芯片型号（CH340/CP2102/FT232），去官网下驱动；避免“万能驱动”
- macOS：在「系统设置 → 隐私与安全性 → 完全磁盘访问」里添加 VS Code；若用 CH340，还需允许
CH34xUSBSerialDriver.kext - Linux：运行
sudo usermod -a -G dialout $USER，然后完全退出 VS Code 再重开（仅 Reload Window 不生效） - 状态栏点击
Select Serial Port，选对设备：Windows 是COM3类，macOS 是/dev/cu.usbserial-xxxx，Linux 是/dev/ttyUSB0
上传没反应、卡住、或烧录旧代码
常见于缓存未清、FQBN 错配、或开发板未进入编程模式。
- 删掉项目根目录下的
build/文件夹再试；arduino-cli默认复用上次构建产物 - 检查
arduino.json里是否漏了"fqbn"字段，或值不完整（如缺cpu=atmega328p） - Nano 等老板子需手动复位：点击 Upload 后 1 秒内按一下板载复位键；UNO 一般自动，但 CH340 异常时也得手按
- 如果一直烧录上一版代码，确认没在其他程序（Arduino IDE、串口助手、Python 脚本）占用该端口
最易被忽略的是：所有配置（CLI 路径、核心安装、串口权限）都必须在项目初始化（Arduino: Initialize）之后再做；先乱点 Select Board 再补环境，大概率触发状态不一致。
