企业官网建设流程全解析

Electrobun 开发指南：用 TypeScript 构建轻量级跨平台桌面应用

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

Electrobun 是一套面向 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、下载被锁定的编译器工具链，并产出可分发的安装包（在配置签名时会顺带完成签名）。
• Cottontail：Electrobun 默认的 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-canary：

curl -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 --template=hello-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.json

src/下的目录划分忠实反映了应用的真实运行方式：

• 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.ts：

export default { scripts: { install: ["hutch", "install", "--frozen-lockfile"], start: ["hutch", "electrobun", "dev"], dev: ["hutch", "electrobun", "dev", "--watch"], build: ["hutch", "electrobun", "build", "--env=stable"], }, };

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.ts：

import 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，用于访问打包进应用内的资源。

Devkit：SDK 从哪里来

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 构建环境共有三个：dev、canary、stable。

包管理边界

没有packageManager配置时，hutch install使用 Hutch 内置的npm 兼容解析器：它处理package.json的 registry、file:与 git 依赖（github:owner/repo#ref与git+<url>#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 的职责边界非常清晰：

所有构建相关的东西都不会进入发给用户的运行时。一个值得注意的细节是：构建期 Cottontail（用于加载配置、运行脚本的那份）与 Hutch 发布版本配对，由hutch upgrade一起升级；而build.mainProcess: "cottontail"打进应用包里的那份由所选 Electrobun devkit 单独 pin，互不继承。Cottontail 的完整介绍见 Cottontail 指南。

如果你的应用确实依赖真实的 Bun 运行时，把build.mainProcess设为"bun"即可——Hutch 仍然是构建工具。

构建与分发：一条命令产出全部发布物

hutch electrobun build --env=canary hutch electrobun build --env=stable

一次构建同时产出：可运行的 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>.patch

Windows x64 与 Linux x64 的产物结构类似（Windows 是包含安装程序的 zip，Linux 是含自解压安装器的.tar.gz），stable 安装器文件名不带渠道前缀与-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-wgpu>HTML 元素：允许你在 UI 中像普通元素一样合成隔离的 webview 与原生 GPU 表面。元素实现见 package/src/browser/webviewtag.ts 与 package/src/browser/wgputag.ts，API 文档见 electrobun-webview-tag.mdx。

设计目标：五条核心原则

README 明确列出了项目的设计目标，它们也解释了上述特性为何存在：

1. 主进程与 webview 都用 TypeScript 写，无需操心底层差异。
2. 主进程与 webview 进程隔离，通过快速、类型安全、易于实现的 RPC 通信——"被攻破或有 bug 的视图无法触及它从未被授予的权限"。
3. 使用系统 webview 时，应用包体积小（自解压小 bundle）。
4. 小更新优先用二进制补丁，失败时回退到压缩全量下载。
5. 提供一个紧密集成的完整工作流：5 分钟开始写代码，10 分钟完成分发。

进程模型上，主进程持有应用状态与原生对象，每个浏览器视图与之隔离，仅通过 RPC 与事件桥通信——你获得了 Web UI 的便利，却不会把特权主进程 API 暴露给页面 JavaScript。RPC 的底层实现与测试可参考 package/src/shared/rpc.ts 与 package/src/shared/rpc.test.ts。

平台支持矩阵

注意：Electrobun 当前的发布矩阵不发布 macOS x64 核心产物；Windows ARM 通过系统仿真使用 x64 产物。

从源码构建 Electrobun（为贡献者准备）

用模板开发应用只需要安装 Hutch；本节是为想从源码构建 Electrobun 以贡献修复的开发者准备的。

各平台前置条件

macOS：需要 Xcode command line tools 与 cmake（brew 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-dev

Linux 端用户系统还需要对应的 GTK 3、WebKitGTK 4.1、Ayatana AppIndicator 与 librsvg 运行时包，具体发行版的安装命令见 cross-platform-development.mdx；launcher 会在依赖缺失时报告缺失的精确共享库。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:clean

package/目录是核心构建工作区，其配置见 package/hutch.config.ts。

开发工作流

以下命令均从package/目录执行：

# 修改源码后重新构建本地 devkit 并运行 Kitchen（综合测试应用） hutch dev # 让某个仓库模板针对同一份本地 package/dist 运行 hutch dev:template hello-world # 需要完全重来时 hutch dev:clean

• hutch 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.txt，clangd 兼容的编辑器会自动发现它；改动原生依赖或系统工具链后需要重新构建。
• 如果存在同级的jsc、cottontail、dash-cloud、electrobun检出目录，可以加--local同时构建并选择本地 JSC、Cottontail 与 Hutch 各层：hutch dev --local。

其他常用命令：hutch dev:canary（canary 模式构建并运行 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