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 发布的通道号,或者其他形式的唯一标识符。例如,设为 prodbeta

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 startyarn start,在终端输入 rs 并按回车可以快速重启应用。

Electron脚手架 - ElectronForge使用文档_第1张图片
  • -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"

  1. 添加依赖
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
  1. 开始编程

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

你可能感兴趣的:(electron)