Back to Details

electrobun-build

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Electrobun Build

Electrobun 构建

Builds a distributable app bundle and installer for the current platform using 
electrobun build
.
使用 
electrobun build
为当前平台构建可分发的应用包和安装程序。

Build Environments

构建环境

EnvironmentCommandCodesignUpdatesPatch gen
dev
electrobun dev
NoDisabledNo
canary
electrobun build --env=canary
Yes (if configured)EnabledYes
stable
electrobun build --env=stable
Yes (if configured)EnabledYes
ELECTROBUN_BUILD_ENV
is set automatically by the CLI and passed to 
postBuild
scripts — you do not set it manually.
环境命令代码签名自动更新生成补丁
dev
electrobun dev
否禁用否
canary
electrobun build --env=canary
是（已配置时）启用是
stable
electrobun build --env=stable
是（已配置时）启用是
ELECTROBUN_BUILD_ENV
会由 CLI 自动设置并传递给 
postBuild
脚本 —— 你无需手动设置。

Platform Prerequisites

平台前置条件

macOS (Intel + Apple Silicon)

macOS（Intel + Apple Silicon）

bash
xcode-select --install   # Xcode Command Line Tools
brew install cmake
Produces: 
.dmg
installer + 
.app.tar.zst
update tarball Toolchain: 
clang++
+ 
make
+ 
install_name_tool
(all from Xcode CLT) Architectures: 
arm64
(Apple Silicon), 
x64
(Intel) — build runs on matching host
bash
xcode-select --install   # Xcode Command Line Tools
brew install cmake
产物： 
.dmg
安装包 + 
.app.tar.zst
更新 tar 包 工具链： 
clang++
+ 
make
+ 
install_name_tool
（均来自 Xcode CLT） 架构： 
arm64
（Apple Silicon）、
x64
（Intel）—— 构建在匹配的宿主机上运行

Windows

Windows

  • Visual Studio 2022 with component 
    Microsoft.VisualStudio.Component.VC.Tools.x86.x64
  • cmake (available via VS installer or standalone)
The CLI uses 
vswhere.exe
to find VS and 
vcvarsall.bat
to configure the environment automatically.
Produces: 
.exe
self-extracting installer (in a 
.zip
) + 
.tar.zst
update tarball Toolchain: 
cl.exe
+ 
link.exe
via MSVC Architecture: 
x64
only
  • Visual Studio 2022，包含组件 
    Microsoft.VisualStudio.Component.VC.Tools.x86.x64
  • cmake（可通过 VS 安装器或独立安装获得）
CLI 使用 
vswhere.exe
查找 VS，并通过 
vcvarsall.bat
自动配置环境。
产物： 
.exe
自解压安装程序（打包在 
.zip
中）+ 
.tar.zst
更新 tar 包 工具链： 通过 MSVC 使用 
cl.exe
+ 
link.exe
架构： 仅 
x64

Linux

Linux

bash
sudo apt-get install -y \
  build-essential \
  cmake \
  pkg-config \
  libgtk-3-dev \
  libwebkit2gtk-4.1-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  fuse \
  libfuse2
libfuse2
is required for AppImage creation.
Produces: 
.AppImage
+ 
.tar.zst
update tarball Toolchain: 
g++
+ 
make
+ 
pkg-config
Architectures: 
x64
, 
arm64
bash
sudo apt-get install -y \
  build-essential \
  cmake \
  pkg-config \
  libgtk-3-dev \
  libwebkit2gtk-4.1-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  fuse \
  libfuse2
创建 AppImage 需要 
libfuse2
。
产物： 
.AppImage
+ 
.tar.zst
更新 tar 包 工具链： 
g++
+ 
make
+ 
pkg-config
架构： 
x64
、
arm64

electrobun.config.ts — Build Options

electrobun.config.ts —— 构建选项

General (
build.*
)

通用配置（
build.*
）

