VSCode本身不运行Arduino脚本，仅调用arduino-cli编译烧录；必须手动安装arduino-cli并正确配置路径、运行Arduino: Initialize初始化项目、选择匹配的板型与串口，缺一不可。
VSCode 本身不运行 Arduino 脚本，它只调用 arduino-cli 编译并烧录到板子上；没装 arduino-cli、没运行 Arduino: Initialize、没选对串口，点 Upload 就是空转。
arduino-cli 没装或路径错，Upload 按钮直接灰掉
插件不是“自带编译器”，它只是个界面壳。你必须手动安装 arduino-cli，且 VS Code 能在系统 PATH 或显式配置里找到它。
- Windows：去 GitHub releases 下载
arduino-cli_0.41.2_Windows_64bit.zip，解压后把arduino-cli.exe放进C:\tools\，然后在 VS Code 设置里填完整路径：C:\tools\arduino-cli.exe - macOS：推荐
brew install arduino-cli；若手动安装，务必chmod +x arduino-cli并软链到/usr/local/bin/arduino-cli - Linux：运行
which arduino-cli确认路径，VS Code 设置中arduino.path必须填绝对路径（如/home/you/.arduino15/arduino-cli），不能是符号链接 - 验证是否成功：终端执行
arduino-cli version能输出版本号才算过关；没输出就别往下走
Arduino: Initialize 没运行，.vscode/arduino.json 就不会生成
新建项目后不执行这一步，后续所有板型、端口选择都无效——状态栏不会出现 “Select Board” 或 “Select Serial Port”。
- 打开一个**空文件夹** → 用 VS Code 打开 →
Ctrl+Shift+P（Win）或Cmd+Shift+P（macOS）→ 输入Arduino: Initialize回车 - 选 “Arduino” 模式（不是 PlatformIO），然后从列表里挑**完整板型标识**，例如
arduino:avr:uno，不是 “Uno” 或 “Arduino Uno” - 生成的
.vscode/arduino.json中"board"和"port"字段必须存在、拼写严格（大小写、冒号、双引号全对），JSON 不能有单引号或多逗号 - 如果列表里没有你的板子（比如 ESP32），先终端运行
arduino-cli core install esp32:esp32，再重启 VS Code
串口选错或权限没给，上传报 “No device found on COM3”
VS Code 不会自动刷新串口列表，拔插开发板后，状态栏显示的还是旧端口；不重选，上传必然失败。
- 连接开发板后，
Ctrl+Shift+P→ 输入Arduino: Select Serial Port→ 从下拉菜单选真实端口：COM3（Win）、/dev/cu.usbmodem14301（macOS）、/dev/ttyUSB0（Linux） - macOS 注意区分
/dev/cu.*（正确）和/dev/tty.*（通常无效）；Linux 用户需确保当前用户属于dialout组：sudo usermod -a -G dialout $USER，然后**完全退出 VS Code 再重开**（仅 Reload Window 不生效） - Windows 上查设备管理器里 USB-SERIAL CH340 或 CP210x 是否有黄色感叹号；驱动没装好，端口根本不会出现在列表里
- 上传前确认没被其他程序占用：Arduino IDE、串口助手、Python 脚本等关掉，否则
avrdude: ser_open(): can't open device是静默失败，不是硬件问题
上传卡住、烧录旧代码、或 Serial 监视器乱码
这些现象表面看是通信问题，实际常因缓存、FQBN 错配、或开发板未进入编程模式导致。
- 删掉项目根目录下的
build/文件夹再试；arduino-cli默认复用上次构建产物 - 检查
arduino.json是否漏了"fqbn"字段，或值不完整（如 Nano 需要arduino:avr:nano:cpu=atmega328） - Nano 等老板子需手动复位：点击 Upload 后 1 秒内按一下板载复位键；UNO 一般自动，但 CH340 异常时也得手按
- 监视器乱码？90% 是端口被占：上传后 CLI 会独占串口，如果此时其他程序连着，VS Code 监视器连上的只是空连接——关掉所有串口软件再试
最容易被忽略的是：所有配置（CLI 路径、核心安装、串口权限）都必须在 Arduino: Initialize 之后再做；先乱点 Select Board 再补环境，大概率触发状态不同步，错误信息还特别模糊。
