许多开发者在 VS Code 中尝试编写 Arduino 程序时，点击 Upload 却发现毫无反应，进度条一动不动。实际上，VS Code 本身并不直接执行 Arduino 脚本，它只是调用底层命令行工具 arduino-cli 来完成编译与烧录。换句话说，只要缺少任何一个环节——例如未安装 arduino-cli、未初始化项目、未正确选择开发板或串口——点击 Upload 就如同空转。下面我们将逐一拆解这些关键步骤，每一步都不可或缺。
arduino-cli 未安装或路径配置错误？Upload 按钮直接变灰不可用
插件本质上只是一个图形界面，真正的编译和烧录工作完全依赖 arduino-cli。如果没有正确安装它，或者 VS Code 在系统 PATH 中无法找到它，Upload 按钮就会呈现灰色，无法点击。因此，手动安装这一步无法跳过。
- 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，如果能看到版本号才算通过；若没有任何输出，请先检查路径问题，不要继续后续操作。
如果跳过初始化步骤？.vscode/arduino.json 无法自动生成
新建项目后若跳过 Arduino: Initialize 命令，后续所有板型和端口选择都会失效——状态栏不会出现 “Select Board” 或 “Select Serial Port” 选项。这一步是整个配置的基石。
- 打开一个空文件夹 → 在 VS Code 中打开该文件夹 → 按下
Ctrl+Shift+P（Windows）或Cmd+Shift+P（macOS）→ 输入Arduino: Initialize并回车。 - 选择 “Arduino” 模式（而非 PlatformIO），然后从列表中选择完整的板型标识，例如
arduino:a vr: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→ 从下拉菜单中选取正确的端口：Windows 下为COM3，macOS 下为/dev/cu.usbmodem14301，Linux 下为/dev/ttyUSB0。 - 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 脚本等），否则会出现
a vrdude: ser_open(): can't open device这类静默错误，并非硬件问题。
上传卡住、烧录旧代码、监视器显示乱码？常见问题及解决套路
表面看像是通信故障，但很多时候是由于缓存未清理、FQBN 参数填写错误，或者开发板未能进入编程模式导致的。
- 首先删除项目根目录下的
build/文件夹再试——arduino-cli默认会复用上次的构建产物。 - 检查
arduino.json是否缺少"fqbn"字段，或者其值填写不完整（例如 Nano 需要arduino:a vr:nano:cpu=atmega328）。 - 对于 Nano 这类较老的开发板，需要手动复位：点击 Upload 后 1 秒内按下板载复位键；UNO 通常可自动复位，但遇到 CH340 异常时也需要手动按下。
- 监视器显示乱码？90% 是因为端口被占用：上传后 CLI 会独占串口，如果其他程序仍连接着该端口，VS Code 监视器连接的只是空连接——请将所有串口相关软件关闭后再试。
最容易忽视的一点是：所有配置（CLI 路径、核心安装、串口权限）都必须在执行 Arduino: Initialize 之后再进行；如果先随意点击 Select Board 再补全环境设置，大概率会引发状态不一致，错误信息也含糊不清，导致难以定位原因。