typescript
build: {
  bun: {
    entrypoint: "src/bun/index.ts",  // default
    // + any Bun.build() options (splitting, minify, target, etc.)
  },

  views: {
    // Each key becomes the view's URL scheme: mainview://index.html
    mainview: {
      entrypoint: "src/mainview/index.ts",
      // + any Bun.build() options per view
    },
  },

  copy: {
    // Record<sourcePath, destPathInBuildOutput>
    "src/assets/icon.png": "resources/icon.png",
  },

  buildFolder:    "build",      // default: "build"
  artifactFolder: "artifacts",  // default: "artifacts"
  targets:        "current",    // default: build for host platform

  useAsar:    false,            // default: false — pack assets into ASAR archive
  asarUnpack: ["*.node", "*.dll", "*.dylib", "*.so"],  // always unpacked from ASAR

  cefVersion:  undefined,  // override bundled CEF version
  bunVersion:  undefined,  // override bundled Bun runtime version
  wgpuVersion: undefined,  // override latest electrobun-dawn release

  locales: "*",  // ICU locales to include ("*" = all); Linux/Windows only
}
typescript
build: {
  bun: {
    entrypoint: "src/bun/index.ts",  // 默认值
    // + 任意 Bun.build() 选项（splitting、minify、target 等）
  },

  views: {
    // 每个键都会成为该 view 的 URL scheme：mainview://index.html
    mainview: {
      entrypoint: "src/mainview/index.ts",
      // + 每个 view 可单独配置任意 Bun.build() 选项
    },
  },

  copy: {
    // Record<sourcePath, destPathInBuildOutput>
    "src/assets/icon.png": "resources/icon.png",
  },

  buildFolder:    "build",      // 默认值："build"
  artifactFolder: "artifacts",  // 默认值："artifacts"
  targets:        "current",    // 默认值：为宿主平台构建

  useAsar:    false,            // 默认值：false —— 将资源打包进 ASAR 归档
  asarUnpack: ["*.node", "*.dll", "*.dylib", "*.so"],  // 始终从 ASAR 中解包

  cefVersion:  undefined,  // 覆盖内置的 CEF 版本
  bunVersion:  undefined,  // 覆盖内置的 Bun 运行时版本
  wgpuVersion: undefined,  // 覆盖最新版 electrobun-dawn 发布版本

  locales: "*",  // 需要包含的 ICU locale（"*" = 全部）；仅限 Linux/Windows
}

macOS (
build.mac
)

macOS（
build.mac
）

typescript
build: {
  mac: {
    bundleCEF:       false,      // bundle CEF instead of WKWebView (~120MB)
    bundleWGPU:      false,      // bundle Dawn for native GPU rendering
    defaultRenderer: "native",   // "native" | "cef"
    codesign:        false,      // enable Apple code signing
    notarize:        false,      // enable notarization (requires codesign: true)
    icons:           undefined,  // path to .iconset folder or .icns file
    chromiumFlags:   {},         // Record<string, string|true> — CEF-only flags
    entitlements:    undefined,  // path to custom entitlements.plist
  }
}
typescript
build: {
  mac: {
    bundleCEF:       false,      // 打包 CEF 而非使用 WKWebView（约 120MB）
    bundleWGPU:      false,      // 打包 Dawn 以启用原生 GPU 渲染
    defaultRenderer: "native",   // "native" | "cef"
    codesign:        false,      // 启用 Apple 代码签名
    notarize:        false,      // 启用公证（需要 codesign: true）
    icons:           undefined,  // .iconset 文件夹或 .icns 文件路径
    chromiumFlags:   {},         // Record<string, string|true> —— 仅 CEF 可用
    entitlements:    undefined,  // 自定义 entitlements.plist 路径
  }
}

Windows (
build.win
)

Windows（
build.win
）

