VSCode本身不支持Arduino开发，必须搭配arduino-cli或完整Arduino IDE才能编译上传；只装扩展无效，90%报错源于工具链未连上。
VSCode 本身不支持 Arduino 开发，必须搭配 arduino-cli 或完整 Arduino IDE 才能编译、上传；只装扩展没用，90% 的报错（如 “No board selected”“arduino-cli not found”）都源于工具链没连上。
Arduino 官方扩展 + arduino-cli 是当前最轻量可靠的组合
Microsoft 维护的 Arduino 扩展（非 PlatformIO）是唯一官方支持路径，但它完全不带编译器——所有动作都靠 arduino-cli 驱动。它比依赖完整 Arduino IDE 更干净，尤其适合 CI/CD 或多用户环境。
- Windows：下载
arduino-cli_0.41.2_Windows_64bit.zip，解压后把arduino-cli.exe放进C:\tools\这类无空格路径，再在 VSCode 设置里填arduino.cliPath为该完整路径 - macOS：用
brew install arduino-cli，Apple Silicon 路径是/opt/homebrew/bin/arduino-cli，Intel 是/usr/local/bin/arduino-cli - Linux：确保
arduino-cli在$PATH中，且当前用户有串口权限（sudo usermod -a -G dialout $USER） - 验证是否就位：终端运行
arduino-cli version必须输出版本号；否则扩展会静默失败，状态栏一直灰着
必须运行 Arduino: Initialize 才能生成有效配置
新建文件夹 → 用 VSCode 打开 → Ctrl+Shift+P（Win）或 Cmd+Shift+P（macOS）→ 输入 Arduino: Initialize 并回车。跳过这步，.vscode/arduino.json 就不会生成，后续所有板型、端口选择都无效。
- 选 “Arduino” 模式（不是 PlatformIO），然后从列表中严格选
arduino:avr:uno，不是 “Uno” 或 “Arduino Uno” - 如果列表里没有你的板子（比如 ESP32），先终端运行
arduino-cli core install esp32:esp32，再重启 VSCode -
arduino.json中"board"和"port"字段必须存在，值用双引号包裹，冒号和大小写不能错，JSON 不允许单引号或尾随逗号
上传前必须手动重选串口，且 macOS/Linux 要特别注意设备名
VSCode 不自动刷新串口列表。拔插开发板后，状态栏显示的还是旧端口，不重选必失败，典型错误是 No device found on COM3 或 avrdude: ser_open(): can't open device。
- 按
Ctrl+Shift+P→ 输入Arduino: Select Serial Port→ 从下拉菜单选真实端口：COM3（Win）、/dev/cu.usbmodem14301（macOS）、/dev/ttyUSB0（Linux） - macOS 上务必选
/dev/cu.*开头的设备，/dev/tty.*基本无效；CH340 芯片需在「系统设置 → 隐私与安全性 → 允许」里手动启用CH34xUSBSerialDriver.kext - Linux 用户若提示权限不足，检查是否已加入
dialout组，必要时执行sudo chmod a+rw /dev/ttyUSB0（仅临时调试用）
Arduino 扩展不支持调试，真要断点得换方案
官方 Arduino 扩展只提供验证（✓）和上传（→）按钮，没有调试能力。想在 ATmega328P 上设断点、看变量，目前只有两条路：
- 改用
PlatformIO：在platformio.ini中明确写upload_protocol = arduino，并配好debug_tool（如simavr或atmel-ice） - 坚持用 Arduino 扩展：额外装
cortex-debug插件，在.vscode/launch.json里手写配置，但仅支持部分带 SWD/JTAG 的 AVR（如 ATmega4809），经典 Uno/Nano 不支持硬件调试
真正容易被忽略的是：Arduino 扩展的“上传”本质只是调用 avrdude 烧录 hex 文件，它不启动任何调试服务；所谓“调试”，要么靠串口打印，要么得切换工具链。
