Electrobun 桌面应用排错速查：从构建失败到恢复的完整路径

Electrobun 桌面应用排错速查：从构建失败到恢复的完整路径

【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobun

Electrobun 的构建和测试一报错，先别慌，把信息读完。四个高频症状，每个都走完「报错信息 → 根因 → 修复 → 验证」的完整链路。一份 Electrobun 排错速查，拿来即用。

先读报错，再动手

Electrobun 的构建脚本会把每条子命令的失败包成固定格式。第一行是"<命令>" failed with exit status <退出码>，第二行是cwd: ...，后面跟这条命令的 stderr。⚠️ 第一行告诉你哪一步挂了、以什么方式挂的；cwd告诉你先去看哪个目录；真正的错误几乎都在下面的 stderr 里。Windows 上退出码是 0x 十六进制，比如0x00000001。

测试失败另有固定形态：测试执行器 会打出红色的✗ FAILED: <错误信息>，带堆栈时会把堆栈一并打印。堆栈首行通常就是问题所在。

"cmake --build ." failed with exit status 2 cwd: /work/package/vendors/cef make[2]: *** [CMakeFiles/libcef_dll_wrapper.dir] Error 1

看到这组输出，别先修第一行，往下读最后一条 stderr，那才是编译器的判词。

按症状分组的高频问题

症状：构建失败报Missing required dependencies，起步即中断

现象：终端打印⚠️ Missing required dependencies:，下面列出缺失项（如cmake、build-essential），随后抛出Missing required dependencies. Please install them and try again.，构建终止。根因：构建脚本 在准备阶段先校验工具链。Linux 缺 cmake、make 或 gcc，macOS 缺 Xcode Command Line Tools，Windows 缺 Visual Studio 2022 或 cmake，都会在本地直接抛错；CI 环境只告警并继续。修复：按系统装到本地环境即可。Linux 执行sudo apt update && sudo apt install -y build-essential cmake；macOS 执行xcode-select --install；Windows 安装 Visual Studio 2022（含 C++ 开发工具）和 cmake。验证：重跑构建，日志出现✓ All required dependencies found即恢复。

症状：CEF 下载抛Download failed，文件大小不达下限

现象：日志在Downloading CEF for Windows x64...（macOS、Linux 同理）之后抛出Download failed: ... is only <n> bytes (expected > <阈值> bytes). Please try again in a minute.根因：网络抖动或代理拦截，下载不完整，文件体积低于校验下限。脚本已把坏文件删掉，下次运行会自动重下，不用手动清理。修复：等一分钟后重跑构建即可。反复失败就先检查网络和代理设置，把外网通道理顺再构建。验证：日志打印CEF extracted successfully，且vendors/cef/CMakeLists.txt存在，说明 CEF 解包完整。

症状：测试卡一阵后报Test timed out

现象：某个测试长时间无返回，日志出现Test timed out after 15000ms，紧接红色✗ FAILED: Test timed out after 15000ms和一段堆栈。根因：非交互测试与超时计时器赛跑，窗口创建或 RPC 调用没在限时内回来就会被掐掉。Linux 上多个 CEF 实例背靠背连跑，资源竞争时尤其容易触发。修复：先关掉其他 Electrobun 测试进程，确认没有残留窗口，然后单独重跑该测试，看它卡在哪一步日志。验证：该测试打出✓ PASSED (xxxms)，整轮跑完汇总行显示全绿。

症状：Failed to vendor cmake，提示手动安装

现象：日志打印Failed to vendor cmake:加原始错误，随后抛出Could not vendor cmake. Please install it manually.根因：构建会尝试把指定版本的 cmake 自行下载到vendors/目录，保证各机版本一致。下载失败时脚本放弃 vendoring，让你装一份系统级的。修复：在本地装 cmake。Linux 用sudo apt install -y cmake，macOS 用brew install cmake，装完直接重跑构建。验证：日志出现✓ cmake vendored successfully，或依赖检查直接通过、构建进入下一步。

当症状对不上号时（进阶排查）

把构建切到 debug 渠道

构建脚本 里不加--release参数时，CHANNEL 默认就是 debug，不做发布级优化，问题更容易原样复现。遇到难定位的行为异常，在package目录下用hutch build:dev走开发模式构建。

用调试器附加到运行进程

macOS 上调试发布版应用，官方姿势是lldb <path-to-bundle>/Contents/MacOS/launcher，回车后输入run启动。适合运行时卡死、崩溃这类静态看代码看不出的问题。

顺着 cwd 和退出码找现场

每条failed with exit status报错都带一行cwd。先cd进那个目录，再读它后面的 stderr。Windows 退出码是 0x 十六进制，像0xC0000005这类值通常指向内存访问违规，问题大概率在原生层而非脚本层。

排错速查表

【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobun