按现象排查故障

板子插上了，端口列表里没有它

看起来是什么样

点「开始烧录」后浏览器弹出端口选择框，但里面是空的，或者只有你电脑上原有的蓝牙串口。没有任何报错——这正是它最难查的地方，屏幕上什么都没发生。

真正的原因（按出现频率排）

1. 线只能充电，不能传数据。这是第一名，远超其他。充电线插上去板子的电源灯会亮，看起来一切正常，但电脑根本不知道它存在。
2. USB 串口驱动没装。板子上那颗负责 USB 转串口的小芯片（常见的是 CH340、CP2102）需要驱动。Windows 和一部分 macOS 上要手动装。
3. 插在了不供数据的口上。有些集线器、有些键盘上的 USB 口只供电。
4. 板子本身没有 USB 转串口芯片。一部分模块（不是开发板）要外接一个 USB-TTL 才能烧。

怎么办

1. 换一根线。换一根你确定能传数据的——比如平时给手机传文件用的那根。这一步能解决大半的情况。
2. 换一个 USB 口，直接插电脑，不要经过集线器。
3. 还是没有，去装驱动：先看板子上那颗小芯片的丝印字样（CH340 / CP2102 / CP2104），按型号搜索官方驱动。装完重新插一次线。

点了烧录，浏览器没弹出端口选择框

看起来是什么样

按钮点下去没反应，或者界面上写着 当前浏览器不支持串口烧录（请用 Chrome 或 Edge）。

真正的原因

浏览器里烧录靠的是 WebSerial，这是一个只有 Chromium 内核浏览器才有的能力。Firefox 和 Safari 没有，而且短期内不会有——这是浏览器厂商的决定，不是我们的限制。

怎么办

1. 换成 Chrome、Edge 或其他 Chromium 内核的浏览器，重新打开这个页面。
2. 不想换浏览器也行：点「下载」把固件下下来，用你惯用的工具（esptool、Arduino IDE、乐鑫官方的烧录工具）自己烧。怎么下载 →

一点开始烧录就失败，或者卡在某个百分比不动

看起来是什么样

端口选好了，进度条走了一点就停，日志里出现 Failed to open serial port.、No serial data received. 或者 Failed to connect with the device。这三句是各自独立的报错，不会拼在一起出现；用 Ctrl+F 搜的时候按原样搜。

真正的原因

你看到的	真正的意思
Failed to open serial port.	另一个程序正占着这个串口。这是浏览器打不开端口时的固定措辞，字面上像权限问题，实际上并非如此。最常见的三个占用者：开着串口监视器的 Arduino IDE、上一个还没关掉的浏览器标签页、别的串口工具。（本页自己的 Console 连着时「开始烧录」是灰的、点不动，所以走不到这一步。）如果你不是在浏览器里烧，而是用命令行的 esptool.py，同一件事在 Windows 上的措辞是 Access is denied.
No serial data received. Failed to connect with the device	板子没进烧录模式。这两句是烧录库分别抛出的，通常只出现其中一句。多数开发板会自动进烧录模式，少数需要你手动：按住 BOOT 键不放，插上线（或按一下 RESET），再松开 BOOT。
走到某个百分比就不动了	通常是线接触不良或供电不足。等是没用的——这不是网络传输，卡住就是卡住了。

怎么办

1. 断开 Console，关掉所有可能占着串口的程序（Arduino IDE、其他串口工具、另一个开着这个项目的标签页）。
2. 重新点烧录。
3. 还是 No serial data received.：按住 BOOT 键，同时按一下 RESET，先松 RESET 再松 BOOT，然后立刻重试烧录。
4. 还是卡住：换一根线，换一个直连电脑的 USB 口。

串口连上了，但打出来的全是乱码

看起来是什么样

Console 中持续有输出，但全是 ÿÿ��@� 这种看不懂的字符。有时候开头几行是正常的，后面变成乱码。

真正的原因

