electron-userland/electron-builder
GitHub: electron-userland/electron-builder
一站式 Electron 应用打包构建解决方案，支持跨平台分发、代码签名和自动更新。
Stars: 14469 | Forks: 1835
# electron-builder [](https://www.npmjs.com/package/electron-builder) [](https://yarn.pm/electron-builder) [](https://www.electron.build/donate)
一个完整的解决方案，用于打包和构建适用于 macOS、Windows 和 Linux 的[Electron](https://electronjs.org)、[Proton Native](https://proton-native.js.org/) 应用，开箱即用，支持“自动更新”。📦
我们一直期待社区的贡献！👀 搭建[开发环境](https://github.com/electron-userland/electron-builder/blob/master/CONTRIBUTING.md)非常简单 🪩
## 文档
请在 [electron.build](https://www.electron.build) 查看完整文档。
* NPM 包管理：
* [原生应用依赖](https://electron.atom.io/docs/tutorial/using-native-node-modules/)编译（支持 [Yarn](http://yarnpkg.com/)）。
* 开发依赖永远不会被包含在内。您不需要显式地忽略它们。
* 支持[两个 package.json 结构](https://www.electron.build/tutorials/two-package-structure)，但即使您有原生生产依赖，也不强制使用它。
* 在 CI 服务器或开发机器上进行[代码签名](https://www.electron.build/code-signing)。
* [自动更新](https://www.electron.build/auto-update)就绪的应用程序打包。
* 众多的目标格式：
* 所有平台：`7z`、`zip`、`tar.xz`、`tar.7z`、`tar.lz`、`tar.gz`、`tar.bz2`、`dir`（解压目录）。
* [macOS](https://www.electron.build/mac)：`dmg`、`pkg`、`mas`。
* [Linux](https://www.electron.build/linux)：[AppImage](http://appimage.org)、[snap](http://snapcraft.io)、debian package (`deb`)、`rpm`、`freebsd`、`pacman`、`p5p`、`apk`。
* [Windows](https://www.electron.build/win)：`nsis`（安装程序）、`nsis-web`（Web 安装程序）、`portable`（免安装便携版）、AppX（Windows Store）、MSI、Squirrel.Windows。
* 将[构建产物](https://www.electron.build/publish)发布到 GitHub Releases、Amazon S3、DigitalOcean Spaces 和 Bintray。
* 高级构建：
* 将[已打包的应用](https://www.electron.build/#pack-only-in-a-distributable-format)打包为可分发格式。
* 分离的[构建步骤](https://github.com/electron-userland/electron-builder/issues/1102#issuecomment-271845854)。
* 并行构建和发布，在 CI 服务器上使用硬链接以减少 IO 和磁盘空间使用。
* [electron-compile](https://github.com/electron/electron-compile)支持（在构建时即时编译以供发布时使用）。
* [Docker](https://www.electron.build/multi-platform-build#docker)镜像，用于在任何平台上构建 Linux 或 Windows 的 Electron 应用。
* [Proton Native](https://www.electron.build/configuration/#proton-native)支持。
* 自动按需下载所有必需的工具文件（例如用于代码签名 Windows 应用程序、制作 AppX），无需设置。
| 问题 | 答案 |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| “我想配置 electron-builder” | [查看选项](https://electron.build/configuration) |
| “我发现了 bug 或者有问题” | [提交 issue](https://github.com/electron-userland/electron-builder/issues/new) |
| “我想支持开发” | [捐赠](https://www.electron.build/donate) |
## 安装
```
yarn add electron-builder --dev
// or npm, pnpm, bun
```
### Yarn 3 注意事项
Yarn 3 默认使用 PnP，但 electron-builder 仍然需要 node-modules（参考：[yarnpkg/berry#4804](https://github.com/yarnpkg/berry/issues/4804#issuecomment-1234407305)）。在 `.yarnrc.yaml` 中添加如下配置：
```
nodeLinker: "node-modules"
```
这将声明使用 node-modules 而不是 PnP。
## 快速设置指南
推荐使用 [electron-webpack-quick-start](https://github.com/electron-userland/electron-webpack-quick-start) 来创建新的 Electron 应用。参见[样板](https://www.electron.build/#boilerplates)。
1. 在应用程序的 `package.json` 中指定标准字段 —— [name](https://electron.build/configuration.html#metadata)、`description`、`version` 和 [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors)。
2. 在 `package.json` 中指定 [build](https://www.electron.build/configuration.html#build) 配置，如下所示：
"build": {
"appId": "your.id",
"mac": {
"category": "your.app.category.type"
}
}
参见[所有选项](https://www.electron.build/configuration)。可能需要 [files](https://www.electron.build/contents#files) 选项来指示哪些文件应打包到最终应用程序中，包括入口文件。
您也可以使用单独的配置文件，例如 `js`、`ts`、`yml` 和 `json`/`json5`。有关支持的扩展名，请参见 [read-config-file](https://www.npmjs.com/package/read-config-file)。[用于编程 API 的 JS 示例](https://www.electron.build/programmatic-usage)
3. 添加[图标](https://www.electron.build/icons)。
4. 将 [scripts](https://docs.npmjs.com/cli/run-script) 键添加到开发 `package.json` 中：
"scripts": {
"app:dir": "electron-builder --dir",
"app:dist": "electron-builder"
}
然后您可以运行 `yarn app:dist`（以可分发格式打包，例如 dmg、windows 安装程序、deb package）或 `yarn app:dir`（仅生成包目录，并未真正打包。这对于测试很有用）。
为了确保您的原生依赖始终与 electron 版本匹配，只需将脚本 `"postinstall": "electron-builder install-app-deps"` 添加到您的 `package.json` 中。
5. 如果您拥有属于应用程序一部分的原生插件（而非作为依赖项），请将 [nodeGypRebuild](https://www.electron.build/configuration.html#nodegyprebuild) 设置为 `true`。
请注意，默认情况下，所有内容都会打包到 asar 存档中[默认](https://electron.build/configuration.html#asar)。
对于将要发布到生产环境的应用，您应该对应用程序进行签名。请参见[在哪里购买代码签名证书](https://www.electron.build/code-signing#where-to-buy-code-signing-certificate)。
## 编程用法
参见 `node_modules/electron-builder/out/index.d.ts`。提供了 TypeScript 类型定义，也可以在[这里](https://www.electron.build/electron-builder/globals)找到。
下面提供的代码片段也可以在[这里](https://www.electron.build/programmatic-usage)“实地”查看。
```
"use strict"
const builder = require("electron-builder")
const Platform = builder.Platform
// Promise is returned
builder.build({
targets: Platform.MAC.createTarget(),
config: {
"//": "build options, see https://www.electron.build/"
}
})
.then(() => {
// handle result
})
.catch((error) => {
// handle error
})
```
## 社区样板
* [electron-react-boilerplate](https://github.com/chentsulin/electron-react-boilerplate) 用于可扩展跨平台桌面应用的样板。
* [electron-vue-vite](https://github.com/caoxiemeihao/electron-vue-vite) 一个非常简单的 Electron + Vue3 + Vite5 样板。
* [vite-electron-builder](https://github.com/cawa-93/vite-electron-builder) 基于 Vite 的 Electron 应用安全样板。支持多个框架。
* [electronjs-with-nextjs](https://github.com/saulotarsobc/electronjs-with-nextjs) 结合 NextJS 和 TypeScript 的 ElectronJS 应用。
## 调试
设置 `DEBUG` 环境变量以调试 electron-builder 的行为：
```
DEBUG=electron-builder
```
`FPM_DEBUG` 环境变量用于添加有关构建 linux 目标（snap 和 appimage 除外）的更多详细信息。
`DEBUG_DMG=true` 环境变量用于从 `hdiutil` (macOS) 添加更多调试/详细输出。
!!! tip "cmd"
在 [Windows](https://github.com/visionmedia/debug#windows-command-prompt-notes) 上，使用 set 命令设置环境变量。
```bash
set DEBUG=electron-builder
```
!!! tip "PowerShell"
PowerShell 使用不同的语法来设置环境变量。
```bash
$env:DEBUG = "electron-builder"
```
## 捐赠
我们在空闲时间进行这项开源工作。如果您希望我们投入更多时间，请[捐赠](https://www.electron.build/donate)。
标签：AppImage, deb, DMG, DNS 反向解析, Electron, GNU通用公共许可证, Linux安全, MITM代理, Node.js, npm, NSIS, rpm, Snap, Web应用防火墙, Yarn, 代码签名, 依赖管理, 前端工程化, 安装包制作, 安装程序, 打包工具, 暗色界面, 桌面应用开发, 自动化攻击, 自动化攻击, 自动更新, 请求拦截, 软件分发