VSCode运行Arduino项目需手动配置arduino-cli、核心库、串口权限及头文件路径。必须安装arduino-cli并加入PATH，运行arduino-cli version验证；执行core update-index和core install安装对应板卡核心；macOS/Linux需授予权限或添加用户组；VSCode中正确设置arduino.path和c_cpp_properties.json的includePath，避免中文路径。
VSCode 要真正跑起 Arduino 项目，不是装个插件就完事——它本身不带编译器，必须靠 arduino-cli 驱动，且核心库、串口权限、板卡定义都得手动对齐，否则必卡在 No such file or directory: Arduino.h 或 Port not found。
arduino-cli 没装好，VSCode 就是空壳
插件只是“遥控器”，arduino-cli 才是真正的编译上传引擎。Windows 用户解压后必须把 arduino-cli.exe 所在目录加进系统 PATH；macOS/Linux 要 chmod +x 并软链到 /usr/local/bin/arduino-cli。终端里运行 arduino-cli version 能返回版本号，才算落地成功。
VSCode 设置里务必确认：arduino.path 指向的是可执行文件（如 /usr/local/bin/arduino-cli），不是文件夹。别信插件自带的“自动下载”，经常版本陈旧或路径错乱。
核心库没装，连 Arduino.h 都找不到
arduino-cli 默认不装任何开发板支持包，选了 Uno 却报 Arduino.h 缺失，就是这个原因。
- 先运行
arduino-cli core update-index同步索引 - 按你用的板子装对应核心：
arduino-cli core install arduino:avr（Uno/Nano）、arduino-cli core install esp32:esp32（ESP32）、arduino-cli core install xiaoice:xiaoice（XIAO ESP32C3） - 第三方板务必查清其
package_index.json里的完整 ID，拼错一个字符就失败
注意：Arduino: Initialize 只生成 arduino.json，不会帮你装核心——它只记你选的 board 和 port。
串口识别失败，90% 是权限或驱动问题
macOS Ventura+ 系统会拦截串口访问，必须进「系统设置 → 隐私与安全性 → 完全磁盘访问」，把 VS Code 加进去；Windows 下 CH340/CP2102 芯片得去官网下驱动，别用“万能驱动”；Linux 用户要执行 sudo usermod -a -G dialout $USER，然后**彻底重启 VS Code**（不是 Reload Window）。
上传前必须手动点右下角 Select Serial Port 选对端口：COM3（Win）、/dev/cu.usbserial-XXXX（macOS）、/dev/ttyUSB0（Linux）。选错或被其他程序占用，就会报 avrdude: ser_open(): can't open device 或 Permission denied。
智能提示失效，其实是头文件路径没声明
VSCode 不像 Arduino IDE 那样自动扫库路径，C/C++ 插件需要显式告诉它去哪找 Arduino.h 和各类库。
检查 .vscode/c_cpp_properties.json 中的 includePath，确保包含：
["${workspaceFolder}/**", "${env:LOCALAPPDATA}/Arduino15/packages/**"]
Windows 用户若用默认 Arduino IDE 安装路径，还得补上类似 C:/Program Files (x86)/Arduino/hardware/** 的条目；macOS/Linux 对应路径也要核对。漏掉任一环节，Serial.println() 就标红，跳转定义也失效。
最常被忽略的其实是路径中的中文字符和空格——Arduino CLI 和 VSCode 插件对中文路径兼容性极差，一旦出现奇怪报错，第一反应该检查工作区和用户文档路径是否全是英文。
