Sublime Text 编译上传 Arduino 代码需手动配置 arduino-cli：必须独立安装官方二进制、显式指定 FQBN 和真实串口、严格遵循项目结构（同名文件夹与 .ino 文件）、补全 include 路径以支持头文件跳转。
Sublime Text 不能编译或上传 Arduino 代码——它连 Arduino.h 都不认识，所有动作都靠调用外部 arduino-cli 完成。配错路径、漏掉 --fqbn、串口名写成通配符，Build 就直接失败，不给你试错机会。
arduino-cli 必须独立安装且路径写死
Sublime 启动时不会自动加载系统 PATH，更看不到 Arduino IDE 里自带的 arduino-cli。你必须手动下载官方二进制（不是 IDE 安装包，也不是 pip 包），放到固定位置，并在 Build System 中写绝对路径：
- macOS/Linux：解压后放
/usr/local/bin/arduino-cli，运行arduino-cli version验证；记得加执行权限：chmod +x /usr/local/bin/arduino-cli - Windows：解压到无空格路径，如
C:rduino-clirduino-cli.exe，Build System 中必须写成"cmd": ["C:\arduino-cli\arduino-cli.exe", ...]（反斜杠要双写） - 别用
pip install arduino-cli——那是旧社区分支，不支持arduino:avr@2.3.5等新版核心
Build System 必须显式指定 FQBN 和真实串口
--fqbn 和 --port 是 arduino-cli compile 和 upload 的强制参数，漏一个就报错。FQBN 不是板子简称，串口也不能用 shell 通配符：
- FQBN 格式严格：Uno 是
arduino:avr:uno，Nano 是arduino:avr:nano:cpu=atmega328；写成uno或arduino:uno会触发Error: board arduino:uno not found - 串口名必须实时匹配：macOS 用
/dev/cu.usbmodem14301，Linux 用/dev/ttyACM0，Windows 用COM3（注意没有冒号）；拔插板子后务必重跑arduino-cli board list查最新设备 - Build System 的
"cmd"字段必须是数组，不能拼字符串；$file_path指向的是 sketch 文件夹路径，不是 .ino 文件本身
.ino 文件命名和项目结构有硬约束
arduino-cli 对项目结构极其敏感，不满足规则就报 No sketch found：
- 项目根目录下只能有一个
.ino文件，且文件名必须与文件夹名完全一致（如blink/blink.ino） - 不能手动改名或新建多个
.ino；如果已有main.ino，得重命名为main/main.ino并确保文件夹也叫main - Sublime 不自动注入
#include "Arduino.h"或封装setup()/loop()——这些是arduino-cli在编译前做的预处理，它只认标准结构
头文件跳转失效？得手动补 include 路径
Sublime 默认找不到 Arduino.h，所以 Ctrl+点击跳转会失败。这不是语法高亮问题，而是路径没告诉编辑器：
- 打开 Project → Edit Project，在
"settings"下加"include_dirs"，例如：["/Users/you/Library/Arduino15/packages/arduino/hardware/avr/2.3.5/cores/arduino"] - 路径得对应你实际安装的核心版本：先运行
arduino-cli core list确认版本号，再查arduino-cli config get directories.data找数据目录 - 这个配置只影响跳转和符号识别，不影响编译——编译是否成功，只看
arduino-cli调用结果
最常被忽略的一点：Build System 里写的串口名，必须和 arduino-cli board list 当前输出的完全一致。板子断开后它就失效，但 Sublime 不会提醒你——你只会看到 Serial port not found，然后花十分钟检查 FQBN，其实只是端口变了。
