Electrobun 开发构建指南基于 Hutch 的编译流程与仓库结构全解析【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobunElectrobun 2 是一套以 TypeScript 构建跨平台桌面应用的框架本指南围绕仓库根目录下的 CLAUDE.md 开发者规范系统讲解它的构建命令、自动化流程与目录组织。读完本文你将掌握从npm ci到hutch dev的完整本地开发链路理解为什么绝不能从 node_modules 运行 Electrobun并能对照源码看懂每次构建背后依次发生了什么。核心约定Hutch 是唯一的构建入口Electrobun 2 的一个关键设计约束写在了文档开头的加粗提示中NEVER run Electrobun fromnode_modules。这与许多传统 npm 包的使用方式截然相反原因在于Electrobun 2 采用Hutch作为构建 CLI负责编排原生层、TypeScript 层与运行时内核的完整编译npm 在该仓库中仅用于安装固定的开发依赖开发仓库根目录的package/package.json中devDependencies仅声明了typescriptdependencies为types/bun、png-to-ico、proxy-agent、rcedit等构建期辅助库仓库版本为2.0.2-beta.25其 package/hutch.config.ts 文件首行带有版本固定注释// hutch cli0.27.0-canary.7 cottontail0.7.0-canary.8即构建工具链版本被精确钉死不由 npm 解析。因此所有构建动作都必须从package目录发起由 Hutch 统一调度。构建与运行命令详解环境准备npm cinpm ci该命令在package目录下执行按照package-lock.json安装仓库钉死的开发依赖。从 package/hutch.config.ts 可以看到仓库将安装动作也收敛到了 Hutch脚本install: [hutch, pm, ci]即通过hutch pm ci完成依赖解析进一步保证构建环境的确定性。开发模式hutch devhutch dev这是最常用的命令构建并运行 Kitchen 应用仓库的测试应用 Kitchen Sink的 dev 模式。命令的实际编排逻辑位于 package/scripts/dev.ts其createDevCommands()按顺序生成三个子命令Build Electrobun packagehutch package/build.ts在package目录执行Install Kitchen dependencies在kitchen目录执行npm installWindows 上通过cmd.exe /D /S /C npm.cmd install调用Launch Kitchen development apphutch electrobun dev在kitchen目录执行并注入关键环境变量HUTCH_ELECTROBUN_DEVKIT_ROOTpackage/dist让 Kitchen 直接指向本次本地构建出的 devkit而不是发布版产物。该脚本还支持--local参数hutch dev --local会跳过 package 自身的重新构建skipPackageBuild: true直接使用已有的本地产物启动。针对模板开发hutch dev:template template-namehutch dev:template template-name该命令从本地 devkit 构建并运行某个仓库模板用于验证templates/目录下各类示例工程如hello-world、react-tailwind-vite、wgpu-babylon等 30 余个模板与当前开发版本的兼容性。其实现见 package/scripts/dev-template.ts流程比普通 dev 更严谨完整步骤为解析模板名parseTemplateName()要求恰好一个参数否则报错Usage: hutch dev:template template-name校验模板存在availableTemplateNames()扫描templates/目录只有同时包含hutch.config.ts与electrobun.config.ts的子目录才被认为是合法模板并给出可用模板列表读取 package 版本与 Hutch 钉版通过readPackageVersion()读取package/package.json的版本并通过readPackageHutchPins()解析 package/hutch.config.ts 首行// hutch注释中的cli/cottontail精确版本钉版——注意该文件必须以该 pragma 开头这是硬性约定定位 Hutch 引擎hutch self path cli-version解析出与钉版匹配的引擎可执行文件组装本地 devkit 环境向模板命令注入HUTCH_ELECTROBUN_DEVKIT_ROOT、HUTCH_DEFAULT_ELECTROBUN、HUTCH_DEFAULT_CLI、HUTCH_ENGINE_BINARY四个环境变量执行构建计划executeTemplateDevPlan()依次执行 build → 校验 devkit 产物版本与 package 版本一致 → 校验模板实际选用的 Hutch CLI / Cottontail 版本与钉版一致 → 安装模板依赖 → 以 dev 模式启动模板。整个链路把版本漂移风险前置到了构建入口只要模板选中的 Hutch 版本与 package 钉版不一致构建会立即失败并明确报错。金丝雀模式hutch dev:canaryhutch dev:canary以 canary 环境构建 Kitchen 应用。该命令在 package/package.json 中展开为hutch run install hutch build:release cd ../kitchen hutch run install hutch electrobun build --envcanary即安装 package 依赖以 release 配置构建 package安装 Kitchen 依赖在 Kitchen 中以--envcanary构建应用。对应地Kitchen 的 kitchen/hutch.config.ts 中还提供了build:stable--envstable、start:canaryhutch electrobun dev --envcanary等配套脚本用于区分 canary / stable 两套发布环境。其他常用脚本仓库在 package/package.json 与 package/hutch.config.ts 中登记了大量开发脚本值得关注的有脚本作用hutch build.ts/hutch build.ts --release构建 dev / release 配置的 packagebuild:dev/build:releasehutch run typecheck先构建 preload再以tsc --noEmit做全量类型检查hutch run test:unit运行 TypeScript 单元测试Cottontail 测试运行器及 Linux 原生层测试hutch run check:release发布前的整体检查版本、产物、manifest 等hutch run dev:matrix/matrix:full在 Kitchen 中跑多平台/多配置构建矩阵hutch run pin:latest将 Hutch CLI / Cottontail 钉版递归同步到最新并固定hutch run push:patch\|minor\|major\|stable\|beta发布版本推进均先执行check:releaseKitchen 侧kitchen/hutch.config.ts还提供package-boundary:test、check:zig-mirrors、check:odin-mirrors等专项校验分别验证 package 边界不被破坏、Zig/Odin 测试镜像与源码一致。构建流程全景一次hutch dev内部发生了什么文档描述的标准构建流程为四步与源码实现完全对应见 package/scripts/dev.tsBuild the native wrappers ↓ Compile the TypeScript code ↓ Build the versioned core and devkit ↓ Switch to the kitchen folder and build/run the app第 1 步构建原生包装层Native WrappersElectrobun 依赖 CEFChromium Embedded Framework承载渲染层因此需要为各平台编译原生包装代码。仓库中对应目录为package/src/native/linuxcef_loader.cpp、nativeWrapper.cpp、wayland_screen_capture.cpp等package/src/native/macosnativeWrapper.mm、cef_process_helper_mac.cc、spell_check.h等package/src/native/winWindows 侧包装代码package/src/native/shared跨平台共享头文件如callbacks.h、config.h、mime_types.h、accelerator_parser.h等。第 2 步编译 TypeScript 代码将package/src/sdks/main、package/src/browser、package/src/preload等 TypeScript 源码编译为 devkit 的 API 产物。package/package.json的exports字段展示了最终 API 形态./mainBun 主进程入口、./view浏览器侧入口、./main/ui/jsx-runtime声明式 UI 的 JSX 运行时、./main/updater、./main/tray、./main/webgpu等 60 余个导出条目。第 3 步构建带版本的核心与 devkit核心运行时由 Zig 实现位于 package/src/core/main.zig约 4400 行负责事件循环、动态库加载、CEF 宿主进程等底层能力。该步会产出带版本号的 core 与 devkit供 Kitchen 与模板通过HUTCH_ELECTROBUN_DEVKIT_ROOT引用。从源码看core 会读取ELECTROBUN_INSTALL_ROOT_NAME环境变量做安装根目录名校验isSafeInstallRootName()会拒绝空值、.、..、路径分隔符及 Windows 下的保留字符这属于安装/运行期安全边界的一部分。第 4 步切到 Kitchen 构建并运行应用最后Hutch 切到kitchen目录按 kitchen/hutch.config.ts 的配置构建并启动 Kitchen 应用。Kitchen 作为厨房水槽测试应用其src/tests/下包含 40 余个交互与单元测试如webview-tag.test.ts、wgpu-tag.test.ts、menus.test.ts、tray.test.ts是验证框架能力的核心载体。仓库结构全景文档给出的项目结构可以用以下仓库相对路径对应文档描述仓库实际位置职责/packagepackage/Electrobun 主包源码构建脚本、SDK、原生层、核心、提取器/kitchenkitchen/Kitchen Sink 测试应用含 playgrounds 与全量测试套件/npm/electrobunnpm/electrobun/无依赖的 npm bootstrap 包/package/src/sdkspackage/src/sdks/随 devkit 发布的多语言 SDKmain/TypeScript 103 个文件、go、odin、rust、zig/package/src/extractorpackage/src/extractor/Zig 实现的自解压器含 Linux/macOS/Windows 卸载提示组件/package/src/nativepackage/src/native/各平台原生包装层补充/npm/electrobun的 bootstrap 机制文档对该目录的描述值得展开npm/electrobun/package.json 声明了一个名为electrobun的 npm 包版本与主仓库同步为2.0.2-beta.25engines.node 18其设计目标是单一、无依赖的 npm bootstrap提供bin/electrobun.cjs作为 CLI 入口安装时不携带任何平台 npm 包也没有 postinstall 脚本files仅包含 bin 与 lib 下的moved.cjs等少量文件首次运行时它读取同版本 GitHub Release 中的hutch-artifacts.json下载并校验配对的 host 归档然后安全缓存并调用解压出的 Hutch launcher。这意味着用户通过 npm 安装到的只是一个极小的启动器真正的构建引擎由 bootstrap 按版本从 Release 获取——这是仓库对npm 仅做开发依赖管理原则的对外延伸。开发工作流实践建议永远在package目录发起构建hutch dev、hutch dev:template、hutch build:release等都以该目录为工作基准Kitchen 侧命令hutch electrobun dev等才在 kitchen/ 目录执行。不要手动npm install主包依赖安装统一走hutch pm ci即npm ci的 Hutch 封装保证锁文件与钉版一致。调试模板前先跑hutch dev:template它比手写步骤多出版本一致性校验能在模板与 devkit 不匹配时第一时间暴露问题省去排查环境漂移的时间。版本敏感操作走固定脚本升级 Hutch 工具链用pin:latest并同步 package/src/shared/strict-semver.js 相关测试推进版本走push:patch等脚本内部强制先过check:release避免绕过发布校验。理解 canary / stable 语义Kitchen 的--envcanary与--envstable对应不同构建配置发布前的金丝雀验证应使用 kitchen/hutch.config.ts 中的build:canary/build:stable脚本。小结Electrobun 2 的构建体系以Hutch 统一编排 npm 仅管开发依赖为设计主轴hutch dev一条命令串联起原生包装、TypeScript 编译、版本化 core/devkit 与 Kitchen 应用四个阶段而hutch dev:template进一步把模板与本地 devkit 的版本一致性检查前置到构建入口。理解这份流程是高效参与本仓库开发与排查构建问题的基础配合 package/scripts/dev.ts、package/scripts/dev-template.ts 与 package/hutch.config.ts 阅读即可把文档中的命令映射为源码级的执行细节。【免费下载链接】electrobunBuild ultra fast, tiny, and cross-platform desktop apps with Typescript.项目地址: https://gitcode.com/GitHub_Trending/el/electrobun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考