VSCode运行Arduino脚本的硬件编程教程

许多开发者在 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 再补全环境设置，大概率会引发状态不一致，错误信息也含糊不清，导致难以定位原因。