electrobun.config.ts

Electrobun 的 TypeScript 配置入口，用来集中声明桌面应用的 app 信息、构建参数、平台差异、复制规则和发布配置。

作用

统一管理 Electrobun 项目的构建与发布行为
以 TypeScript + satisfies ElectrobunConfig 提供类型检查
配合 package.json 脚本驱动 electrobun dev / electrobun build

常见配置块

配置块	作用
`app`	应用名、标识、版本、图标等元信息
`runtime`	窗口生命周期、退出策略等运行时行为
`build.bun`	主进程/后端入口，透传 `Bun.build()` 相关选项
`build.views`	webview/前端入口与打包参数
`build.copy`	静态资源复制规则
`build.watch`	额外监听路径
`release`	更新地址、分发相关配置
`mac` / `linux` / `win`	平台专属选项，如签名、`bundleCEF`、notarize

build 配置详解

build 是配置里字段最多的一块，按用途可以分成几组：

入口与主进程

字段	说明
`build.mainProcess`	主进程实现语言，`"bun"`（默认）/`"zig"`/`"rust"`/`"go"`/`"cottontail"`
`build.bun` / `build.zig` / `build.rust` / `build.go`	对应语言主进程的入口配置，`entrypoint` 默认 `src/bun/index.ts` 等；`bun`/`cottontail` 额外透传 `Bun.build()` 的 `plugins`/`define`/`sourcemap`/`minify`/`splitting` 等选项
`build.views`	webview 前端入口表，`{ [viewName]: { entrypoint, ...Bun.build 选项 } }`

关于 mainProcess: "go"/"rust"/"zig" 的说明：Electrobun 的默认主进程就是 Bun（TS/JS），这是绝大多数项目该用的路径，DX 最好、和 webview 通信最省心。go/rust/zig 是给需要原生性能或底层能力的场景准备的替代选项——官方仓库自带 go-maze-wgpu、rust-flock-wgpu 两个真实可跑的模板，都是用 Go/Rust 主进程直接通过 cgo/FFI 调 WebGPU（Dawn）做 3D 渲染，绕开 Bun 的 JS 运行时开销。属于”性能敏感/游戏引擎级”场景才会用到的进阶选项，不是主流用法；普通桌面应用（表单、CRUD、设置面板等）用默认 bun 就够。

静态资源与监听

字段	说明
`build.copy`	构建时直接复制文件/目录到输出产物，格式 `{ [源路径]: 目标路径 }`。用于图标、字体、非代码静态资源等不需要走打包流程的文件
`build.watch`	`electrobun dev --watch` 模式下额外监听的路径数组（默认只监听入口和 copy 来源目录），适合会影响构建但没被声明为 entrypoint/copy 源的文件
`build.watchIgnore`	glob 匹配的忽略规则数组，命中的文件变化不会触发重新构建。`build/`、`artifacts/`、`node_modules/` 已经被自动忽略，不需要重复声明

build: {
  copy: {
    "assets/icon.png": "Resources/icon.png",
    "src/locales": "Resources/locales",
  },
  watch: ["shared-config.json"],
  watchIgnore: ["**/*.test.ts", "**/*.md"],
}

copy 是”构建阶段单向复制”，不参与打包和类型检查；watch/watchIgnore 只影响 --watch 模式下”什么文件变化算触发重建”，不影响产物内容本身。

输出与打包

字段	说明
`build.buildFolder`	构建产物输出目录，默认 `build`
`build.artifactFolder`	分发产物（安装包等）输出目录，默认 `artifacts`
`build.targets`	编译目标平台，`"current"` / `"all"` / 逗号分隔列表（如 `"macos-arm64,win-x64"`）
`build.useAsar`	是否把 Resources 目录打包进 `app.asar` 归档，默认 `false`
`build.asarUnpack`	`useAsar` 开启时，哪些 glob 模式的文件排除在 asar 外单独存放（默认 `.node`/`.dll`/`.dylib`/`.so`，原生模块需要以真实文件形式存在）

依赖版本覆盖

字段	说明
`build.cefVersion` / `build.wgpuVersion` / `build.bunVersion`	分别覆盖内置 CEF / Dawn(WebGPU) / Bun 运行时的版本，不填则用 Electrobun 当前发行版自带的版本
`build.locales`	Linux/Windows 下 ICU 数据文件包含的语言，`'*'`（全部，默认）或指定子集如 `['en', 'de']` 缩小体积；macOS 用系统 ICU，此项无效

平台专属块（mac / win / linux）

build.mac、build.win、build.linux 各自管理该平台的签名（codesign/notarize）、渲染引擎（bundleCEF/bundleWGPU/defaultRenderer）、图标路径和 chromiumFlags（透传给 CEF 初始化的 Chromium 命令行参数，true 加开关、字符串加值、false 移除 Electrobun 默认加的某个 flag）。

渲染引擎配置：bundleCEF / defaultRenderer / bundleWGPU

默认情况（不配置任何字段）：webview 直接用系统自带的原生引擎渲染网页内容（macOS WebKit / Windows WebView2 / Linux webkit2gtk），体积最小（~14MB）。绝大多数表单、CRUD、设置面板类应用什么都不用配，直接用这个默认值即可。

场景一：需要跨平台渲染行为完全一致，用 CEF

如果应用在不同系统的原生 webview 上出现渲染差异（字体、CSS 特性支持、JS 引擎行为等不一致），可以额外打包固定版本的 CEF（Chromium Embedded Framework），换取三端渲染结果一致，代价是体积明显变大：

build: {
  mac: {
    bundleCEF: true,
    defaultRenderer: "cef",
  },
  win: {
    bundleCEF: true,
    defaultRenderer: "cef",
  },
  linux: {
    bundleCEF: true,
    defaultRenderer: "cef",
  },
}

bundleCEF: true 是”把这份 Chromium 一起打包进去”，defaultRenderer: "cef" 是”webview 默认真的启用它渲染”——两个字段要配套写，只写 bundleCEF 不写 defaultRenderer 的话，CEF 会被打包但 webview 仍按默认走系统原生引擎。

场景二：需要 3D/WebGPU 渲染能力，用 bundleWGPU

这是完全不同的需求：不是要换网页渲染引擎，而是要让 TS 代码能绕开 webview，直接拿到原生 GPU 能力做 3D 渲染（Three.js/Babylon.js 场景）：

build: {
  mac: { bundleWGPU: true },
  win: { bundleWGPU: true },
  linux: { bundleWGPU: true },
}

开启后会打包 Dawn（Google 的 WebGPU 实现），TS 侧就能拿到 GPU surface 直连渲染。官方的 go-maze-wgpu、rust-flock-wgpu 模板就是这种用法，属于 3D 重度渲染场景才需要开的选项。

bundleCEF/defaultRenderer 和 bundleWGPU 可以同时开，互不冲突，只是解决的是两个不同问题（网页渲染一致性 vs 原生 GPU 访问）。详见 electrobun 的 bundleCEF 说明。

最小示例

import type { ElectrobunConfig } from "electrobun";
 
export default {
  app: {
    name: "MyApp",
    identifier: "com.example.myapp",
    version: "1.0.0",
  },
  build: {
    bun: {
      entrypoint: "src/bun/index.ts",
    },
  },
} satisfies ElectrobunConfig;

与 package.json 的关系

package.json 负责脚本入口
electrobun.config.ts 负责 Electrobun 的构建和平台配置
常见组合是 npm run dev / npm run build:* 转到 Electrobun 命令

zhaoweiguo 的知识库

目录