typescript
build: {
  win: {
    bundleCEF:     false,     // CEF is always needed on Windows (no OS webview)
    bundleWGPU:    false,     // bundle Dawn
    icons:         undefined, // path to .ico file
    chromiumFlags: {},        // CEF Chromium flags
  }
}
typescript
build: {
  win: {
    bundleCEF:     false,     // Windows 上始终需要 CEF（没有系统 webview）
    bundleWGPU:    false,     // 打包 Dawn
    icons:         undefined, // .ico 文件路径
    chromiumFlags: {},        // CEF Chromium 标志
  }
}

Linux (
build.linux
)

Linux（
build.linux
）

typescript
build: {
  linux: {
    bundleCEF:     false,     // bundle CEF instead of GTKWebKit
    bundleWGPU:    false,     // bundle Dawn
    icons:         undefined, // icon file path
    chromiumFlags: {},        // CEF Chromium flags
  }
}
Linux multi-view note: GTKWebKit is the default system webview. For apps with multiple views or needing consistent rendering, 
bundleCEF: true
is strongly recommended.
typescript
build: {
  linux: {
    bundleCEF:     false,     // 打包 CEF 而非使用 GTKWebKit
    bundleWGPU:    false,     // 打包 Dawn
    icons:         undefined, // 图标文件路径
    chromiumFlags: {},        // CEF Chromium 标志
  }
}
Linux 多 view 说明： GTKWebKit 是默认的系统 webview。对于包含多个 view 或需要一致渲染表现的应用，强烈建议设置 
bundleCEF: true
。

Code Signing (macOS)

代码签名（macOS）

Code signing runs automatically when 
build.mac.codesign: true
and 
ELECTROBUN_DEVELOPER_ID
is set. It only runs when 
buildEnvironment !== "dev"
, host OS is macOS, and target OS is macOS.
当 
build.mac.codesign: true
且设置了 
ELECTROBUN_DEVELOPER_ID
时会自动执行代码签名。仅在 
buildEnvironment !== "dev"
、宿主系统为 macOS 且目标系统为 macOS 时运行。

Signing Order

签名顺序

  1. CEF framework internals (if 
    bundleCEF: true
    )
  2. CEF helper applications
  3. All 
    .dylib
    files and executables inside 
    MacOS/
    recursively
  4. The 
    launcher
    executable
  5. The entire 
    .app
    bundle
  6. The 
    .dmg
    installer
  1. CEF framework 内部文件（当 
    bundleCEF: true
    时）
  2. CEF helper 应用
  3. MacOS/
    目录下递归的所有 
    .dylib
    文件和可执行文件
  4. launcher
    可执行文件
  5. 整个 
    .app
    应用包
  6. .dmg
    安装包

Required Environment Variables

必需的环境变量

bash
export ELECTROBUN_DEVELOPER_ID="Developer ID Application: Your Name (TEAMID)"
bash
export ELECTROBUN_DEVELOPER_ID="Developer ID Application: Your Name (TEAMID)"

Notarization (requires codesign: true)

公证（需要 codesign: true）

export ELECTROBUN_APPLEID="you@example.com" export ELECTROBUN_APPLEIDPASS="xxxx-xxxx-xxxx-xxxx" # app-specific password export ELECTROBUN_TEAMID="ABCDE12345"
undefined
export ELECTROBUN_APPLEID="you@example.com" export ELECTROBUN_APPLEIDPASS="xxxx-xxxx-xxxx-xxxx" # 应用专用密码 export ELECTROBUN_TEAMID="ABCDE12345"
undefined

Notarization Sequence

公证流程

  1. .app
    bundle zipped
  2. xcrun notarytool submit --wait
    — blocks until Apple responds
  3. On success: 
    xcrun stapler staple
    attaches ticket to bundle
  4. .dmg
    created, then also code-signed and notarized
  1. .app
    应用包压缩
  2. xcrun notarytool submit --wait
    —— 阻塞直到 Apple 返回结果
  3. 成功后：
    xcrun stapler staple
    将票据附加到应用包
  4. 生成 
    .dmg
    ，随后同样进行代码签名和公证

