electron-builder通用配置(翻译)

electron-builder 配置页面

• 原文网址 : https://www.electron.build/configuration/configuration#configuration
• 说明：此页是我自己结合谷歌翻译以及有道词典翻译的，本人非计算机相关专业，并且英语水平暂留入门阶段，可能很多语句翻译的很非人类，如果有大佬肯指出文章中的错误，我一定尽快修正，不胜感激。

通用配置

electron-builder 配置 可以这样定义:

• 在 你项目文件的 package.json 中，加上 build 键值(key)，在最顶层

  "bulid":{
      "appID":"com.example.app"
  }
  

• 或者通过 --config 选项，默认 electron-builder.yml

  appID:"com.example.app"
  

• json ,json5,toml,或者js（导出配置或者生成配置的功能）格式也支持

  如果你想使用 toml 请使用 yarn add toml --dev 命令安装

  大多数的 options (选项) 都接受 null 参数

  例如，要显式地设置DMG图标必须是操作系统中的默认卷图标，并且必须不应用默认规则(即使用应用程序图标作为DMG图标)，请设置 dmg.icon 为 null(set dmg.icon to null)。

Artifact File Name Template

${ext} macro is supported in addition to file macros.

Environment Variables from File

Env file electron-builder.env in the current dir (example). Supported only for CLI usage.

如何阅读文档

• 可选属性（optional) 是正常的，必需的（required）是加粗的

• 在 属性名称（property name） 后边指定类型（type）:Array | String

  这样的形式意味着你可以指定或者字符串（**/*）或字符串数组（["**/*", "!foo.js"]）。

配置（Configuration）

• appId = com.electron.${name}

  String - 应用程序id 。用作MacOs的CFBundleIdentifier和Windows 的Application User Model ID （仅限NSIS目标，不支持Squirrel.Windows），强烈建议设置明确的ID。

• productName

  String - 作为 名称 ，但是允许你为可执行文件指定productName ，该名称可以包含 space 和其他特殊字符

• copyright = Copyright © year ${author}

  String - 你软件的版权信息

• directories

  • buildResources = build

    String - build Resources 的路径

    请注意：build Resources 并未打包进应用程序，如果你需要使用到某些文件，例如 托盘程序图标（tray icon），请明确指明需要包含的文件 "files": ["**/*", "build/icon.*"]

  • output = dist

    String - 输出目录，支持文件宏（File macros）

  • app

    String - 应用程序目录（包含应用程序的 package.json）默认指向 app ，www ，或者工作目录（working directory）

---

• mac MacConfiguration - Options related to how build macOS targets.

• mas MasConfiguration - MAS (Mac Application Store) options.

• dmg DmgOptions - macOS DMG options.

• pkg PkgOptions - macOS PKG options.

---

• win WindowsConfiguration - 于构建windows目标相关的选项

• nsis NsisOptions

• nsisWeb Web安装程序选项，继承 NsisOptions 选项

  • appPackageUrl

    String - 应用程序下载 Url

    Optional - 默认使用 publish configuration

    像 https://example.com/download/latest 的Url ，允许Web安装程序与版本无关（安装程序将下载最新的应用程序包）

    请注意：自定义X-Archhttp 头为32或64。

  • artifactName

    String - The artifact file name template. 默认指向${productName} Web Setup ${version}.${ext}.

  • portable - 便携相关选项

  • requestExecutionLevel = user

    “user”|“highest”|“admin” -Windows 的请求执行级别（The requested execution levelfor Windows.）

  • appx AppXOptions

  • squirrelWindows SquirrelWindowsOptions

---

• linux LinuxConfiguration - Options related to how build Linux targets.
• deb DebOptions - Debian package options.
• snap SnapOptions - Snap options.
• appImage AppImageOptions - AppImage options.
• pacman LinuxTargetSpecificOptions
• rpm LinuxTargetSpecificOptions
• freebsd LinuxTargetSpecificOptions
• p5p LinuxTargetSpecificOptions
• apk LinuxTargetSpecificOptions

---

• buildDependenciesFromSource = false

  Boolean - 是否从源构建应用程序本机依赖项。

• nodeGypRebuild = false

  Boolean - 是否在开始打包应用程序之前执行 node-gyp rebuild

  不要 use npm (neither .npmrc) 来配置 electron headers ，用electron-builder node-gyp-rebuild 来代替

