Electron脚手架 - ElectronForge使用文档

环境:

• node： v14.16.0
• npm: 6.14.11
• electron-forge：6.0.0-beta.54

Electron-forge 是一个帮你从项目初始化到打包发布全流程管理的脚手架工具，可整合React、Vue、Webpack、TS等，配置简单统一，容易上手。

下面是详细的使用文档，包括初始化项目、引入到现有项目、使用模板、不同平台的打包配置、发布渠道配置、CLI命令、API参考等几个重要部分，最常用也是重要的部分是：配置打包Marker部分，涉及到最后安装包的名称、图标、签名、静态资源文件、安装包格式等常用配置，

上手体验

初始化一个新的项目 my-app

npx create-electron-app my-app
cd my-app
npm start

编译打包：

npm run make

在现有项目中使用

将现有的 Electron 项目导入 ELectron Forge 工作流非常直接：

npm6:

cd my-app
npm install --save-dev @electron-forge/cli
npx electron-forge import

npm7

cd my-app
npm install --save-dev @electron-forge/cli
npm exec --package=@electron-forge/cli -c "electron-forge import"

配置方式

在package.json 文件中集中配置 Electron Forge

简单配置：

package.json

{
  "name": "my-app",
  "version": "0.0.1",
  "config": {
    "forge": {
      "packagerConfig": {},
      "makers": [
        {
          "name": "@electron-forge/maker-zip"
        }
      ]
    }
  }
}

一般的配置可以直接写在里面，但是你想提供 hook 钩子函数，这种高级配置选项，就必须使用单独的 js 文件进行配置。

高级配置：

package.json

直接给个 js 路径

{
  "name": "my-app",
  "version": "0.0.1",
  "config": {
    "forge": "./forge.config.js" // 这里写js路径
  }
}

然后详细配置在：forge.config.js

module.exports = {
  packagerConfig: {},
  makers: [
    {
      name: '@electron-forge/maker-zip'
    }
  ]
}

配置内容

所有属性都是可选的，示例：

{
  packagerConfig: { ... },
  electronRebuildConfig: { ... },
  makers: [ ... ],
  publishers: [ ... ],
  plugins: [ ... ],
  hooks: { ... },
  buildIdentifier: 'my-build'
}

1. packagerConfig

Object 对象，直接传递给electron-packager，详细文档说明见：Electron Packager API docs.

统一配置 名称、图标、asar、运行前 Hook、内部下载选项、exe 文件名、静态文件等，当然你可以在下面的 markers 里针对不同平台单独配置。

注意：不要设置 dir、arch、platform、out、electronVersion 选项，Electron Forge 内部会设置。

packagerConfig: {
    name: 'xxx客户端',
    executableName: 'App',
    extraResource: ['./assets/Readme.txt', './assets/img/a.png'], // 静态文件
    icon: './build/icon' // 不用加后缀，但是需要准备3个文件，win: icon.ico, mac: icon.icns, linux: icon.png，打包时自动识别，linux 在BrowserWindow构造参数中设置
  },

其中静态文件在正式环境上通过 process.resourcesPath 访问，如：

path.join(process.resourcesPath, 'Readme.txt')

2. Rebuild Config

Object 对象，直接传递给electron-rebuild，详细文档说明见： electron-rebuild

没仔细研究过这个，好像不太需要。

注意：不要设置 buildPath、arch、electronVersion 选项

3. Makers

数组，用于针对不同平台的打包选项，像 dmg、exe 或者其他文件，支持的 marker 有：AppX-Windows 应用商店、deb、 DMG-macOS 标准格式、Flatpak-linux 沙盒、Pkg-Mac 应用商店 、RPM-基于红帽的 linux 标准包、 Snapcraft、Squirrel.Windows 最常用

forge.config.js 示例：

module.exports = {
  makers: [
    {
      // 全平台都可用
      name: '@electron-forge/maker-zip'
    },
    {
      // Windows
      name: '@electron-forge/maker-squirrel',
      config: {
        authors: 'your name',
        iconUrl: './icon.ico',
        setupIcon: './icon.ico',
        certificateFile: './cert.pfx',
        certificatePassword: 'this-is-a-secret'
      }
    },
    {
      // Mac
      name: '@electron-forge/maker-dmg',
      config: {
        background: './assets/dmg-background.png',
        format: 'ULFO', // (OS X 10.11+ only)
        icon: './icon.icns'
      }
    },
    {
      name: '@electron-forge/maker-rpm',
      config: {
        options: {
          maintainer: 'Joe Bloggs',
          homepage: 'http://example.com'
        }
      }
    }
  ]
}

注：所有的 marker 都有默认的 platforms 平台属性值，一般不需要特殊指定该属性。
dmg 、pkg 目标文件只能在 macOS 上打包
mac 打包参数详细说明 >exe 文件安装时启动多次问题

4. Publishers

