ArduinoESP32.ino 草图桩编译烧录预检

Arduino Sketch 桩编译验证(arduino-sketch-stub-compile)

在烧录前用"桩头文件 + 交叉编译器"几秒验证草图能否编译,拦掉"一烧就失败"的低级错误。

一、这个 skill 是做什么的

写 Arduino / ESP32 草图(.ino 文件)时,最常翻车的不是逻辑,而是一些低级错误:漏掉了宏定义(比如颜色、屏幕旋转方向的常量)、函数写在调用点之后、类型对不上、括号没配平。这些问题在 Arduino IDE 里要等到真正编译甚至烧录那一刻才冒出来,每次试错都要烧一次板子,费时又费心。

本技能用一套"桩头文件 + ESP32 交叉编译器"的组合拳,在你本地电脑上几秒钟就跑一次语法级体检:它把第三方库(如 SPI、Adafruit_GFX)替换成"空壳桩头",只检查你的代码本身语法对不对、类型对不对、声明顺序对不对,不去管库的真实行为。把试错成本从"烧一次板子"降到"跑一条命令"。

它不是纸上谈兵:这套技能来自一个真实的触摸屏校准项目(MRB2801),第一次把验证脚本化后,一次性揪出 4 个会导致编译失败的 bug(3 个缺失宏 + 1 个变量声明晚于使用)——人工审阅时全部漏掉了。

二、什么时候用它

你可能会听到的"信号原话":

三、前置条件 / 准备

四、具体用法(步骤)

  1. 先跑括号平衡:脚本内部已内置这一步。括号不平衡时,编译器报的错会指向错误方向、误导你,所以先确保结构本身是配平的。
  2. 跑桩编译:按脚本报告的 error: 一条条修。常用库别名(大小写不敏感):SPI、Preferences(或 NVS)、Adafruit_GFX(或 GFX)、XPT2046(或 Touch)、WiFi、HTTPClient(或 HTTP)、ArduinoJson(或 JSON)、Wire(或 I2C)。
  3. 分清两类报错:
    • 真 bug:was not declared in this scope(没声明)、no matching function(函数对不上)、缺 <initializer_list> 等 → 改你的草图。
    • 桩不够:库的某个 API 桩头没覆盖(比如某构造函数没实现)→ 去补脚本里 STUBS 字典对应的桩头(补一次长期受益,下次同类项目直接可用)。
  4. 修到 0 error 再交付:退出码 0=通过、1=有编译错误、2=找不到编译器或文件。

几个好用的参数:--prepend 原项目/config.h 把原项目的配置宏插到草图前面(解决"复制代码缺宏");--defines K=V 追加宏定义;--keep 保留临时目录方便排查。

五、可直接照用的示例

你直接对 AI大模型或AI智能体 说:"我刚从老项目抄了段画屏的代码到新的 MRB2801.ino,帮我预检一下能不能编译,别让我直接烧录。"

AI大模型或AI智能体 会:先跑括号平衡,再对该 .ino 跑桩编译(带上 SPI / Adafruit_GFX / XPT2046 等用到的库),把报告里的每个 error 翻译成中文告诉你,并判断是"真 bug 要改草图"还是"桩不够要补桩"。比如发现你抄来的代码用了 COLOR_BLACK 但新草图没定义,会提示你用 --prepend 老项目/config.h。

你直接对 AI大模型或AI智能体 说:"这个 my_sketch.ino 我改了一大通,担心括号或函数顺序错了,在烧之前帮我查一遍。"

AI大模型或AI智能体 会:跑桩编译并逐项核对声明顺序,定位"变量/函数声明晚于使用"这类问题(C++ 要求先声明后使用),告诉你把全局变量集中放到第一个用到它的函数之前,修到 0 error 才让你烧录。

进阶 / 可选——如果你习惯自己动手,下面是这条验证命令在做什么:它让本地交叉编译器用"空壳桩头"去编译你的草图,只查语法/类型/声明顺序,不跑真实逻辑。

python scripts/stub_compile.py my_sketch.ino --libs SPI Preferences Adafruit_GFX XPT2046

(上面这行就是"跑桩编译"这一步本身;其余步骤 AI大模型或AI智能体 会替你串起来。)

六、常见注意 / 避坑

七、相关 skill / 延伸

← 返回 SKILL 库