故障排除

仿真无法启动

1. 检查输出控制台 — 如果编译失败，错误信息会显示在那里，并附带文件和行号。参见 阅读编译错误。
2. 电路验证器警告（例如，在电气模式下，LED 没有串联电阻）会故意阻止运行 — 请修复标记的接线。
3. 会话的首次运行是冷编译，在大型工具链（ESP-IDF）上可能需要一段时间；后续运行会快得多。在假设其卡住之前，请给首次运行一些时间。

程序在运行，但没有任何反应

• 工具栏的板卡选择器中是否选择了正确的板卡？
• 打开串行监视器 — 如果固件崩溃或正在等待输入，它会告诉你。
• 右键点击部件以确认其属性（设置为 0 个 LED 的 NeoPixel 灯带不会产生任何效果）。

页面本身行为异常

• Velxio 需要桌面版 Chromium 或 Firefox，且版本较新。
• 更新后请强制刷新（Ctrl+Shift+R）— 过期的缓存包可能与新后端不兼容。
• 涉及 WebAssembly、canvas 或 WebSockets 的浏览器扩展（激进的隐私拦截器）可能会破坏模拟器 — 请尝试使用无痕窗口。

Web 烧录无法识别我的板卡

• 请使用 Chrome 或 Edge — Firefox/Safari 未提供浏览器串行 API。
• 关闭所有其他占用该端口的程序（串行监视器、IDE）。
• 尝试另一根数据线 — 仅充电 USB 数据线是经典陷阱。

WiFi 示例无法连接

• SSID 必须完全为 Velxio-GUEST，开放网络，无密码。
• 观察串行监视器中 WiFi 协议栈自身的进度行（wifi:connected、got ip），以确定哪一步失败。

仍然卡住？

在项目打开的情况下，向 AI 助手 提问 — 它能看到与你相同的错误。如果是缺陷，请通过帮助菜单、Discord 或 GitHub 联系团队。