编译与固件

你不用装编译器，也不用看懂生成的代码。但有几件事值得知道：编译什么时候发生、失败时由谁处理、以及为什么「改了代码」不等于「板子上变了」。

一览

你要做什么什么都不用。编译是它自己触发的
一轮大概多久几分钟。第一次要准备工具链。单次编译有上限：ESP-IDF 三十分钟，PlatformIO / Arduino 二十分钟，超过即判为编译超时
产物是什么一个可以直接烧的固件文件
什么时候能下载 / 烧录编译成功之后。在那之前顶栏那三个按钮是灰的
有没有进度条没有。只显示当前在做哪一步——百分比在这里只能是编的
失败了怎么办大多数它自己修完重来。只有一类需要你介入，见下

编译是自己发生的，不是你点出来的

你说「开始写固件吧」，它就把写代码和编译连着做完。中间不需要你按任何按钮。

过程中顶栏和对话里会显示当前这一步：分析需求 → 准备工具 → 生成固件并编译 → 编译完成。这里故意不显示百分比——写代码这件事没有可靠的进度可言，给一个数字只会让你误判还要等多久。

编译成功之后，顶栏右边的下载 / 烧录 / 打包发布才会亮。这是判断「是否已有可用固件」最快的方式。

看到什么算成功：对话里的进度标记走到 📦 编译通过；Main 面板的编译产物出现四行——编译（成功）、框架、构建目标、大小；顶栏的下载 / 烧录 / 打包发布同时变成可点。

编译通过 ≠ 能在你板子上跑。编译只检查代码层面对不对。引脚接错了、模块型号不符、供电不够——这三样编译器一个都发现不了。真正的验收是烧进去之后 Console 里那几行输出。

编译失败了，先看是哪一类

失败被分成七类，类型写在 Main 面板编译产物的「失败环节」那一行，界面上是英文原文，后面还跟着一个处理动作（例如 · User action required）。七类里只有 Hardware selection needs attention 需要你出手——它表示这套硬件挑不出构建目标，回对话里换一块受支持的板子或者把型号补全即可；其余六类等平台自己处理或者稍后重试。

七类分别是什么、各自该找谁，完整对照见按现象排查：编译一直不通过。

「失败环节」下面那句英文不是给你的。失败时那一行下方还会出现一句英文说明，例如 Install PlatformIO, install the required PlatformIO platforms, or configure WB_PLATFORMIO_BIN. 或 Inspect backend/worker logs and fix the compile infrastructure or workflow bug.。它是后端给平台运维写的处理提示，不是你的操作步骤，你既没有那台机器也不需要动它。

「编译」那一行除了成功和失败，还有四种结果，同样拿不到固件：排队超时、编译超时、已取消、系统错误。前两种输入 重新编译 再来一轮即可——这类超时和你输入的内容无关。

还有一句话看着像第五种取值，其实不是：⚠️ 硬件不足，未编译。它不是「编译」那一行的取值，而是对话里的进度标记——表示硬件方案还不足以支撑这一轮要实现的功能，平台根本没有开始编译，所以编译产物那张表里不会出现它。这一种需要你补充硬件信息，参见 硬件方案与接线。

连着三轮都是同一个错？不必继续等待。复制它给出的失败说明，然后输入：连续三轮都是这个错，换个思路试试。或者退回最小版本：先不管前面那些，只做一个最小的：让板载 LED 每秒闪一次——这一招能立刻告诉你是工具链的问题还是你那个具体功能的问题。

源码面板

切到「源码」，能看到完整的工程目录树。你不需要看懂它——整个流程不看代码也能做完。但它在这里，随时可以看。目录树本身不带徽章；打开某个文件之后，文件名旁边才会出现「可编辑」或「只读」。

什么时候能改，什么时候不能

有任务在跑的时候不能保存。徽章变成「只读」，保存按钮点不动，提示是：「当前有任务在运行，暂时无法保存。等它完成后再保存（你的修改仍保留在编辑器里）。」
它刚改过这个文件会提示你文件已被改动，需要点「重新加载」取最新内容之后再改。直接保存会覆盖它刚写入的内容
打不开的文件只有二进制文件和超过 1 MB 的文件读写不了，点开只会得到一条错误提示。构建配置不在此列——platformio.ini、sdkconfig、CMakeLists.txt 都是小文本文件，能打开也能保存。build/、.pio/ 这类生成目录则根本不出现在目录树里

更简便的做法：不要手改，直接说。把读取间隔从 5 秒改成 30 秒 比你自己去代码里找那个数字快得多，而且它改完会同时重新编译。手改适合你很清楚要动哪一行的场合。

「源码已修改，当前固件仍来自上次成功编译」

源码面板上会显示这三句话之一：

尚未编译出固件。这个项目当前没有可用的固件产物，没有东西可以和源码对照。第一次成功编译之前，看到的就是这一句
源码与最近编译一致。你现在看到的代码，就是最近那个固件编出来的代码
源码已修改，当前固件仍来自上次成功编译。代码变了，但固件还是旧的。要重新编译才会对上

这是新手最容易陷入的一个概念误区。「源码改了」和「板子上跑的变了」之间隔着两步：

源码  ──编译──▶  固件文件  ──烧录──▶  板子上运行的程序
      ↑                    ↑
   这一步没做              这一步没做
   固件就是旧的            板子就是旧的

任何一步没走，下游就是旧的。而且注意：平台知道前两步的状态，但完全不知道你板子上现在跑的是哪一版——那个只有你自己清楚。

如果你熟悉软件开发

这里没有热重载，也没有 docker restart。四个环节各自有状态：源码 → 编译 → 固件产物 → 设备。前三环在云端可查，第四环在你桌上、不可查。

「源码与最近编译一致 / 源码已修改」这个指示器只覆盖前两环的一致性，相当于 git status。第三到第四环没有任何指示器——没有 kubectl rollout status 告诉你设备上跑的是哪个版本。想要就得自己造：让它在启动日志里打一个版本串，那句话就是你的 image tag。

获取固件文件

顶栏的「下载」会给你编译好的固件。什么时候用得上：

下载链接是有时效的，过期了回来重新点一次即可。

常见问题

编译要多久算正常？

几分钟。第一次编译一个新项目还要准备工具链。超过三十分钟还没动静，看 发出去半天没有回应。

我可以让它只编译不改代码吗？

可以，输入 重新编译一次，不要改代码。

「固件已实现功能」那张表是怎么来的？

从代码里来的，不是从计划来的。它说有，就是真的写进去了。所以那张表可以当验收清单用——你要的功能在不在上面，即可判断。