Artifact Output

产物输出

All artifacts land in 
artifacts/
(or 
build.artifactFolder
).
所有产物都会落在 
artifacts/
（或 
build.artifactFolder
）目录中。

Naming Convention: 
{channel}-{os}-{arch}-{filename}

命名约定：
{channel}-{os}-{arch}-{filename}

PlatformInstallerUpdate TarballManifest
macOS stable arm64
MyApp.dmg
stable-macos-arm64-MyApp.app.tar.zst
stable-macos-arm64-update.json
macOS canary arm64
MyApp-canary.dmg
canary-macos-arm64-MyApp-canary.app.tar.zst
canary-macos-arm64-update.json
macOS stable x64
MyApp.dmg
stable-macos-x64-MyApp.app.tar.zst
stable-macos-x64-update.json
Windows stable x64
MyApp-Setup.zip
stable-win-x64-MyApp.tar.zst
stable-win-x64-update.json
Windows canary x64
MyApp-Setup-canary.zip
canary-win-x64-MyApp-canary.tar.zst
canary-win-x64-update.json
Linux stable x64
MyApp-Setup.AppImage
stable-linux-x64-MyApp.tar.zst
stable-linux-x64-update.json
Linux canary arm64
MyApp-Setup-canary.AppImage
canary-linux-arm64-MyApp-canary.tar.zst
canary-linux-arm64-update.json
Patch files: 
{channel}-{os}-{arch}-{fromHash}.patch
(generated if previous tarball available)
平台安装包更新 tar 包Manifest
macOS stable arm64
MyApp.dmg
stable-macos-arm64-MyApp.app.tar.zst
stable-macos-arm64-update.json
macOS canary arm64
MyApp-canary.dmg
canary-macos-arm64-MyApp-canary.app.tar.zst
canary-macos-arm64-update.json
macOS stable x64
MyApp.dmg
stable-macos-x64-MyApp.app.tar.zst
stable-macos-x64-update.json
Windows stable x64
MyApp-Setup.zip
stable-win-x64-MyApp.tar.zst
stable-win-x64-update.json
Windows canary x64
MyApp-Setup-canary.zip
canary-win-x64-MyApp-canary.tar.zst
canary-win-x64-update.json
Linux stable x64
MyApp-Setup.AppImage
stable-linux-x64-MyApp.tar.zst
stable-linux-x64-update.json
Linux canary arm64
MyApp-Setup-canary.AppImage
canary-linux-arm64-MyApp-canary.tar.zst
canary-linux-arm64-update.json
补丁文件： 
{channel}-{os}-{arch}-{fromHash}.patch
（在存在上一个 tar 包时生成）

update.json
Contents

update.json
内容

json
{
  "version":  "1.0.0",
  "hash":     "<sha256-of-uncompressed-tarball>",
  "platform": "macos",
  "arch":     "arm64"
}
json
{
  "version":  "1.0.0",
  "hash":     "<sha256-of-uncompressed-tarball>",
  "platform": "macos",
  "arch":     "arm64"
}

version.json
Inside the App Bundle

应用包内的 
version.json

macOS:   MyApp.app/Contents/Resources/version.json
Windows: MyApp/Resources/version.json
Linux:   MyApp/Resources/version.json
json
{
  "version":    "1.0.0",
  "hash":       "<content-hash>",
  "channel":    "stable",
  "baseUrl":    "https://updates.example.com/",
  "name":       "MyApp",
  "identifier": "com.example.myapp"
}
macOS:   MyApp.app/Contents/Resources/version.json
Windows: MyApp/Resources/version.json
Linux:   MyApp/Resources/version.json
json
{
  "version":    "1.0.0",
  "hash":       "<content-hash>",
  "channel":    "stable",
  "baseUrl":    "https://updates.example.com/",
  "name":       "MyApp",
  "identifier": "com.example.myapp"
}

