Electrobun 开发必看：CEF 依赖下载失败？手动解压一招搞定！

梁三石
0 阅读2分钟

在使用 Electrobun + Bun + WebView2 构建跨平台桌面应用时，很多开发者（尤其是国内网络环境）在运行 bun dev 启动项目时，可能会遇到这样一个令人头大的报错：

$ electrobun dev
Using config file: electrobun.config.ts
Ensured launcher has .exe extension on Windows
CEF dependencies not found for win-x64, downloading...
Downloading CEF (attempt 1/3) from: https://github.com/blackboardsh/electrobun/releases/download/v1.15.1/electrobun-cef-win-x64.tar.gz
Download attempt 1 failed: Unable to connect. Is the computer able to access the url?
Retrying in 2 seconds...
Downloading CEF (attempt 2/3) from: https://github.com/blackboardsh/electrobun/releases/download/v1.15.1/electrobun-cef-win-x64.tar.gz
Download attempt 2 failed: Unable to connect. Is the computer able to access the url?
Retrying in 4 seconds...
Downloading CEF (attempt 3/3) from: https://github.com/blackboardsh/electrobun/releases/download/v1.15.1/electrobun-cef-win-x64.tar.gz
Download attempt 3 failed: Unable to connect. Is the computer able to access the url?
Failed to download CEF dependencies for win-x64: Failed to download after 3 attempts: Unable to connect. Is the computer able to access the url?

Please ensure you have an internet connection and the release exists.
If the problem persists, try clearing the cache: rm -rf "E:\workspace\DesktopApp\electrobun\my-app\node_modules\electrobun"
error: script "dev" exited with code 1

❌ 错误原因：Electrobun 需要在首次运行时自动下载约 156MB 的 CEF (Chromium Embedded Framework) 依赖包。由于该资源托管在 GitHub Releases 上，受网络波动或防火墙影响，命令行工具往往无法直接连接下载，导致项目无法启动。

✅ 解决方案：无需等待重试，我们可以手动下载该依赖包，解压到指定目录，让 Electrobun 直接识别本地缓存，瞬间启动！

🛠️ 三步解决下载失败问题

第一步：手动下载 CEF 依赖包

既然命令行下载不动，我们就用浏览器或专业下载工具（如 IDM、迅雷）来下载。

  • 下载地址： github.com/blackboards… (注：如果版本更新，请前往 Electrobun GitHub Release 页面查找最新的 electrobun-cef-win-x64.tar.gz )
  • 文件大小：约 156MB
  • 操作：复制链接到浏览器下载，确保文件完整。

第二步：解压并放入指定目录

下载完成后，我们需要将文件“归位”。Electrobun 会优先检查 node_modules 下的特定目录。

  1. 找到项目目录： 进入你的项目根目录，找到以下路径： 你的项目路径\node_modules\electrobun

  2. 创建/确认目标文件夹： 在该目录下，确保存在名为 dist-win-x64 的文件夹。

    路径示例：E:\workspace\DesktopApp\electrobun\my-app\node_modules\electrobun\dist-win-x64

  3. 解压文件： 使用解压软件（如 7-Zip, WinRAR）打开下载的 electrobun-cef-win-x64.tar.gz。

    • 先解压出 .tar 文件。
    • 再解压 .tar 文件，将其中的所有文件和文件夹（包括 cef, bun.exe, launcher.exe, dll 文件等）直接复制到 dist-win-x64 目录中。

    ⚠️ 注意：确保 dist-win-x64 目录下直接包含 cef 文件夹和 launcher.exe 等核心文件，不要多套一层文件夹。 正确的目录结构应类似如下：

    node_modules/electrobun/dist-win-x64/
├── cef/                 <-- 核心 CEF 文件
├── bun.exe
├── launcher.exe
├── d3dcompiler_47.dll
└── ... (其他 dll 和文件)

  4. cef的目录如下图所示

完整的目录

完整的目录

第三步：重新启动项目

完成上述操作后，再次回到项目根目录运行开发命令：

bun dev

此时，你会看到 Electrobun 不再尝试下载，而是直接识别到了本地文件：

$ electrobun dev
Using config file: electrobun.config.ts
Ensured launcher has .exe extension on Windows
CEF dependencies found for win-x64, using cached version
skipping codesign
skipping notarization
Attached to parent console
Child process spawned with PID anyopaque@d8
[LAUNCHER] Loaded identifier: dev.my.app, name: MyApp-dev, channel: dev
[LAUNCHER] Loading app code from flat files
[CEF] Created job object for process tracking
[CEF] Using path: C:\Users\love2\AppData\Local\dev.my.app\dev\CEF
[CEF] Applying user chromium flag: user-agent=My App/0.0.1(custom user agent)
Server started at http://localhost:50000
[Tue Mar 10 10:30:45 2026] setJSUtils called but using map-based approach instead of callbacks

DevTools listening on ws://127.0.0.1:9222/devtools/browser/e16f1c80-96ff-4094-9221-8b514696a1d4
[Tue Mar 10 10:30:46 2026] Custom class failed, falling back to STATIC class
DEBUG: BrowserView constructor - no HTML provided for webview 1
setting webviewId:  1
WebView2: Download handler registered successfully
[WebView2] NavigationStarting fired for webview 1
[WebView2] NavigationCompleted fired for webview 1
[Bridge:eventBridge] Unknown method DISPID=1 for webview 1
[Bridge:eventBridge] Received message for webview 1

🎉 恭喜！项目成功启动！

💡 原理解析

Electrobun 在启动时会执行以下逻辑：

  1. 检查 node_modules/electrobun/dist-win-x64 是否存在且包含必要的 CEF 文件。
  2. 如果存在，直接跳过下载步骤，使用本地缓存（这就是我们手动复制的目的）。
  3. 如果不存在，则尝试从 GitHub 下载。

通过手动预置文件，我们完美绕过了不稳定的网络环境，实现了“秒级”启动。

📝 常见问题 Q&A

Q: 如果升级了 Electrobun 版本怎么办？ A: 如果大版本更新（例如 v1.15.1 -> v1.16.0），建议删除 dist-win-x64 目录，重新按照上述步骤下载对应新版本的 .tar.gz 包，以确保内核兼容性。

Q: Mac 或 Linux 用户需要这样做吗？ A: 本教程主要针对 Windows (win-x64) 用户。Mac 和 Linux 对应的文件名分别为 electrobun-cef-darwin-x64.tar.gz 或 linux 版本，操作方法一致，只需修改目标文件夹名称（如 dist-darwin-x64）。

Q: 解压后还是报错怎么办？ A: 请检查文件层级。很多时候是因为解压时多套了一层目录（例如 dist-win-x64/electrobun-cef-win-x64/cef）。请确保 cef 文件夹直接在 dist-win-x64 下。

🌟 结语

工欲善其事，必先利其器。在网络环境复杂的情况下，掌握手动管理依赖的技巧，能大大提升我们的开发效率。

希望这篇教程能帮你顺利跑通 Electrobun 项目！如果觉得有用，欢迎点赞、在看、转发，让更多开发者少走弯路！

👇 你在开发中还遇到过哪些奇怪的依赖下载问题？欢迎在评论区留言交流！

avatar
文章
阅读
粉丝