发布方式，publisher 将 make 命令打包的产物发送到你的软件分发服务器（或者 S3 bucket）上，供用户下载新的安装包。 支持的 publisher 有 Bitbucket、Electron Release Server、GitHub(代码开源才行）、Nucleus、S3、Snapcraft

forge.config.js 例：

module.exports = {
  publishers: [
    {
      name: '@electron-forge/publisher-electron-release-server',
      platforms: ['darwin', 'linux'],
      config: {
        baseUrl: 'https://update.server.com',
        channel: 'stable',
        username: 'admin',
        password: 'admin'
      }
    }
  ]
}

注：所有的 publisher 默认发布全平台的安装包，如果你只想发布某几个平台的安装包，请在 platforms 参数的列表中指明。

5. Plugins

Electron Forge 的插件系统可以很容易扩展其核心功能，插件编写指南.

插件列表：

• Electronegativity: 是一个识别 Electron 应用中的错误配置项和进行安全检查的工具，详见electronegativity

• Webpack: 使用标准的 webpack 工具编译你的主进程和渲染进程代码，支持渲染进程的模块热重载。你需要两份配置文件，一个主进程的 mainConfig，另一个是渲染进程的 renderer.config，当然你也可以通过 webpack 模板初始化项目时生成这两个文件

  npx create-electron-app my-new-app --template=webpack
  

• Auto Unpack Native Modules

• Local Electron: 当你需要 fork Electron 仓库并在本地新测试功能或者修复它的 bug 时使用。

6. Hook

Hook 允许你在 Electron Forge 构建过程中的不同节点自定义自己的功能，hook 是一个异步的函数，返回一个 Promise。接收的第一个参数是 Electron 相关的配置，其他参数取决于 hook 类型。

hook 类型有： generateAssets, postStart, prePackage, packageAfterCopy, packageAfterPrune, packageAfterExtract, postPackage, preMake, postMake, readPackageJson

{
  hooks: {
    generateAssets: async (forgeConfig) => {
      console.log('We should generate some assets here')
    }
  }
}

7. Build Identifier

此属性可用于标识不同的构建配置，通常设置为 release 发布的通道号，或者其他形式的唯一标识符。例如，设为 prod 或 beta

config.forge.js

const {
  utils: { fromBuildIdentifier }
} = require('@electron-forge/core')

module.exports = {
  buildIdentifier: process.env.IS_BETA ? 'beta' : 'prod',
  packagerConfig: {
    appBundleId: fromBuildIdentifier({ beta: 'com.beta.app', prod: 'com.app' })
  }
}

CLI 命令行参数说明

Electron forge’s CLI 是从其核心模块中分离而来，全局安装命令：

# NPM
npm i -g @electron-forge/cli

# Yarn
yarn global add @electron-forge/cli

CLI 模块只是 代理了原始的 API 命令，几乎所有的配置都在 Electron Forge 配置中完成，CLI 只是提供了触发所有核心功能的便捷方法。

提供的命令如下，你需要重点关注 start、package、make 和 publish 命令

1. import

对应 electronForge.import, 尝试将 Forge 导入进现有的 Electron 应用与之兼容，通常，这只是创建一个基本的 Electron Forge 配置，并添加所需的依赖项。

无其他参数值。

electron-forge import

2. init

对应 electronForge.init，在指定的目录下（默认为 .)初始化一个 Electron 应用. 建议加上 --template参数从 ts 或者 webpack 模板初始化项目（需要全局安装 electron-forge）。

参数

• -t, --template [name]： 非必填，值为 typescript、webpack 或 typescript-webpack
• -c, --copy-ci-files： 是否添加 Travis 和 Appveyor 的自动化构建 CI 模板

例：

electron-forge init -t webpack -c demo-electron2

相关连接：

持续集成服务 Travis CI 教程 - 阮一峰

AppVeyor

3. install

对应 electronForge.install，方便安装已经发布到 Github 上的开源项目（实际没啥用），例如： Atom

electron-forge install atom/atom

4. lint

对应 electronForge.lint，运行在你的 package.json 中定义的 lint 命令

electron-forge lint

5. make

对应 electronForge.make，基于你的 Forge 配置文件和传递的参数进行打包、编译，生成可分发的安装包。在 make 之前会先运行 package 命令。

• -a, --arch [arch]：目标系统架构，例如: x64
• -p, --platform [platform]: 运行平台，例如： mas，默认是你当前的系统编译环境
• --targets [targets]： 与 marker 的作用一致，例如：@electron-forge/maker-deb
• --skip-package： 是否跳过打包步骤，如果你需要进行连续的 make 任务，设置该标志位可节省时间。

electron-forge make --target @electron-forge/maker-squirrel --target @electron-forge/maker-zip --skip-package

6. package

对应 electronForge.package，打包你的应用到一个文件夹，这不能生成可分发的软件安装包，如需要请使用上面的 make 命令。

• -a, --arch [arch]：目标系统架构，例如: x64
• -p, --platform [platform]: 运行平台，例如： mas，默认是你当前的系统编译环境

7. publish