Environment Variables Reference

环境变量参考

Set by Electrobun CLI — passed to 
postBuild
scripts

由 Electrobun CLI 设置 —— 传递给 
postBuild
脚本

VariableExample
ELECTROBUN_BUILD_ENV
"dev"
/ 
"canary"
/ 
"stable"
ELECTROBUN_OS
"macos"
/ 
"win"
/ 
"linux"
ELECTROBUN_ARCH
"arm64"
/ 
"x64"
ELECTROBUN_BUILD_DIR
/abs/path/to/build/
ELECTROBUN_APP_NAME
"MyApp"
ELECTROBUN_APP_VERSION
"1.0.0"
ELECTROBUN_APP_IDENTIFIER
"com.example.myapp"
ELECTROBUN_ARTIFACT_DIR
/abs/path/to/artifacts/
变量示例
ELECTROBUN_BUILD_ENV
"dev"
/ 
"canary"
/ 
"stable"
ELECTROBUN_OS
"macos"
/ 
"win"
/ 
"linux"
ELECTROBUN_ARCH
"arm64"
/ 
"x64"
ELECTROBUN_BUILD_DIR
/abs/path/to/build/
ELECTROBUN_APP_NAME
"MyApp"
ELECTROBUN_APP_VERSION
"1.0.0"
ELECTROBUN_APP_IDENTIFIER
"com.example.myapp"
ELECTROBUN_ARTIFACT_DIR
/abs/path/to/artifacts/

Set by you — version and runtime overrides

由你设置 —— 版本与运行时覆盖

VariablePurpose
ELECTROBUN_CEF_VERSION
Override CEF version without editing config
ELECTROBUN_BUN_VERSION
Override Bun runtime version
ELECTROBUN_CONSOLE=1
Force console output on Windows in production
ELECTROBUN_SKIP_CODESIGN
does not exist. Code signing is controlled by 
config.build.mac.codesign
and 
buildEnvironment
.
变量用途
ELECTROBUN_CEF_VERSION
无需修改配置即可覆盖 CEF 版本
ELECTROBUN_BUN_VERSION
覆盖 Bun 运行时版本
ELECTROBUN_CONSOLE=1
在生产环境的 Windows 上强制开启控制台输出
ELECTROBUN_SKIP_CODESIGN
并不存在。 代码签名由 
config.build.mac.codesign
和 
buildEnvironment
控制。

GitHub Actions CI/CD Matrix

GitHub Actions CI/CD 矩阵

Official runners used by Electrobun's own release workflow:
yaml
strategy:
  matrix:
    include:
      - runner: macos-14           # Apple Silicon
        arch: arm64
      - runner: macos-15-intel     # Intel
        arch: x64
      - runner: ubuntu-24.04       # Linux x64
        arch: x64
      - runner: ubuntu-24.04-arm   # Linux ARM64
        arch: arm64
      - runner: windows-2025       # Windows x64
        arch: x64
Electrobun 自身发布工作流所使用的官方 runner：
yaml
strategy:
  matrix:
    include:
      - runner: macos-14           # Apple Silicon
        arch: arm64
      - runner: macos-15-intel     # Intel
        arch: x64
      - runner: ubuntu-24.04       # Linux x64
        arch: x64
      - runner: ubuntu-24.04-arm   # Linux ARM64
        arch: arm64
      - runner: windows-2025       # Windows x64
        arch: x64

Required GitHub Secrets

必需的 GitHub Secrets