1. 波特率不对。第一名。连接时选的速率和固件里设的不一致，读出来就是乱码。默认约定是 115200。
2. 开头几行乱、后面正常：这不是故障。复位后最开始那几行由芯片自带的 ROM 打印，它用的速率不一定和固件里设的一致；固件接管之后就正常了，继续往下看即可。
3. 全程乱码且波特率确认没错：通常是接地不良，或者用了不合适的 USB-TTL。

怎么办

1. 断开 Console，重新点「连接设备」，波特率选 115200。
2. 还是乱，试 9600。手上是 ESP8266 板子再试 74880——那是 ESP8266 bootloader 的速率，ESP32 系列的 ROM 用的是 115200。
3. 都不行，在对话中输入：串口输出是乱码，帮我确认固件里设的波特率是多少。

烧完之后板子一直重启

看起来是什么样

Console 里每隔一两秒就重新打印一遍启动信息，中间夹着 Guru Meditation Error、abort() 或者 rst:0xc (SW_CPU_RESET)。

真正的原因

固件已开始运行，但在初始化的某一步崩了，然后看门狗把它重启，如此循环。最常见的是硬件对不上：代码按方案里的引脚去初始化传感器，而你实际接的脚不一样，或者根本没接。

怎么办

1. 在 Console 里向上滚动，找到崩溃前的最后一行——那行通常会说它当时在初始化什么。
2. 把从「复位」到「崩溃」这一整段日志复制下来。
3. 粘到项目对话框里，加一句：烧录后一直重启，这是串口日志，帮我看看卡在哪一步。
4. 同时对照 引脚连接表核一遍你的实际接线。

编译一直不通过

看起来是什么样

对话里出现编译失败的消息。具体是哪一类，看 Main 面板编译产物里的「失败环节」那一行——界面上是英文原文，后面还跟着一个处理动作（例如 · User action required）。失败分成七类，各归各的责任方，先看清是哪一类，再判断要不要你出手。

「失败环节」上的原文	该谁处理	你要做什么
Firmware project needs repair	平台自己修	什么都不用做，等它重试。多数编译失败属于这一类
Hardware selection needs attention	你	这套硬件挑不出构建目标。回对话里换一块受支持的板子，或者把型号补全
Build profile needs backend attention	平台	报给我们
Compile workflow needs backend attention	平台	报给我们
Compile service needs attention	平台	稍后重试
Compile resource unavailable	平台	稍后重试
Compile safety check blocked output	需要人工确认	报给我们

还有几种结果根本不带「失败环节」这一行：它们写在同一个面板上面的「编译」那一行——排队超时、编译超时、系统错误、已取消。前三种直接重试，这是资源紧张，不是你的代码有问题；已取消 是这一轮被停掉了，多数是你自己点了输入框上的停止按钮，重新说一次即可。

怎么办

1. 看清是哪一类。只有 Hardware selection needs attention 需要你出手，其余都在平台侧。
2. 是硬件那一类：回对话里说清楚你实际有什么板子、什么模块。
3. 属于超时或已取消那一类：输入 重新编译。
4. 连着几轮都是同一个错：复制它给出的失败信息，然后输入 连续三轮都是这个错，帮我换个思路。

它说这个硬件「不支持」

看起来是什么样

顶栏的硬件支持标记显示不支持或信息不足，而不是「推荐」或「可尝试」。

真正的原因

目前平台的框架只有 esp-idf 和 arduino 两种。能编出固件的板子是：ESP32 系列（esp32 / s2 / s3 / c2 / c3 / c6 / h2）、ESP8266 开发板、Arduino Uno。它宁可提前说不支持，也不会假装能做然后在编译时炸掉。这是有意的。

「信息不足」是另一回事：它不是说不行，是说你给的信息还不够判断。这种情况补一句型号通常就过了。

怎么办

1. 先看是「不支持」还是「信息不足」。属于信息不足，就把板子完整型号说出来（丝印上印的那一串）。
2. 确实不支持：换一块 ESP32 系列的板子。ESP32-C3 和 ESP32-S3 是最稳的两条路。
3. 手上只有这块、不想换：可以让它按最接近的芯片出方案，但要知道编译能过不等于能在你板子上跑。

