关键在于手动安装arduino-cli并显式指定其完整可执行路径至vscode的arduino.path设置，重启后通过arduino: board config验证cli就绪；同时确保arduino.json中board和port与硬件严格匹配，避免端口占用、路径错误或文件结构不合规导致的静默失败。
不用装 Arduino IDE，也能完整编译、上传、串口调试 Arduino 项目。关键在于让 VSCode 正确识别并调用 arduino-cli，而不是依赖 IDE 自带的工具链。
如何让 VSCode 找到并正确使用 arduino-cli
插件默认会尝试自动下载一个“bundled”版本的 arduino-cli，但这个行为在某些系统（尤其是 Windows + WSL 混合环境或企业级网络）下容易失败或路径错乱。更稳妥的做法是手动安装并显式指定路径。
- 从
arduino.github.io/arduino-cli下载对应系统的最新arduino-cli二进制（如arduino-cli_0.41.2_Windows_64bit.zip） - 解压后把
arduino-cli.exe（Windows）或arduino-cli（macOS/Linux）放到一个固定路径，例如C:\tools\arduino-cli.exe或/usr/local/bin/arduino-cli - 在 VSCode 设置中搜索
arduino.path，填入该完整路径（注意不是文件夹，是可执行文件本身） - 重启 VSCode，按
Ctrl+Shift+P输入Arduino: Board Config，如果能正常弹出板型列表，说明 CLI 已就绪
arduino.json 中 board 和 port 必须匹配硬件实际状态
arduino.json 里写的 "board": "arduino:avr:uno" 和 "port": "COM3" 不是“选一个就行”，而是必须和你当前接上的物理设备完全一致。写错会导致编译通过但上传失败，错误信息常为 Failed to upload: No device found on COM3 或 Board arduino:avr:uno not found。
- Windows 上用设备管理器确认 CH340/CP210x 驱动是否已加载，端口号是否真为 COM3
- macOS/Linux 上用
ls /dev/cu.*查看真实串口名，cu.usbmodem类似名称才有效，tty.开头的多数不可用 - 板型 ID 必须精确：ESP32 是
esp32:esp32:esp32，不是esp32；Nano Every 是arduino:megaAVR:nona4809，不是arduino:avr:nano - 如果开发板刚插上，VSCode 可能缓存旧端口，需点击左下角状态栏的端口/板型区域重新选择
串口监视器乱码？先关掉所有其他串口软件再排查
VSCode 内置串口监视器显示乱码，90% 的情况不是波特率设错，而是端口被占用了。Arduino CLI 上传时会独占串口，如果此时有别的程序（Arduino IDE、Putty、Serial Studio、甚至另一个 VSCode 窗口）开着串口，arduino-cli 会静默失败，后续监视器连上的只是残留的空连接。
- 关闭所有可能访问串口的软件，包括后台运行的 Arduino IDE 实例（哪怕没打开窗口）
- 检查
arduino.json中是否误加了"programmer"字段——除非你用 ISP 烧录器，否则删掉它，避免干扰串口通信 - 波特率要和代码中
Serial.begin(115200)严格一致；若仍乱码，临时改回9600测试，排除 USB 转换芯片兼容性问题 - macOS 上若用的是较新的 Silicon Mac，确保已安装 Apple 提供的
CH34xUSBSerialDriver（非社区版），否则cu.wchusbserial类设备无法稳定通信
多文件项目编译失败？别漏掉 .h/.cpp 的命名与位置
VSCode + Arduino 插件对多文件支持有限：它只扫描项目根目录下的 .ino、.cpp、.h，不会递归进入子文件夹。如果你把 sensor.cpp 放在 src/ 里，它根本不会参与编译。
- 所有源文件必须平铺在项目根目录，不能嵌套；
.ino主文件名必须和文件夹名一致（如文件夹叫Blink，主文件就得叫Blink.ino） -
.h文件必须有对应的.cpp（或.ino中有#include "xxx.h"），且头文件开头要有#pragma once或传统卫士宏，否则重复包含报错 - 若用到第三方库，不要手动复制到项目里；改用
arduino-cli lib install "Adafruit SSD1306"命令全局安装，或在arduino.json中加"library_manager": { "enable": true }后通过命令面板管理
真正卡住的地方往往不是语法或逻辑，而是 CLI 路径没生效、端口被静默占用、或者头文件根本没被编译器看到——这些细节不报错，只让整个流程看起来“莫名其妙地失败”。