对应 electronForge.publish，会先执行 package、make 命令生成可分发的安装包，然后根据你的配置文件中的 publisher 配置进行上传发布。

• --target [target[,target...]]：会覆盖你的 target 配置
• --dry-run：只运行完 package、make 命令，保存当前状态，不上传文件到 publisher
• --from-dry-run：继续执行 --dry-run 最后未完成的上传 publisher 操作

electron-forge publish --dry-run
electron-forge publish --from-dry-run

8. start

对应 electronForge.start，启动应用，相当于 npm start 或 yarn start，在终端输入 rs 并按回车可以快速重启应用。

• -p, --app-path ：应用所在的文件夹路径，默认为 .
• -l, --enable-logging: 是否启用日志，开启后会打印 Electron 内部日志
• -n, --run-as-node： 是否以 node.js 脚本方式启动 app
• -i, --inspect-electron：是否开启主进程检查模式，Electron>1.7, 查看帮助

electron-forge start -i -l

内置模板

内置三个模板：typescript、typescript-webpack、webpack

webpack 详细说明见上文 配置项 -> plugins 部分

项目初始化方法：

npx create-electron-app my-new-app --template=typescript
或者
yarn create electron-app my-new-app --template=typescript
或者
electron-forge init -t typescript

开发指南

应用签名

整合前端框架

1. Parcel

2. React

以下内容在 React 17, TypeScript 4.1, Webpack 4 下测试可用。

1. 根据上文指导，先以 webpack 模板初始化一个项目，然后将以下依赖到 devDependencies 即可使用 JSX

   # npm
   npm install --save-dev @babel/core @babel/preset-react babel-loader
   
   # yarn
   yarn add --dev @babel/core @babel/preset-react babel-loader
   

2. webpack.rules.js 设置 babel-loader

   module.exports = [
     // ... existing loader config ...
     {
       test: /\.jsx?$/,
       use: {
         loader: 'babel-loader',
         options: {
           exclude: /node_modules/,
           presets: ['@babel/preset-react']
         }
       }
     }
     // ... existing loader config ...
   ]
   

3. 添加基本的 React 依赖

   # npm
   npm install --save react react-dom
   
   # yarn
   yarn add react react-dom
   

4. 开始编程

   React 文档

   import * as React from 'react'
   import * as ReactDOM from 'react-dom'
   
   function render() {
     ReactDOM.render(<h2>Hello from React!</h2>, document.body)
   }
   
   render()
   

3. React with TypeScript

以下内容在 React 17, TypeScript 4.1, Webpack 4 下测试可用。

1. 根据上文指导，先以 typescript-webpack 模板创建一个项目，编辑新创建的 tsconfig.json

文件，在 compilerOptions 部分添加键值对 "jsx": "react"

2. 添加依赖

npm install --save react react-dom
npm install --save-dev @types/react @types/react-dom

# or
yarn add react react-dom
yarn add --dev @types/react @types/react-dom

3. 开始编程

4. Vue2

（建议使用功能更完善的模板项目：electron-vue，但是默认没有集成 Forge，使用的是electron-packager和electron-builder ）

1. 不使用模板或者使用 webpack 模板初始化一个项目

2. 添加依赖

   npm install --save vue
   
   # or
   yarn add vue
   

3. 开始编程

   src/index.html

   
     {{ message }}
   
   
   

   src/renderer.js

   // Since we declared the script as type=module in the HTML file,
   // we can use ES Modules (adapted from the Vue 2 Introduction
   // https://vuejs.org/v2/guide/#Declarative-Rendering
   
   // Alternatively, omit the .min from the path for Vue debugging purposes.
   import Vue from '../node_modules/vue/dist/vue.esm.browser.min.js'
   
   const app = new Vue({
     el: '#app',
     data: {
       message: 'Hello Vue!'
     }
   })
   

高级功能

自动更新

过程跟 Electron docs. 里描述的一致，Forge 通过配置 publisher 增强了你的工作流程。大致分两种更新方法：

1. 开源的 App - update.electronjs.org

   在 github 上开源的项目可以使用免费的自动更新服务 update.electronjs.org，参考上文配置项说明，设置 publisher - Github，并安装 update-electron-app

   这是最简单的自动更新方式。

2. 非开源的 App - 部署更新服务器

   发布到更新服务器上，比如： nucleus or nuts，详细参考 Electron’s Updating Applications docs.

Debugging

要求 Electron >= 1.8

命令行

在 electron-forge start 启动时加上 --inspect-electron 参数

electron-forge start --inspect-electron

然后在谷歌浏览器里打开 chrome://inspect

For help, see: https://nodejs.org/en/docs/inspector

VScode

launch.config

{
  "type": "node",
  "request": "launch",
  "name": "Electron Main",
  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron-forge-vscode-nix",
  "windows": {
    "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron-forge-vscode-win.cmd"
  },
  // runtimeArgs will be passed directly to your Electron application
  "runtimeArgs": ["foo", "bar"],
  "cwd": "${workspaceFolder}"
}

API 参考

API Docs