必须手动安装并配置 arduino-cli 路径，VSCode Arduino 扩展不自带编译器；需执行 Arduino: Initialize 生成 arduino.json；上传前须正确选择串口并确保驱动和权限正常。
arduino-cli 必须手动安装并正确配置路径，否则 VSCode 的 Arduino 扩展根本无法执行编译或上传——插件本身不带编译器，所有动作都依赖这个命令行工具。
为什么装了扩展还报 “arduino-cli not found”
VSCode 的 Arduino 插件（Microsoft 官方维护）默认不捆绑 arduino-cli，也不会自动从 Arduino IDE 目录读取工具链。它只认系统 PATH 里的可执行文件，或你显式指定的 arduino.path 设置。
- Windows 用户解压
arduino-cli_0.41.2_Windows_64bit.zip后，把arduino-cli.exe放进C:\tools\这类固定路径，再在 VSCode 设置里填完整路径：C:\tools\arduino-cli.exe - macOS/Linux 用户推荐用
brew install arduino-cli或手动放到/usr/local/bin/，然后chmod +x赋权 - 终端运行
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 格式不能有单引号或多逗号
上传前必须手动选串口，且要选对设备名
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.*（通常无效）；Linux 用户需确保当前用户属于dialout组 - CH340 芯片（常见于国产 Nano）在 macOS 13+ 需手动允许驱动：
系统设置 → 隐私与安全性 → 允许 <code>CH34xUSBSerialDriver.kext
上传失败时最该先查的三件事
别急着改代码。90% 的上传失败跟代码无关，而是环境链路断在底层。
- 终端执行
arduino-cli board list—— 看是否能列出已连接设备；如果报错或无输出，说明驱动或 USB 连接异常 - 检查是否有其他程序占用了串口：Arduino IDE、Serial Monitor、Putty、甚至另一个 VSCode 窗口，全部关掉再试
- 确认开发板处于可接收状态：UNO 一般自动复位，Nano 类板子常需在点击 Upload 后 1 秒内手动按一次复位键
arduino-cli 的初始化状态和串口权限管理——这两处出问题，VSCode 界面往往没明显报错，只表现为按钮灰掉、上传无反应或终端卡在 “Uploading…”。 
