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（AVR 板）或arduino-cli core install esp32:esp32（ESP32） - 确认
package_index.json里对应平台的索引已更新，否则core install会静默失败 - 装完后重启 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，选对设备：COM3（Win）、/dev/cu.usbserial-xxxx（macOS）、/dev/ttyUSB0（Linux）；注意 macOS 上/dev/cu.*才有效，/dev/tty.*通常打不开
上传没反应、卡住、或烧录旧代码
常见于缓存未清、FQBN 错配、或开发板未进入编程模式。
- 删掉项目根目录下的
build/文件夹再试；arduino-cli默认复用上次构建产物 - 检查
arduino.json里是否漏了"fqbn"字段，或值不完整（如缺cpu=atmega328p） -
Nano等老板子需手动复位：点击 Upload 后 1 秒内按一下板载复位键；UNO一般自动，但CH340异常时也得手按 - 如果一直烧录上一版代码，确认没在其他程序（Arduino IDE、串口助手、Python 脚本）占用该端口
所有配置（CLI 路径、核心安装、串口权限）都必须在项目初始化（Arduino: Initialize）之后再做；先乱点 Select Board 再补环境，大概率触发状态不一致，且错误信息极难定位。