• npmArgs

  Array | String - 安装应用程序本地依赖（native deps） 时添加的额外命令行参数

• nmpRebuild = true

  Boolean - 是否在打包应用程序之前rebuild本地依赖

  ---

• buildVersion

  String - 构建的版本，对应于

  MacOS 的CFBundleVersion 和 Windows 元数据属性，默认为Version

  如果已经定义TRAVIS_BUILD_NUMBER 、 APPVEYOR_BUILD_NUMBER 、 CIRCLE_BUILD_NUM 、 BUILD_NUMBER 、 bamboo.buildNumber 这些环境变量，那么将会被用作 build Version（version.build_number）

• electronCompile

  Boolean - 是否使用 electron-compile 来编译应用程序。默认为true，如果在dependencies中设定electron-compile为true，并且在devDependencies设置为false` 或者不声明。

• electronDist

  String - 自定义electron构建路径，例如（~/electron/out/R）

• electronDownload - electron-download 选项

  • version String
  • cache String - 缓存位置
  • mirror String - 镜像
  • strictSSL Boolean
  • isVerfyChecksum Boolean
  • platform “darwin” | “linux” | “win32” | “mas”
  • arch String

• electronVersion

  String - 你所打包的electron版本，默认为electron electron-prebuilt electron-prebuilt-compile 依赖

• extends

  String - 内置配置预设的名称或配置文件的路径（相对于项目目录）目前，仅仅支持react-cra

  如果，在应用程序依赖中声明 react-scripts ，那么react-cra 将自动设置，设置为null 禁用自动检测

• extraMetadata

  any - 将属性添加到package.json

• readonly = false

  Boolean - 如果应用程序未签名是否失败（如果代码签名配置不正确，则防止未签名的应用程序）

• muonVersion

  String - 你要打包的 muon 版本

• nodeVersion

  String - 仅限于libui-based frameworks ，你所要打包的 NodeJS 版本，你可以设置为current 来设置为正在运行的NodeJS版本。

• launchUiVersion

  Boolean | String - 仅限于libui-based frameworks ，你所要打包的 LaunchUI 版本。仅仅针对于Windows ，默认为适合框架使用的版本。

• framework

  String - 框架名称，electron proton-native libui 默认为electron

• afterPack

  function| 文件路径 | 模块id - 打包后运行（but before pack into distributable format and sign).

• afterSign

  function| 文件路径 | 模块id 打包后或者签名后运行（but before pack into distributable format）

• artifactBuildStarted

  module:app-builder-lib/out/configuration.__type | String - The function (or path to file or module id) to be run on artifact build start.

• artifactBuildCompleted

  module:app-builder-lib/out/configuration.__type | String - The function (or path to file or module id) to be run on artifact build completed.

• afterAllArtifactBuild - The function (or path to file or module id) to be run after all artifacts are build.

• onNodeModuleFile - The function (or path to file or module id) to be run on each node modulefile.

• beforeBuild (context: BeforeBuildContext) => Promise | null - The function (or path to file or module id) to be run before dependencies are installed or rebuilt. Works when npmRebuild is set to true. Resolving to false will skip dependencies install or rebuild.

  If provided and node_modules are missing, it will not invoke production dependencies check.

• remoteBuild = true

  Boolean - 如果当前操作系统不支持目标，是否使用Electron Build Service构建。

• includePdb = false

Boolean - 是否包含PDB文件

• removePackageScripts = true

  Boolean - 是否从package.json 中移除 scripts

---

每个平台可覆写的Options

如果需要，以下options可用在每一个平台（top-level keys mac, linux and win）

• appId = com.electron.${name}

  String - 应用程序id，用作MacOs的CFBundleIdentifier和Windows 的Application User Model ID （仅限NSIS目标，不支持Squirrel.Windows），强烈建议设置明确的ID。

• artifactName

  String - The artifact file name template.Defaults to ${productName}-${version}.${ext} (some target can have other defaults, see corresponding options).

• compression = normal “stroe” | “normal” | “maximum”

  压缩级别。如果要快速测试构建，store 能够显著地缩短构建时间，maximum 不会导致明显的尺寸差异，但是会增加构建时间。

• files

  文件配置（The files configuration.）

• extraResources

  The extra resources configuration.

• extraFiles

  The extra files configuration.

• asar = true AsarOptions

  Boolean - 是否使用Electron的存档格式将应用程序的源代码打包到存档中。

  Node moduls，必须是 unpacked，将自动检测，你不需要显式设置 asarUnpack ，please file an issue if this doesn’t work.

  • smartUnpack = true

    Boolean - 是否自动解压缩可执行文件。

    ordering String

    asarUnpack Array | String - A glob patterns relative to the app directory, which specifies which files to unpack when creating the asar archive.(相对于app目录的glob模式，指定在创建asar存档时要解压缩的文件。)

• fileAssociations Array | FileAssociation 文件关联

  • ext String | Array 扩展名（点之后的）。例如。png。
  • name String - 名称。例如PNG。默认为ext。
  • description String - 仅支持Windows ， 描述
  • mimeType String - 仅支持Linux ， mime-type
  • icon String - icon路径，相对于（构建资源目录）的图标路径（.icns for MacOS and .ico for Windows）默认为${firstExt}.icns/ ${firstExt}.ico或应用程序图标（如果指定了多个扩展名，使用第一个）。不支持Linux，file issue if need (default icon will be x-office-document).
  • role = Editor ：String - 仅支持 MacOS The app’s role with respect to the type. The value can be Editor, Viewer, Shell, or None. Corresponds to CFBundleTypeRole.
  • isPackage ：Boolean - macOS-only Whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. Corresponds to LSTypeIsPackage.
  • protocols Array | Protocol ：The URL protocol schemes.
  • name String - The name. e.g. IRC server URL.
  • schemes Array - The schemes. e.g. ["irc", "ircs"].
  • role = Editor “Editor” | “Viewer” | “Shell” | “None” - macOS-only The app’s role with respect to the type.

• forceCodeSigning

  Boolean 应用程序没有签名是否失败

• electronUpdaterCompatibility

  String The electron-updater compatibility semver range.

• publish The publish options.

• detectUpdateChannel = true

  Boolean Whether to infer update channel from application version pre-release components. e.g. if version 0.12.1-alpha.1, channel will be set to alpha. Otherwise to latest.

• detectUpdateChannel = true

  Boolean Please see Building and Releasing using Channels.

• releaseInfo The release info. Intended for command line usage:

  -c.releaseInfo.releaseNotes="new features"

  • releaseName String - The release name.
  • releaseNotes String - The release notes.
  • releaseNotesFile String - The path to release notes file. Defaults to release-notes-${platform}.md (where platform it is current platform — mac, linux or windows) or release-notes.md in the build resources.
  • releaseDate String - The release date.
  • target String | TargetConfiguration

---

Metadata

Some standard fields should be defined in the package.json.

• name String - The application name.

• description String - The application description.

• homepage String - The url to the project homepage (NuGet Package projectUrl (optional) or Linux Package URL (required)).

  If not specified and your project repository is public on GitHub, it will be https://github.com/${user}/${project} by default.

• license String - linux-only. The license name.

• author

  • name String

  • email String

• repository

  String | RepositoryInfo - The repository

  • url String

• build Configuration - The electron-builder configuration.

---

Proton Native

To package Proton Native app, set protonNodeVersion option to current or specific NodeJS version that you are packaging for. Currently, only macOS and Linux supported.

---

Build Version Management

CFBundleVersion (macOS) and FileVersion (Windows) will be set automatically to version.build_number on CI server (Travis, AppVeyor, CircleCI and Bamboo supported).

---

Hooks

All examples assumed that you use latest Node.js 8.11.x or higher.

---

afterPack

The function (or path to file or module id) to be run after pack (but before pack into distributable format and sign).

(context: AfterPackContext): Promise<any> | any

AS function

afterPack: async (context) => {
  // your code
}

Because in a configuration file you cannot use JavaScript, can be specified as a path to file or module id. Function must be exported as default export.

"build": {
  "afterPack": "./myAfterPackHook.js"
}

File myAfterPackHook.js in the project root directory:

myAfterPackHook.js

exports.default = async function(context) {
  // your custom code
}

afterSign

The function (or path to file or module id) to be run after pack and sign (but before pack into distributable format).

(context: AfterPackContext): Promise<any> | any

Configuration in the same way as afterPack (see above).

afterAllArtifactBuild

The function (or path to file or module id) to be run after all artifacts are build.

(buildResult: BuildResult): Promise<Array<string>> | Array<string>

Configuration in the same way as afterPack (see above).

myAfterAllArtifactBuild.js

exports.default = function () {
  // you can return additional files to publish
  return ["/path/to/additional/result/file"]
}

onNodeModuleFile

The function (or path to file or module id) to be run on each node module file.

(file: string) => void

Configuration in the same way as afterPack (see above).

AfterPackContext

interface AfterPackContext {
  outDir: string
  appOutDir: string
  packager: PlatformPackager<any>
  electronPlatformName: string
  arch: Arch
  targets: Array<Target>
}

BuildResult

interface BuildResult {
  outDir: string
  artifactPaths: Array
  platformToTargets: Map>
  configuration: Configuration
}

---

转载

一,electron-builder打包的详细介绍

• 原文地址 :http://www.php.cn/div-tutorial-411690.html.

builder的使用和配置都是很简单的
builder配置有两种方式

package.json中直接配置使用（比较常用，我们下面着重来讲这个）

指定electron-builder.yml文件

下面是一个简单的package.js中带注释的配置

"build": {  // 这里是electron-builder的配置

    "productName":"xxxx",//项目名 这也是生成的exe文件的前缀名

    "appId": "com.xxx.xxxxx",//包名  

    "copyright":"xxxx",//版权  信息

    "directories": { // 输出文件夹

      "output": "build"

    }, 

    // windows相关的配置

    "win": {  

      "icon": "xxx/icon.ico"//图标路径 

    }  

  }

在配置文件中加入以上的文件之后就可以打包出来简单的文件夹，文件夹肯定不是我们想要的东西。下一步我们来继续讲别的配置。

打包目标配置

要打包成安装程序的话我们有两种方式，

使用NSIS工具对我们的文件夹再进行一次打包，打包成exe

通过electron-builder的nsis直接打包成exe，配置如下

"win": {  // 更改build下选项

	    "icon": "build/icons/aims.ico",
	
	    "target": [
	
		      {
		
		        "target": "nsis" // 我们要的目标安装包
		
		      }
	
	    ]

  },

其他平台配置

"dmg": { // macOSdmg

	  "contents": [
	
	    ...
	
	  ]

  },

  "mac": {  // mac

    	"icon": "build/icons/icon.icns"

  },

  "linux": { // linux

    	"icon": "build/icons"

  }

nsis配置

这个要详细的讲一下，这个nsis的配置指的是安装过程的配置，其实还是很重要的，如果不配置nsis那么应用程序就会自动的安装在C盘。没有用户选择的余地，这样肯定是不行的

关于nsis的配置是在build中nsis这个选项中进行配置，下面是部分nsis配置

"nsis": {

  "oneClick": false, // 是否一键安装

  "allowElevation": true, // 允许请求提升。 如果为false，则用户必须使用提升的权限重新启动安装程序。

  "allowToChangeInstallationDirectory": true, // 允许修改安装目录

  "installerIcon": "./build/icons/aaa.ico",// 安装图标

  "uninstallerIcon": "./build/icons/bbb.ico",//卸载图标

  "installerHeaderIcon": "./build/icons/aaa.ico", // 安装时头部图标

  "createDesktopShortcut": true, // 创建桌面图标

  "createStartMenuShortcut": true,// 创建开始菜单图标

  "shortcutName": "xxxx", // 图标名称

  "include": "build/script/installer.nsh", // 包含的自定义nsis脚本 这个对于构建需求严格得安装过程相当有用。

  "script" : "build/script/installer.nsh" // NSIS脚本的路径，用于自定义安装程序。 默认为build / installer.nsi  

},

nsis中配置

"win": {

	  "icon": "build/icons/aims.ico",
	
	  "target": [
	
		    {
		
		      "target": "nsis",
		
		      "arch": [ // 这个意思是打出来32 bit + 64 bit的包，但是要注意：这样打包出来的安装包体积比较大，所以建议直接打32的安装包。
		
		        "x64", 
		
		        "ia32"
		
		      ]
	
	    }

  ]

}

更新配置
下面这个是给更新用的配置，主要是为了生成lastest.yaml配置文件

完整配置
基本上可用的完整的配置

"build": {

    "productName":"xxxx",//项目名 这也是生成的exe文件的前缀名

    "appId": "com.leon.xxxxx",//包名  

    "copyright":"xxxx",//版权  信息

    "directories": { // 输出文件夹

      		"output": "build"

    	}, 

    "nsis": {

      "oneClick": false, // 是否一键安装

      "allowElevation": true, // 允许请求提升。 如果为false，则用户必须使用提升的权限重新启动安装程序。

      "allowToChangeInstallationDirectory": true, // 允许修改安装目录

      "installerIcon": "./build/icons/aaa.ico",// 安装图标

      "uninstallerIcon": "./build/icons/bbb.ico",//卸载图标

      "installerHeaderIcon": "./build/icons/aaa.ico", // 安装时头部图标

      "createDesktopShortcut": true, // 创建桌面图标

      "createStartMenuShortcut": true,// 创建开始菜单图标

      "shortcutName": "xxxx", // 图标名称

      "include": "build/script/installer.nsh", // 包含的自定义nsis脚本

    },

    "publish": [

	      {
	
	        "provider": "generic", // 服务器提供商 也可以是GitHub等等
	
	        "url": "http://xxxxx/" // 服务器地址
	
	      }

    ],

    "files": [

		      "dist/electron/**/*"
	
	    ],

    "dmg": {

	      "contents": [
	
		        {
		
		          "x": 410,
		
		          "y": 150,
		
		          "type": "link",
		
		          "path": "/Applications"
		
		        },
	
		        {
		
		          "x": 130,
		
		          "y": 150,
		
		          "type": "file"
		
		        }
	
	      ]

    },

    "mac": {

	     	 "icon": "build/icons/icon.icns"
	
	    },

    "win": {

     	 "icon": "build/icons/aims.ico",

	      "target": [
	
		        {
		
			          "target": "nsis",
			
			          "arch": [
			
			            "ia32"
			
			          ]
		
		        }
		
	      ]

    },

    "linux": {

	      	"icon": "build/icons"
	
	    }

  }

命令行参数（CLI）

Commands(命令):

electron-builder build                    构建命名                      [default]

electron-builder install-app-deps         下载app依赖

electron-builder node-gyp-rebuild         重建自己的本机代码

electron-builder create-self-signed-cert  为Windows应用程序创建自签名代码签名证书

electron-builder start                    使用electronic-webpack在开发模式下运行应用程序(须臾要electron-webpack模块支持)

Building(构建参数):

--mac, -m, -o, --macos   Build for macOS,                              [array]

--linux, -l              Build for Linux                               [array]

--win, -w, --windows     Build for Windows                             [array]

--x64                    Build for x64 (64位安装包)                     [boolean]

--ia32                   Build for ia32(32位安装包)                     [boolean]

--armv7l                 Build for armv7l                              [boolean]

--arm64                  Build for arm64                               [boolean]

--dir                    Build unpacked dir. Useful to test.           [boolean]

--prepackaged, --pd      预打包应用程序的路径（以可分发的格式打包）

--projectDir, --project  项目目录的路径。 默认为当前工作目录。

--config, -c             配置文件路径。 默认为`electron-builder.yml`（或`js`，或`js5`)

Publishing(发布):

--publish, -p  发布到GitHub Releases [choices: "onTag", "onTagOrDraft", "always", "never", undefined]

Other(其他):

--help     Show help                                                 [boolean]

--version  Show version number                                       [boolean]

Examples(例子):

electron-builder -mwl                        为macOS，Windows和Linux构建（同时构建）

electron-builder --linux deb tar.xz          为Linux构建deb和tar.xz

electron-builder -c.extraMetadata.foo=bar    将package.js属性`foo`设置为`bar`

electron-builder --config.nsis.unicode=false 为NSIS配置unicode选项

TargetConfiguration(构建目标配置):

target:  String - 目标名称，例如snap.

arch “x64” | “ia32” | “armv7l” | “arm64”> | “x64” | “ia32” | “armv7l” | “arm64”  -arch支持列表

–这部分来自这位作者，写的很详细，有删减，大家有兴趣可以去它的博客阅读，链接在上边