Electrobun 开发指南用 TypeScript 构建轻量级跨平台桌面应用【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobunElectrobun 是一套面向 macOS、Windows 与 Linux 的跨平台桌面应用框架核心理念是开箱即用solution-in-a-box安装一个命令行工具 Hutch即可完成项目初始化、TypeScript 打包、原生工具链获取、签名与分发最终产出体积以 MB 计、自带静默更新能力的桌面应用。本文基于当前仓库的 README.md 与 docs 文档体系完整讲解从安装 Hutch、初始化项目、理解双配置文件到构建分发与从源码二次开发的全部流程并给出仓库内的源码与模板证据帮助你快速上手并在 10 分钟内产出可分发的应用。Electrobun 是什么一个分层的盒子式解决方案Electrobun 的目标是成为构建、更新与发布 TypeScript 桌面应用的一体化解决方案solution-in-a-box。它由三个各自独立的组件协作完成Hutch原生构建与工作区 CLI。它运行项目自定义脚本、打包 TypeScript、解析并同步精确的 Electrobun devkit、下载被锁定的编译器工具链并产出可分发的安装包在配置签名时会顺带完成签名。CottontailElectrobun 默认的 JavaScript 主进程运行时用 Zig 构建在 JavaScriptCore 之上提供桌面应用实际会用到的 Node.js 与 Bun 兼容 API。Electrobun 平台层由 Zig、Objective-C 和 C 组成的原生层负责跨平台的窗口、视图、RPC、菜单、托盘、更新与系统集成。与多数桌面 Web 框架不同Electrobun 默认不随应用打包 Chromium 与 Node你的 UI 渲染在用户系统自带的 webview 上macOS 的 WKWebView、Windows 的 WebView2、Linux 的 WebKitGTK主进程跑在轻量级的 Cottontail 上因此应用体积以 MB 计量而非数百 MB。如果你确实需要处处一致的浏览器引擎bundleCEF选项可以打包并固定 Chromium代价是文件体积增大——这是一个由你权衡的取舍。关于 2.x 技术栈的完整分层说明可参见 What is Electrobun 与 Cottontail。快速开始安装 Hutch 并初始化项目方式一全局安装 Hutch在 macOS 或 Linux 上执行curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh在 Windows PowerShell 上执行 ([scriptblock]::Create((irm https://hutch.blackboard.sh/hutch/install.ps1)))安装完成后通过hutch --version确认已加入 PATH。这是唯一需要的 Electrobun 全局安装——Hutch 统一负责脚本、构建、devkit、工具链和发布。如需在不动现有环境的前提下试用预发布版本可以用--channel canary将 canary 渠道安装为独立的hutch-canarycurl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh -s -- --channel canary生产渠道与 canary 渠道并存于~/.hutch/releases启动器位于~/.hutch/bin精确的本地选择记录在~/.hutch/state/selections.json设置HUTCH_HOME可以重定位整个存储目录。stable是生产渠道的别名。方式二从 npm 或 Bun 引导npx electrobun init与bunx electrobun init提供同样的交互式初始化体验。这个零依赖的单一 npm 包本身不携带 Electrobun 运行时或 SDK它只负责从该版本对应的 Electrobun GitHub Release 下载精确配对的 Hutch 归档、校验并缓存然后转发命令。初始化器还会确保生成的项目所需的全局hutch启动器可用。npx electrobun init # 或 bunx electrobun init两种方式默认从stable模板目录初始化显式传入--beta才会使用 beta 模板目录。关于该 npm 引导包的实现细节可参考仓库中的 npm/electrobun/package.json 与 npm/scripts/check-published-bootstrap.mjs后者用于校验已发布的引导包行为。创建项目hutch electrobun init这会打开交互式选择器方向键浏览模板、回车确认。Hutch 下载当前 stable 模板目录并创建项目。模板从极简的 hello-world 到带 React、Solid、Vue、Svelte 或 GPU 渲染 UI 的完整应用骨架一应俱全仓库中可看到 templates 目录下 30 多个模板包括go-maze-wgpu、rust-flock-wgpu、odin-particles-wgpu、wgpu-babylon、wgpu-threejs等。已经知道要选哪个模板跳过选择器hutch electrobun init my-app --templatehello-world初始化必须联网Hutch 需要拉取当前模板目录与所选模板并不会在本地持久缓存它们。初始化完成后init已自动执行了模板显式声明的install任务并完成 devkit 准备如果你用了--skip-install且所选模板提供了install任务请在dev之前先运行hutch run install。项目结构与双配置文件以 templates/hello-world 模板为例一个典型项目长这样my-app/ |-- src/ | |-- bun/ | | -- index.ts # Cottontail 主进程 | -- mainview/ | |-- index.html | |-- index.css | -- index.ts |-- electrobun.config.ts |-- hutch.config.ts |-- package.json |-- hutch.lock -- tsconfig.jsonsrc/下的目录划分忠实反映了应用的真实运行方式src/bun/index.ts是主进程——运行在 Cottontail 上拥有窗口与原生状态是特权代码所在之处。注意目录名bun只是约定俗成并不代表选择了 Bun 运行时运行时选择完全由electrobun.config.ts的build.mainProcess决定详见 Cottontail 文档 中的说明。src/mainview/是 webview UI——普通的 HTML、CSS、TypeScript渲染在原生 webview 中。hutch.config.ts拥有任务与可选的包管理器策略electrobun.config.ts告诉 Hutch 如何把两部分组合成一个应用包。hutch.config.ts任务与版本看仓库中真实的 templates/hello-world/hutch.config.tsexport default { scripts: { install: [hutch, install, --frozen-lockfile], start: [hutch, electrobun, dev], dev: [hutch, electrobun, dev, --watch], build: [hutch, electrobun, build, --envstable], }, };Hutch只从这个文件读取脚本它不会推断package.json里的 scripts不会把node_modules/.bin加进 PATH也不会模拟 npm 生命周期钩子。脚本既可以是字符串作为 shell 表达式解释支持管道、重定向、环境变量展开与等操作符也可以是参数数组第一个元素作为可执行文件其余作为精确参数不做 shell 解析。已发布的模板会在hutch.config.ts中写入精确的 Electrobun release pin例如electrobun: { version: 2.0.0 }保证模板与它测试过的发布版本严格一致。手写项目可以省略这个 pin此时 npm 启动的命令使用依赖配对默认值直接使用 Hutch 的命令则浮动在活动发布渠道上。升级生成的项目只需在应用目录运行hutch electrobun update它会改写最近的hutch.config.ts中的精确 pin 并同步应用。electrobun.config.ts应用与构建再看 templates/hello-world/electrobun.config.tsimport type { ElectrobunConfig } from electrobun; export default { app: { name: hello-world, identifier: helloworld.electrobun.dev, version: 0.0.1, }, build: { mainProcess: cottontail, cottontail: { entrypoint: src/bun/index.ts, }, views: { mainview: { entrypoint: src/mainview/index.ts, }, }, copy: { src/mainview/index.html: views/mainview/index.html, src/mainview/index.css: views/mainview/index.css, }, mac: { bundleCEF: false }, linux: { bundleCEF: false }, win: { bundleCEF: false }, }, } satisfies ElectrobunConfig;自上而下阅读app定义应用身份名称、标识符、版本build.mainProcess选择 Cottontail 作为主进程运行时entrypoint指向主进程入口views声明 webview 的入口copy把 HTML/CSS 放进 bundle 中views://URL 期望的路径三个平台的bundleCEF: false明确采用系统 webview 以保持体积最小。views://是 Electrobun 的专用 scheme用于访问打包进应用内的资源。DevkitSDK 从哪里来Electrobun 没有独立的 SDK npm 包。所选版本的平台归档electrobun-core-*.tar.gz中同时包含该平台的运行时、devkit 清单、JavaScript API以及 Zig、Rust、Go、Odin 四套 SDK。Hutch 准备项目时会校验并将归档存储到~/.hutch/releases/electrobun然后把 SDK 树拷贝进项目作为生成式 sysroot.hutch/devkit/ |-- api/ # JavaScript/TypeScript SDK 源码与配置类型 |-- zig-sdk/ |-- rust-sdk/ |-- go-sdk/ |-- odin-sdk/ |-- package.json # 该版本的 electrobun/* 导出映射 |-- tsconfig.json # 指向 api/ 的 TypeScript paths -- projection.json # 版本、平台与 manifest 身份TypeScript 项目通常通过extends: ./.hutch/devkit/tsconfig.json来让编辑器解析这个无包 SDK facade。.hutch/是 Hutch 拥有的生成状态同步时可能被整体替换直接编辑或提交它都不是受支持的工作流。完整边界说明见 Project Ownership and the Devkit。Hutch 日常命令速查命令作用hutch electrobun init从默认目录选择模板初始化项目hutch electrobun init --beta使用 beta 模板目录hutch run install运行项目可复现的 install 任务hutch install安装package.json依赖内置解析器或委托的外部管理器hutch pm exec -- vite --version运行项目本地的包二进制hutch run dev运行hutch.config.ts中声明的脚本hutch electrobun dev --watch构建并启动应用源码变更时热重建hutch electrobun prepare只准备 devkit 与工具链不构建hutch electrobun update把最近的精确 pin 升级到最新 stable 并同步 devkithutch electrobun sync让未 pin 的项目主动前进到当前渠道头部hutch electrobun build --envcanary/--envstable产出可分发的构建Hutch 的 Electrobun 构建环境共有三个dev、canary、stable。包管理边界没有packageManager配置时hutch install使用 Hutch 内置的npm 兼容解析器它处理package.json的 registry、file:与 git 依赖github:owner/repo#ref与giturl#ref锁定到精确 commit 并以 checkout 形式安装写入hutch.lock——这是 Hutch 唯一读写的外部锁文件bun.lock、package-lock.json等外来锁文件会被忽略且从不迁移。生命周期脚本永不执行没有 postinstall、没有 prepare需要在安装时编译的包应交给显式选择的外部管理器。hutch pm exec只解析最近 package 项目的node_modules/.bin/command拒绝路径形式的命令名绝不使用全局可执行文件、不回退 PATH、不接触 registry、也不像npx那样行为。顶层packageManager可选值为npm、bun、pnpm、yarn或自定义的{ name, executable? }。选择bun而不给 executable 时使用 Hutch 内置的 Bun 工具链PATH 上什么都不用加。包管理与应用主进程跑在 Cottontail 还是 Bun 上完全无关。Rust 项目用 Cargo、Go 项目用 Go modules 管理各自生态的依赖Hutch 不做干预。Cottontail默认的 TypeScript 主进程运行时为什么桌面框架需要单独的运行时因为桌面应用的运行时与通用服务器运行时职责不同Cottontail 只携带应用实际用到的 API把其余部分留给外部生态。它是用 Zig 构建在 JavaScriptCore 之上的提供 Node.js 与 Bun 兼容 API包括Bun.$shell 接口因此现有代码与 npm 包可以直接运行而无需随应用分发 Node 或 Bun。一个最小主进程示例import { BrowserWindow } from electrobun/main; new BrowserWindow({ title: My App, url: views://mainview/index.html, });Cottontail 与 Hutch 的职责边界非常清晰关注点归属执行打包后的 TypeScript 主进程CottontailNode.js 与 Bun 兼容运行时 APICottontail安装包、执行其二进制、维护锁文件默认 Hutch或显式选择的外部包管理器打包主进程与 webview 源码Hutch获取编译器与原生平台产物Hutch签名、公证、封装与打包发布Hutch所有构建相关的东西都不会进入发给用户的运行时。一个值得注意的细节是构建期 Cottontail用于加载配置、运行脚本的那份与 Hutch 发布版本配对由hutch upgrade一起升级而build.mainProcess: cottontail打进应用包里的那份由所选 Electrobun devkit 单独 pin互不继承。Cottontail 的完整介绍见 Cottontail 指南。如果你的应用确实依赖真实的 Bun 运行时把build.mainProcess设为bun即可——Hutch 仍然是构建工具。构建与分发一条命令产出全部发布物hutch electrobun build --envcanary hutch electrobun build --envstable一次构建同时产出可运行的 App、自解压封装、更新元数据、压缩的全量更新归档以及平台安装器产物配置了签名时代码签名与公证是发布构建的一部分。canary 与 stable 是相互独立的渠道因此可以先给测试人员发预发布构建而不影响 stable 发布线。Hutch 只构建当前所在操作系统与架构的目标完整的跨平台发布需要在各目标的原生 CI runner 上各跑一次。发布产物与命名规则所有产物是扁平文件可直接托管在 R2、S3、GitHub Releases 或任何静态 HTTP 服务上。配置发布地址import type { ElectrobunConfig } from electrobun; export default { app: { name: My Cool App, identifier: com.example.my-cool-app, version: 1.0.0, }, build: { mainProcess: cottontail, cottontail: { entrypoint: src/bun/index.ts }, }, release: { baseUrl: https://releases.example.com/my-cool-app, generatePatch: true, }, } satisfies ElectrobunConfig;上传artifacts/目录时不要重命名文件。Hutch 会把应用名中的 ASCII 空格去掉。一个名为My Cool App的应用macOS ARM64 canary 构建产出artifacts/ |-- canary-macos-arm64-update.json |-- canary-macos-arm64-MyCoolApp-canary.dmg |-- canary-macos-arm64-MyCoolApp-canary.app.tar.zst -- canary-macos-arm64-previous-hash.patchWindows x64 与 Linux x64 的产物结构类似Windows 是包含安装程序的 zipLinux 是含自解压安装器的.tar.gzstable 安装器文件名不带渠道前缀与-canary标记但 stable 的更新 JSON 与压缩归档保留stable-os-arch-协议前缀以兼容 Electrobun v1.18.1 客户端。完整命名规则见 Bundling and Distribution。差分补丁与更新链当release.generatePatch: true且配置了baseUrl时Hutch 会从发布主机拉取上一个版本的update.json与.tar.zst归档解压后用 Zig 优化的BSDIFF 实现生成二进制补丁kilobyte 级别并以上一版本的 bundle hash命名。首次发布没有前驱、自然没有补丁缺失或损坏的旧产物会跳过补丁生成但保留全量归档。每个发布贡献一个previous-hash.patch静态主机保留这些不可变文件就形成了补丁链落后多个版本的应用可以逐级应用补丁直到 hash 追上update.json中的目标任意一环失败则回退到全量下载。更新流程与元数据细节见 Updates 指南 与 Updater API。关键特性一览README 中特别强调了以下特性它们都能在仓库源码与模板中找到对应实现Zstandard 压缩的自解压 bundle分发物使用 Zstandard 压缩显著压缩体积。Linux 平台的自解压封装在 package/src/extractor/含 macOS、Windows、Linux 三套卸载提示实现。Zig 优化的 BSDIFF 补丁支持产生 kilobyte 级的增量更新见上文差分补丁。bundleCEF标志打包并固定 Chromium换取处处一致的渲染引擎代价是文件体积。模板中三平台默认false。bundleWGPU让你用 Bun TypeScript → WGPU 直接控制原生 GPU 表面完全不需要 webview。对应wgpuTagRenderer等实现见 kitchen/src/bun/wgpuTagRenderer.ts相关 API 见 electrobun-wgpu-tag.mdx。Three.js 与 Babylon.js 适配器直接在 Cottontail 主进程中工作。仓库中有 wgpu-threejs 与 wgpu-babylon 两个模板以及 kitchen/src/tests/wgpu-adapter.test.ts 等适配器测试。electrobun-webview与electrobun-wgpuHTML 元素允许你在 UI 中像普通元素一样合成隔离的 webview 与原生 GPU 表面。元素实现见 package/src/browser/webviewtag.ts 与 package/src/browser/wgputag.tsAPI 文档见 electrobun-webview-tag.mdx。设计目标五条核心原则README 明确列出了项目的设计目标它们也解释了上述特性为何存在主进程与 webview 都用 TypeScript 写无需操心底层差异。主进程与 webview 进程隔离通过快速、类型安全、易于实现的 RPC 通信——被攻破或有 bug 的视图无法触及它从未被授予的权限。使用系统 webview 时应用包体积小自解压小 bundle。小更新优先用二进制补丁失败时回退到压缩全量下载。提供一个紧密集成的完整工作流5 分钟开始写代码10 分钟完成分发。进程模型上主进程持有应用状态与原生对象每个浏览器视图与之隔离仅通过 RPC 与事件桥通信——你获得了 Web UI 的便利却不会把特权主进程 API 暴露给页面 JavaScript。RPC 的底层实现与测试可参考 package/src/shared/rpc.ts 与 package/src/shared/rpc.test.ts。平台支持矩阵操作系统状态macOS 14官方支持Windows 11官方支持Ubuntu 24.04官方支持其他 Linux 发行版gtk3、webkit2gtk-4.1社区支持Raspberry Pi非官方 forklinux-wpe注意Electrobun 当前的发布矩阵不发布 macOS x64 核心产物Windows ARM 通过系统仿真使用 x64 产物。从源码构建 Electrobun为贡献者准备用模板开发应用只需要安装 Hutch本节是为想从源码构建 Electrobun 以贡献修复的开发者准备的。各平台前置条件macOS需要 Xcode command line tools 与 cmakebrew install cmake。 Windows需要 Visual Studio Build Tools或带 C 开发工具的 Visual Studio与 cmake。 Linux需要 build-essential、cmake、webkit2gtk 与 GTK 开发包。Ubuntu/Debian 系一行安装sudo apt install build-essential cmake pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev libpipewire-0.3-dev librsvg2-devLinux 端用户系统还需要对应的 GTK 3、WebKitGTK 4.1、Ayatana AppIndicator 与 librsvg 运行时包具体发行版的安装命令见 cross-platform-development.mdxlauncher 会在依赖缺失时报告缺失的精确共享库。Wayland 屏幕区域采集额外要求可用的桌面 portal、PipeWire 以及libpipewire-0.3.so.0运行时库Ubuntu/Debian 新版本上由libpipewire-0.3-0t64提供。首次构建git clone --recurse-submodules 仓库地址 cd electrobun/package npm ci hutch dev:cleanpackage/目录是核心构建工作区其配置见 package/hutch.config.ts。开发工作流以下命令均从package/目录执行# 修改源码后重新构建本地 devkit 并运行 Kitchen综合测试应用 hutch dev # 让某个仓库模板针对同一份本地 package/dist 运行 hutch dev:template hello-world # 需要完全重来时 hutch dev:cleanhutch dev构建package/dist并让 Kitchen 针对该本地 devkit 运行直接从kitchen/运行hutch dev则继续使用 kitchen/hutch.config.ts 中 pin 的 Electrobun 版本。hutch dev:template template-name构建同一份本地 devkit执行模板配置的依赖安装并用这些本地产物启动它的dev任务。仓库内模板在此工作流下保持不 pin发布发布者会在暂存模板归档时注入随附的 Electrobun 版本。原生构建会为当前机器生成package/src/native/compile_flags.txtclangd 兼容的编辑器会自动发现它改动原生依赖或系统工具链后需要重新构建。如果存在同级的jsc、cottontail、dash-cloud、electrobun检出目录可以加--local同时构建并选择本地 JSC、Cottontail 与 Hutch 各层hutch dev --local。其他常用命令hutch dev:canarycanary 模式构建并运行 kitchen sink、hutch build:dev开发模式构建、hutch build:release发布模式构建。调试macOS 上对 release 构建使用lldb path-to-bundle/Contents/MacOS/launcher后执行run。生态与社区README 中列举了大量基于 Electrobun 构建的真实应用覆盖 AI 编码工作区Co(lab)、VibesOS、PiBun、音视频工具Audio TTS、FLACK、笔记与编辑器MarkBun、Sideleaf、开发工具Patchline、codex-devtools等方向仓库的 templates 目录与 kitchen 综合测试应用则是探索框架能力的入口。参与贡献前请阅读 CONTRIBUTING.md注意作者明确说明 Issues 与 PRs 可以用于分享想法但不保证会被审阅、回复或合并并参考 docs/src/content/docs/electrobun/guides/changelog/index.mdx 了解各版本演进。关于跨平台开发的深入主题热重载、UI 创建、代码签名、迁移到 v2 等均可从 docs 文档树继续深入。【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Electrobun 开发指南：用 TypeScript 构建轻量级跨平台桌面应用
Electrobun 开发指南用 TypeScript 构建轻量级跨平台桌面应用【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobunElectrobun 是一套面向 macOS、Windows 与 Linux 的跨平台桌面应用框架核心理念是开箱即用solution-in-a-box安装一个命令行工具 Hutch即可完成项目初始化、TypeScript 打包、原生工具链获取、签名与分发最终产出体积以 MB 计、自带静默更新能力的桌面应用。本文基于当前仓库的 README.md 与 docs 文档体系完整讲解从安装 Hutch、初始化项目、理解双配置文件到构建分发与从源码二次开发的全部流程并给出仓库内的源码与模板证据帮助你快速上手并在 10 分钟内产出可分发的应用。Electrobun 是什么一个分层的盒子式解决方案Electrobun 的目标是成为构建、更新与发布 TypeScript 桌面应用的一体化解决方案solution-in-a-box。它由三个各自独立的组件协作完成Hutch原生构建与工作区 CLI。它运行项目自定义脚本、打包 TypeScript、解析并同步精确的 Electrobun devkit、下载被锁定的编译器工具链并产出可分发的安装包在配置签名时会顺带完成签名。CottontailElectrobun 默认的 JavaScript 主进程运行时用 Zig 构建在 JavaScriptCore 之上提供桌面应用实际会用到的 Node.js 与 Bun 兼容 API。Electrobun 平台层由 Zig、Objective-C 和 C 组成的原生层负责跨平台的窗口、视图、RPC、菜单、托盘、更新与系统集成。与多数桌面 Web 框架不同Electrobun 默认不随应用打包 Chromium 与 Node你的 UI 渲染在用户系统自带的 webview 上macOS 的 WKWebView、Windows 的 WebView2、Linux 的 WebKitGTK主进程跑在轻量级的 Cottontail 上因此应用体积以 MB 计量而非数百 MB。如果你确实需要处处一致的浏览器引擎bundleCEF选项可以打包并固定 Chromium代价是文件体积增大——这是一个由你权衡的取舍。关于 2.x 技术栈的完整分层说明可参见 What is Electrobun 与 Cottontail。快速开始安装 Hutch 并初始化项目方式一全局安装 Hutch在 macOS 或 Linux 上执行curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh在 Windows PowerShell 上执行 ([scriptblock]::Create((irm https://hutch.blackboard.sh/hutch/install.ps1)))安装完成后通过hutch --version确认已加入 PATH。这是唯一需要的 Electrobun 全局安装——Hutch 统一负责脚本、构建、devkit、工具链和发布。如需在不动现有环境的前提下试用预发布版本可以用--channel canary将 canary 渠道安装为独立的hutch-canarycurl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh -s -- --channel canary生产渠道与 canary 渠道并存于~/.hutch/releases启动器位于~/.hutch/bin精确的本地选择记录在~/.hutch/state/selections.json设置HUTCH_HOME可以重定位整个存储目录。stable是生产渠道的别名。方式二从 npm 或 Bun 引导npx electrobun init与bunx electrobun init提供同样的交互式初始化体验。这个零依赖的单一 npm 包本身不携带 Electrobun 运行时或 SDK它只负责从该版本对应的 Electrobun GitHub Release 下载精确配对的 Hutch 归档、校验并缓存然后转发命令。初始化器还会确保生成的项目所需的全局hutch启动器可用。npx electrobun init # 或 bunx electrobun init两种方式默认从stable模板目录初始化显式传入--beta才会使用 beta 模板目录。关于该 npm 引导包的实现细节可参考仓库中的 npm/electrobun/package.json 与 npm/scripts/check-published-bootstrap.mjs后者用于校验已发布的引导包行为。创建项目hutch electrobun init这会打开交互式选择器方向键浏览模板、回车确认。Hutch 下载当前 stable 模板目录并创建项目。模板从极简的 hello-world 到带 React、Solid、Vue、Svelte 或 GPU 渲染 UI 的完整应用骨架一应俱全仓库中可看到 templates 目录下 30 多个模板包括go-maze-wgpu、rust-flock-wgpu、odin-particles-wgpu、wgpu-babylon、wgpu-threejs等。已经知道要选哪个模板跳过选择器hutch electrobun init my-app --templatehello-world初始化必须联网Hutch 需要拉取当前模板目录与所选模板并不会在本地持久缓存它们。初始化完成后init已自动执行了模板显式声明的install任务并完成 devkit 准备如果你用了--skip-install且所选模板提供了install任务请在dev之前先运行hutch run install。项目结构与双配置文件以 templates/hello-world 模板为例一个典型项目长这样my-app/ |-- src/ | |-- bun/ | | -- index.ts # Cottontail 主进程 | -- mainview/ | |-- index.html | |-- index.css | -- index.ts |-- electrobun.config.ts |-- hutch.config.ts |-- package.json |-- hutch.lock -- tsconfig.jsonsrc/下的目录划分忠实反映了应用的真实运行方式src/bun/index.ts是主进程——运行在 Cottontail 上拥有窗口与原生状态是特权代码所在之处。注意目录名bun只是约定俗成并不代表选择了 Bun 运行时运行时选择完全由electrobun.config.ts的build.mainProcess决定详见 Cottontail 文档 中的说明。src/mainview/是 webview UI——普通的 HTML、CSS、TypeScript渲染在原生 webview 中。hutch.config.ts拥有任务与可选的包管理器策略electrobun.config.ts告诉 Hutch 如何把两部分组合成一个应用包。hutch.config.ts任务与版本看仓库中真实的 templates/hello-world/hutch.config.tsexport default { scripts: { install: [hutch, install, --frozen-lockfile], start: [hutch, electrobun, dev], dev: [hutch, electrobun, dev, --watch], build: [hutch, electrobun, build, --envstable], }, };Hutch只从这个文件读取脚本它不会推断package.json里的 scripts不会把node_modules/.bin加进 PATH也不会模拟 npm 生命周期钩子。脚本既可以是字符串作为 shell 表达式解释支持管道、重定向、环境变量展开与等操作符也可以是参数数组第一个元素作为可执行文件其余作为精确参数不做 shell 解析。已发布的模板会在hutch.config.ts中写入精确的 Electrobun release pin例如electrobun: { version: 2.0.0 }保证模板与它测试过的发布版本严格一致。手写项目可以省略这个 pin此时 npm 启动的命令使用依赖配对默认值直接使用 Hutch 的命令则浮动在活动发布渠道上。升级生成的项目只需在应用目录运行hutch electrobun update它会改写最近的hutch.config.ts中的精确 pin 并同步应用。electrobun.config.ts应用与构建再看 templates/hello-world/electrobun.config.tsimport type { ElectrobunConfig } from electrobun; export default { app: { name: hello-world, identifier: helloworld.electrobun.dev, version: 0.0.1, }, build: { mainProcess: cottontail, cottontail: { entrypoint: src/bun/index.ts, }, views: { mainview: { entrypoint: src/mainview/index.ts, }, }, copy: { src/mainview/index.html: views/mainview/index.html, src/mainview/index.css: views/mainview/index.css, }, mac: { bundleCEF: false }, linux: { bundleCEF: false }, win: { bundleCEF: false }, }, } satisfies ElectrobunConfig;自上而下阅读app定义应用身份名称、标识符、版本build.mainProcess选择 Cottontail 作为主进程运行时entrypoint指向主进程入口views声明 webview 的入口copy把 HTML/CSS 放进 bundle 中views://URL 期望的路径三个平台的bundleCEF: false明确采用系统 webview 以保持体积最小。views://是 Electrobun 的专用 scheme用于访问打包进应用内的资源。DevkitSDK 从哪里来Electrobun 没有独立的 SDK npm 包。所选版本的平台归档electrobun-core-*.tar.gz中同时包含该平台的运行时、devkit 清单、JavaScript API以及 Zig、Rust、Go、Odin 四套 SDK。Hutch 准备项目时会校验并将归档存储到~/.hutch/releases/electrobun然后把 SDK 树拷贝进项目作为生成式 sysroot.hutch/devkit/ |-- api/ # JavaScript/TypeScript SDK 源码与配置类型 |-- zig-sdk/ |-- rust-sdk/ |-- go-sdk/ |-- odin-sdk/ |-- package.json # 该版本的 electrobun/* 导出映射 |-- tsconfig.json # 指向 api/ 的 TypeScript paths -- projection.json # 版本、平台与 manifest 身份TypeScript 项目通常通过extends: ./.hutch/devkit/tsconfig.json来让编辑器解析这个无包 SDK facade。.hutch/是 Hutch 拥有的生成状态同步时可能被整体替换直接编辑或提交它都不是受支持的工作流。完整边界说明见 Project Ownership and the Devkit。Hutch 日常命令速查命令作用hutch electrobun init从默认目录选择模板初始化项目hutch electrobun init --beta使用 beta 模板目录hutch run install运行项目可复现的 install 任务hutch install安装package.json依赖内置解析器或委托的外部管理器hutch pm exec -- vite --version运行项目本地的包二进制hutch run dev运行hutch.config.ts中声明的脚本hutch electrobun dev --watch构建并启动应用源码变更时热重建hutch electrobun prepare只准备 devkit 与工具链不构建hutch electrobun update把最近的精确 pin 升级到最新 stable 并同步 devkithutch electrobun sync让未 pin 的项目主动前进到当前渠道头部hutch electrobun build --envcanary/--envstable产出可分发的构建Hutch 的 Electrobun 构建环境共有三个dev、canary、stable。包管理边界没有packageManager配置时hutch install使用 Hutch 内置的npm 兼容解析器它处理package.json的 registry、file:与 git 依赖github:owner/repo#ref与giturl#ref锁定到精确 commit 并以 checkout 形式安装写入hutch.lock——这是 Hutch 唯一读写的外部锁文件bun.lock、package-lock.json等外来锁文件会被忽略且从不迁移。生命周期脚本永不执行没有 postinstall、没有 prepare需要在安装时编译的包应交给显式选择的外部管理器。hutch pm exec只解析最近 package 项目的node_modules/.bin/command拒绝路径形式的命令名绝不使用全局可执行文件、不回退 PATH、不接触 registry、也不像npx那样行为。顶层packageManager可选值为npm、bun、pnpm、yarn或自定义的{ name, executable? }。选择bun而不给 executable 时使用 Hutch 内置的 Bun 工具链PATH 上什么都不用加。包管理与应用主进程跑在 Cottontail 还是 Bun 上完全无关。Rust 项目用 Cargo、Go 项目用 Go modules 管理各自生态的依赖Hutch 不做干预。Cottontail默认的 TypeScript 主进程运行时为什么桌面框架需要单独的运行时因为桌面应用的运行时与通用服务器运行时职责不同Cottontail 只携带应用实际用到的 API把其余部分留给外部生态。它是用 Zig 构建在 JavaScriptCore 之上的提供 Node.js 与 Bun 兼容 API包括Bun.$shell 接口因此现有代码与 npm 包可以直接运行而无需随应用分发 Node 或 Bun。一个最小主进程示例import { BrowserWindow } from electrobun/main; new BrowserWindow({ title: My App, url: views://mainview/index.html, });Cottontail 与 Hutch 的职责边界非常清晰关注点归属执行打包后的 TypeScript 主进程CottontailNode.js 与 Bun 兼容运行时 APICottontail安装包、执行其二进制、维护锁文件默认 Hutch或显式选择的外部包管理器打包主进程与 webview 源码Hutch获取编译器与原生平台产物Hutch签名、公证、封装与打包发布Hutch所有构建相关的东西都不会进入发给用户的运行时。一个值得注意的细节是构建期 Cottontail用于加载配置、运行脚本的那份与 Hutch 发布版本配对由hutch upgrade一起升级而build.mainProcess: cottontail打进应用包里的那份由所选 Electrobun devkit 单独 pin互不继承。Cottontail 的完整介绍见 Cottontail 指南。如果你的应用确实依赖真实的 Bun 运行时把build.mainProcess设为bun即可——Hutch 仍然是构建工具。构建与分发一条命令产出全部发布物hutch electrobun build --envcanary hutch electrobun build --envstable一次构建同时产出可运行的 App、自解压封装、更新元数据、压缩的全量更新归档以及平台安装器产物配置了签名时代码签名与公证是发布构建的一部分。canary 与 stable 是相互独立的渠道因此可以先给测试人员发预发布构建而不影响 stable 发布线。Hutch 只构建当前所在操作系统与架构的目标完整的跨平台发布需要在各目标的原生 CI runner 上各跑一次。发布产物与命名规则所有产物是扁平文件可直接托管在 R2、S3、GitHub Releases 或任何静态 HTTP 服务上。配置发布地址import type { ElectrobunConfig } from electrobun; export default { app: { name: My Cool App, identifier: com.example.my-cool-app, version: 1.0.0, }, build: { mainProcess: cottontail, cottontail: { entrypoint: src/bun/index.ts }, }, release: { baseUrl: https://releases.example.com/my-cool-app, generatePatch: true, }, } satisfies ElectrobunConfig;上传artifacts/目录时不要重命名文件。Hutch 会把应用名中的 ASCII 空格去掉。一个名为My Cool App的应用macOS ARM64 canary 构建产出artifacts/ |-- canary-macos-arm64-update.json |-- canary-macos-arm64-MyCoolApp-canary.dmg |-- canary-macos-arm64-MyCoolApp-canary.app.tar.zst -- canary-macos-arm64-previous-hash.patchWindows x64 与 Linux x64 的产物结构类似Windows 是包含安装程序的 zipLinux 是含自解压安装器的.tar.gzstable 安装器文件名不带渠道前缀与-canary标记但 stable 的更新 JSON 与压缩归档保留stable-os-arch-协议前缀以兼容 Electrobun v1.18.1 客户端。完整命名规则见 Bundling and Distribution。差分补丁与更新链当release.generatePatch: true且配置了baseUrl时Hutch 会从发布主机拉取上一个版本的update.json与.tar.zst归档解压后用 Zig 优化的BSDIFF 实现生成二进制补丁kilobyte 级别并以上一版本的 bundle hash命名。首次发布没有前驱、自然没有补丁缺失或损坏的旧产物会跳过补丁生成但保留全量归档。每个发布贡献一个previous-hash.patch静态主机保留这些不可变文件就形成了补丁链落后多个版本的应用可以逐级应用补丁直到 hash 追上update.json中的目标任意一环失败则回退到全量下载。更新流程与元数据细节见 Updates 指南 与 Updater API。关键特性一览README 中特别强调了以下特性它们都能在仓库源码与模板中找到对应实现Zstandard 压缩的自解压 bundle分发物使用 Zstandard 压缩显著压缩体积。Linux 平台的自解压封装在 package/src/extractor/含 macOS、Windows、Linux 三套卸载提示实现。Zig 优化的 BSDIFF 补丁支持产生 kilobyte 级的增量更新见上文差分补丁。bundleCEF标志打包并固定 Chromium换取处处一致的渲染引擎代价是文件体积。模板中三平台默认false。bundleWGPU让你用 Bun TypeScript → WGPU 直接控制原生 GPU 表面完全不需要 webview。对应wgpuTagRenderer等实现见 kitchen/src/bun/wgpuTagRenderer.ts相关 API 见 electrobun-wgpu-tag.mdx。Three.js 与 Babylon.js 适配器直接在 Cottontail 主进程中工作。仓库中有 wgpu-threejs 与 wgpu-babylon 两个模板以及 kitchen/src/tests/wgpu-adapter.test.ts 等适配器测试。electrobun-webview与electrobun-wgpuHTML 元素允许你在 UI 中像普通元素一样合成隔离的 webview 与原生 GPU 表面。元素实现见 package/src/browser/webviewtag.ts 与 package/src/browser/wgputag.tsAPI 文档见 electrobun-webview-tag.mdx。设计目标五条核心原则README 明确列出了项目的设计目标它们也解释了上述特性为何存在主进程与 webview 都用 TypeScript 写无需操心底层差异。主进程与 webview 进程隔离通过快速、类型安全、易于实现的 RPC 通信——被攻破或有 bug 的视图无法触及它从未被授予的权限。使用系统 webview 时应用包体积小自解压小 bundle。小更新优先用二进制补丁失败时回退到压缩全量下载。提供一个紧密集成的完整工作流5 分钟开始写代码10 分钟完成分发。进程模型上主进程持有应用状态与原生对象每个浏览器视图与之隔离仅通过 RPC 与事件桥通信——你获得了 Web UI 的便利却不会把特权主进程 API 暴露给页面 JavaScript。RPC 的底层实现与测试可参考 package/src/shared/rpc.ts 与 package/src/shared/rpc.test.ts。平台支持矩阵操作系统状态macOS 14官方支持Windows 11官方支持Ubuntu 24.04官方支持其他 Linux 发行版gtk3、webkit2gtk-4.1社区支持Raspberry Pi非官方 forklinux-wpe注意Electrobun 当前的发布矩阵不发布 macOS x64 核心产物Windows ARM 通过系统仿真使用 x64 产物。从源码构建 Electrobun为贡献者准备用模板开发应用只需要安装 Hutch本节是为想从源码构建 Electrobun 以贡献修复的开发者准备的。各平台前置条件macOS需要 Xcode command line tools 与 cmakebrew install cmake。 Windows需要 Visual Studio Build Tools或带 C 开发工具的 Visual Studio与 cmake。 Linux需要 build-essential、cmake、webkit2gtk 与 GTK 开发包。Ubuntu/Debian 系一行安装sudo apt install build-essential cmake pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev libpipewire-0.3-dev librsvg2-devLinux 端用户系统还需要对应的 GTK 3、WebKitGTK 4.1、Ayatana AppIndicator 与 librsvg 运行时包具体发行版的安装命令见 cross-platform-development.mdxlauncher 会在依赖缺失时报告缺失的精确共享库。Wayland 屏幕区域采集额外要求可用的桌面 portal、PipeWire 以及libpipewire-0.3.so.0运行时库Ubuntu/Debian 新版本上由libpipewire-0.3-0t64提供。首次构建git clone --recurse-submodules 仓库地址 cd electrobun/package npm ci hutch dev:cleanpackage/目录是核心构建工作区其配置见 package/hutch.config.ts。开发工作流以下命令均从package/目录执行# 修改源码后重新构建本地 devkit 并运行 Kitchen综合测试应用 hutch dev # 让某个仓库模板针对同一份本地 package/dist 运行 hutch dev:template hello-world # 需要完全重来时 hutch dev:cleanhutch dev构建package/dist并让 Kitchen 针对该本地 devkit 运行直接从kitchen/运行hutch dev则继续使用 kitchen/hutch.config.ts 中 pin 的 Electrobun 版本。hutch dev:template template-name构建同一份本地 devkit执行模板配置的依赖安装并用这些本地产物启动它的dev任务。仓库内模板在此工作流下保持不 pin发布发布者会在暂存模板归档时注入随附的 Electrobun 版本。原生构建会为当前机器生成package/src/native/compile_flags.txtclangd 兼容的编辑器会自动发现它改动原生依赖或系统工具链后需要重新构建。如果存在同级的jsc、cottontail、dash-cloud、electrobun检出目录可以加--local同时构建并选择本地 JSC、Cottontail 与 Hutch 各层hutch dev --local。其他常用命令hutch dev:canarycanary 模式构建并运行 kitchen sink、hutch build:dev开发模式构建、hutch build:release发布模式构建。调试macOS 上对 release 构建使用lldb path-to-bundle/Contents/MacOS/launcher后执行run。生态与社区README 中列举了大量基于 Electrobun 构建的真实应用覆盖 AI 编码工作区Co(lab)、VibesOS、PiBun、音视频工具Audio TTS、FLACK、笔记与编辑器MarkBun、Sideleaf、开发工具Patchline、codex-devtools等方向仓库的 templates 目录与 kitchen 综合测试应用则是探索框架能力的入口。参与贡献前请阅读 CONTRIBUTING.md注意作者明确说明 Issues 与 PRs 可以用于分享想法但不保证会被审阅、回复或合并并参考 docs/src/content/docs/electrobun/guides/changelog/index.mdx 了解各版本演进。关于跨平台开发的深入主题热重载、UI 创建、代码签名、迁移到 v2 等均可从 docs 文档树继续深入。【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考