SecretPurpose
MACOS_CERTIFICATE
Base64-encoded .p12 certificate
MACOS_CERTIFICATE_PWD
Certificate password
ELECTROBUN_DEVELOPER_ID
Apple Developer ID string
ELECTROBUN_APPLEID
Apple ID email
ELECTROBUN_APPLEIDPASS
App-specific password
ELECTROBUN_TEAMID
Apple Team ID
R2_ENDPOINT
Cloudflare R2 endpoint URL
R2_ACCESS_KEY_ID
R2 access key
R2_SECRET_ACCESS_KEY
R2 secret key
R2_BUCKET
R2 bucket name
NODE_AUTH_TOKEN
npm publish token
Secret用途
MACOS_CERTIFICATE
Base64 编码的 .p12 证书
MACOS_CERTIFICATE_PWD
证书密码
ELECTROBUN_DEVELOPER_ID
Apple Developer ID 字符串
ELECTROBUN_APPLEID
Apple ID 邮箱
ELECTROBUN_APPLEIDPASS
应用专用密码
ELECTROBUN_TEAMID
Apple Team ID
R2_ENDPOINT
Cloudflare R2 endpoint URL
R2_ACCESS_KEY_ID
R2 access key
R2_SECRET_ACCESS_KEY
R2 secret key
R2_BUCKET
R2 bucket 名称
NODE_AUTH_TOKEN
npm publish token

macOS Certificate Import Step

macOS 证书导入步骤

yaml
- name: Install Apple Certificate
  run: |
    echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
    security create-keychain -p "" build.keychain
    security import certificate.p12 -k build.keychain \
      -P $MACOS_CERTIFICATE_PWD -T /usr/bin/codesign
    security list-keychains -d user -s build.keychain
    security set-keychain-settings -t 3600 -u build.keychain
    security unlock-keychain -p "" build.keychain
yaml
- name: Install Apple Certificate
  run: |
    echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
    security create-keychain -p "" build.keychain
    security import certificate.p12 -k build.keychain \
      -P $MACOS_CERTIFICATE_PWD -T /usr/bin/codesign
    security list-keychains -d user -s build.keychain
    security set-keychain-settings -t 3600 -u build.keychain
    security unlock-keychain -p "" build.keychain

Common Build Failures

常见构建失败

ErrorCauseFix
View URL not foundConfig key doesn't match 
src/
dir name
views: { mainview: ... }
→ URL must be 
mainview://index.html
Blank windowScript tag points to 
.ts
not compiled 
.js
Use 
index.js
in HTML
Codesign fails locallyCertificate not in keychainRun 
security find-identity -v -p codesigning
Notarization failsHardened runtime without JIT entitlementAdd 
com.apple.security.cs.allow-jit
to entitlements.plist
Linux AppImage won't runFUSE missing
apt-get install fuse libfuse2
Windows MSVC not foundVS component missingInstall 
VC.Tools.x86.x64
component via VS Installer
CEF build failscmake not installedInstall cmake for the platform
libwebgpu_dawn.dylib
not found
bundleWGPU
not set		Set 
build.mac.bundleWGPU: true
in config
WGPU GC crash after framesFFI objects not pinnedPush all GPU objects to 
KEEPALIVE
array
错误原因修复方式
View URL 未找到配置键与 
src/
目录名不匹配
views: { mainview: ... }
→ URL 必须为 
mainview://index.html
窗口空白script 标签指向 
.ts
而非编译后的 
.js
在 HTML 中使用 
index.js
本地代码签名失败证书不在 keychain 中运行 
security find-identity -v -p codesigning
公证失败启用了 hardened runtime 但缺少 JIT entitlement在 entitlements.plist 中添加 
com.apple.security.cs.allow-jit
Linux AppImage 无法运行缺少 FUSE
apt-get install fuse libfuse2
找不到 Windows MSVC缺少 VS 组件通过 VS Installer 安装 
VC.Tools.x86.x64
组件
CEF 构建失败未安装 cmake为该平台安装 cmake
找不到 
libwebgpu_dawn.dylib
未设置 
bundleWGPU
在配置中设置 
build.mac.bundleWGPU: true
渲染若干帧后 WGPU GC 崩溃FFI 对象未被固定将所有 GPU 对象放入 
KEEPALIVE
数组