发出去半天没有回应

看起来是什么样

消息发出去了，界面上一直显示「正在处理」之类的状态，但很久没有新内容。

真正的原因

1. 它确实正在执行。写代码 + 编译一轮通常要几分钟。这里故意不显示百分比进度条——因为那个数字会是编的。取而代之的是当前在做哪一步。
2. 推送通道断了。结果出来你也看不到。顶栏那盏「实时连接」的灯不会因此变色——通道断开时它只在后台悄悄重连，所以判断不了。
3. 这一轮的执行预算用完了。它会明说，并且可以继续。

怎么办

1. 先看顶栏状态在不在变。在变就是正常的，等着。
2. 直接刷新页面——刷新不会丢失内容，这一轮还在后台跑。刷新会重新拉一次结果，比盯着那盏灯管用。
3. 刷新后仍然没有新内容，且已经超过三十分钟（单次编译的上限就是这个量级）：输入 刚才那一轮好像断了，重新来一次。

代码明明改了，烧进去还是老样子

看起来是什么样

源码面板里能看到改动，但烧到板子上行为没变。界面上可能写着：源码已修改，当前固件仍来自上次成功编译。

真正的原因

「源码改了」和「板子上跑的变了」是两件事，中间隔着两步：编译，和烧录。这是新手最容易陷入的一个概念误区。改源码只改了云端的工程，它必须重新编译成固件，你必须重新烧进去，板子上的行为才会变。

如果你熟悉软件开发

这里没有热重载，也没有 docker restart。链路是 源码 → 编译 → 固件文件 → 烧录 → 设备，四个环节各自有状态，任何一环没走，下游就是旧的。

界面上那句「源码与最近编译一致 / 源码已修改」就是在告诉你前两环对不对得上。烧录那一环没有任何指示器——板子上跑的是什么，平台不知道，只有你知道你最后一次烧的是哪一版。

怎么办

1. 确认它已经重新编译过了——看编译状态那一行说的是「源码与最近编译一致」还是「源码已修改」。
2. 还没编译，就在对话里输入 重新编译。
3. 编译完成后重新烧一次。不重烧，板子上永远是老固件。

Console 显示「当前浏览器不支持串口 console。」

看起来是什么样

切到 Console 面板，日志区里只有这一句提示，「连接设备」按钮是灰的、点不动。按钮一直在那里，只是被禁用了。

真正的原因

和烧录是同一个原因：WebSerial 只有 Chromium 内核的浏览器才有。

怎么办

换 Chrome 或 Edge。串口日志没有下载这条退路——它必须实时连着设备读，所以产品内没有其他办法。产品之外还有一条：用电脑上任何一个串口工具（比如 screen、PuTTY、Arduino IDE 的串口监视器）读，然后把日志复制到对话框里。

日志太长——直接粘贴，超长的会自动转成附件

看起来是什么样

粘贴本身是可以的。粘完如果正文会超过上限，这段文字不会进输入框，而是变成输入框下方的一条 pasted-….log 文件条，同时给出提示：粘贴内容 12345 字，超过正文上限 8000 字，已转成附件 pasted-20260908-101530-a1b2.log（48.2 KB）。请在输入框写一句你想让我看什么。

真正的原因

项目对话单条正文最多 8000 字。没超过上限的粘贴照常进输入框，行为一点不变；超过的那一次才走转存。转出来的是一条普通附件，和你自己把文件拖进来没有区别。

怎么办

1. 粘贴之后一定要写一句话说明你想让它看什么，比如 这是烧录后的串口输出，一直在重启，帮我看看卡在哪。只有附件、正文空着是发不出去的，界面会提示 请说明你上传的是什么、想让我做什么。
2. 日志已经存成文件的，直接把 .log 拖进输入框，效果一样。
3. 或者只贴关键的那一段：从「复位」到「崩溃」之间通常就够了。