用途：把已有的 Bun Web 服务器封装成原生桌面应用，基于已验证的实现，覆盖集成中的主要难点。
架构：Electron 负责窗口管理、原生菜单、自动更新与 IPC；Bun 运行实际 Web 服务器。Electron 主进程启动打包的 Bun 二进制运行服务器，再在 BrowserWindow 中加载 http://localhost:{port}。Web 应用无需感知 Electron，仅通过可选的 window.electronAPI 桥接原生功能。服务端代码零改动，浏览器与 Electron 中行为一致；Electron 与 Web 应用各自使用独立的 node_modules（前者 npm，后者 Bun）。
主要能力分四阶段：一、项目搭建，在现有 Bun 应用旁创建 electron/ 子项目，含独立 package.json、ESM 主进程与 CJS preload 两套 tsconfig、electron-builder.yml、macOS entitlements，以及打包服务器和下载平台专属 Bun 二进制的脚本。二、主进程，包含应用生命周期、单实例锁、IPC、Bun 进程启动与端口选择、健康轮询、窗口配置与边界持久化、electron-updater 自动更新、contextBridge 预加载桥。三、Web 应用适配，加入 Electron 检测工具、类型声明、CSS 拖拽区域、macOS 红绿灯间距变量、存储与静态资源路径环境变量、自动更新 React hook 与更新提示组件、功能开关。四、构建与分发，打包服务器为单文件、下载 Bun 二进制、两遍编译 TypeScript、electron-builder 打包；CI/CD 由版本标签触发，矩阵构建 macOS arm64/x64 与 Windows x64，构建步骤用 --publish never，另设发布任务创建草稿 GitHub 发布，并在 CI 中导入 Apple 证书与公证。
使用方式：开发时 electron:dev 通过 concurrently 同时启动 Bun 开发服务器（HMR）与 Electron，Electron 经 ELECTRON_DEV_URL 连接外部开发服务器而非自行启动 Bun；preload 与主进程改动需重启，Web 改动自动热重载。本地可用 bun run electron:pack 测试类生产行为。发布时先在 electron/package.json 升版本并合并到 main，用 grep -A2 'tags:' .github/workflows/*.yml 查找标签模式，再 git tag <pattern><version> origin/main 并推送，用 gh run list --workflow=<workflow>.yml --limit=1 监控 CI，最后在 GitHub 审核并发布草稿。
限制与注意：切勿本地构建发布产物，本地构建未签名会被 macOS Gatekeeper 拦截；需 5 个 GitHub secrets（APPLE_CERTIFICATE、APPLE_CERTIFICATE_PASSWORD、APPLE_ID、APPLE_PASSWORD、APPLE_TEAM_ID）。常见坑包括 ESM/CJS 冲突、preload 必须为 CJS、__dirname 不可用、开发模式 MIME 错误、Bun 版本不匹配、nvm PATH 问题、存储路径错误、打开白屏闪烁、平台变量与 process.platform 不一致、Bun workspace 依赖提升、本地构建未公证等。适配新项目时需更新应用名、窗口标题、开发端口、环境变量名、背景色、分类、仓库 URL、Bun 版本与图标资源。