潮汐客户端开心版打包教程

Electron是一个使用 JavaScript、HTML 和 CSS 构建桌面应用程序的框架。 Electron 将 Chromium 和 Node.js 嵌入到了一个二进制文件中，因此它允许你仅需一个代码仓库，就可以撰写支持 Windows、macOS 和 Linux 的跨平台应用。

本教程将指导您使用 Electron 开发一个桌面应用，并将其分发给终端用户。

目标​

本教程首先指导您完成从头开始拼凑一个最小的 Electron 应用程序的过程，然后教您如何使用 Electron Forge 打包并将其分发给用户。

如果您希望从单命令样板开始项目，我们建议您使用 Electron Forge 的 create-electron-app 命令。

前言​

Electron 是网页应用 (web apps) 的一个原生包装层，在 Node.js 环境中运行。 因此，本教程假设您已经对 Node.js 和前端 Web 开发有一定地了解。 如果您还需要了解一些背景知识，我们推荐您阅读：

• Web 入门 (MDN Web Docs)
• NodeJS官方入门指南

所需工具​

代码编辑器​

您需要一个文本编辑器来编写代码。 我们建议使用 Visual Studio Code， 您也可以选择自己喜欢的任何一个文本编辑器。

命令行工具​

在整个教程中，我们将要求您使用各种命令行接口 (CLI) 。 您可以使用系统的默认命令行工具：

• Windows: 命令提示符 / PowerShell
• macOS: Terminal
• Linux: 视发行版决定 (如 GNOME 终端 Konsole)

大多数代码编辑器也内置了终端，您也可以使用它们。

Git 和 GitHub​

Git 是常用的版本控制系统，GitHub 是一个基于它的协作开发平台。 虽然它们对开发 Electron 应用而言不是必需的，但我们在后续教程中会使用 GitHub Releases 来实现软件的自动更新。 因此，我们建议您：

• 创建一个 GitHub 账号
• 安装 Git
• https://github.com/git-guides/install-git
  https://git-scm.com

如果您对 Git 还不熟悉，我们推荐阅读 GitHub 的 Git 指南 。 如果您喜欢可视化界面而不是命令行，也可以使用 GitHub Desktop 。

我们建议您创建一个本地 Git 仓库，在阅读教程之前将其推送到 GitHub，并且在完成教程各个步骤后将代码提交上去。

通过 GITHUB DESKTOP 安装 GIT

如果您的操作系统中没有安装 Git，GitHub Desktop 会自动帮您安装 Git 最新版本。

Node.js 和 npm​

要开发 Electron 应用，您需要安装 Node.js 运行环境和它的包管理器 npm。 我们推荐安装最新的长期支持 (LTS) 版本。

提示

请使用为你平台预构建的 Node.js 安装器来进行安装， 否则，您可能会遇到与不同开发工具不兼容的问题。 如果您使用 macOS，我们推荐使用如 Homebrew 或 nvm 这样的包管理器，来避开读写目录权限问题。

要检查 Node.js 是否已被安装，您可以在运行 node 和 npm 命令时，加上 -v 参数。 如果已安装，它们应当会输出对应的版本。

$ node -v
v16.14.2
$ npm -v
8.7.0

学习目标​

在本节，您会学习如何创建您的 Electron 项目，并且编写一个简单的入门程序。 到了本节末尾，您应该能够在终端开发环境运行一个 Electron 应用。

创建项目​

避免使用 WSL

如果您使用的是Windows系统，在本教程中请不要使用 Windows Subsystem for Linux (WSL)，否则您在尝试运行应用时可能会遇到问题。

初始化 npm 项目​

Electron 应用基于 npm 搭建，以 package.json 文件作为入口点。 首先创建一个文件夹，然后在其中执行 npm init 初始化项目。

• npm
• Yarn

mkdir my-electron-app && cd my-electron-app
npm init

这条命令会帮您配置 package.json 中的一些字段。 为本教程的目的，有几条规则需要遵循：

• 入口点 应当是 main.js (您很快就会创建它)
• author、license 和 description 可以是任何值，但在稍后的packaging中是必需的。

然后，将 Electron 安装为您项目的 devDependencies，即仅在开发环境需要的额外依赖。

为什么 ELECTRON 是 DEVDEPENDENCY?

您的应用需要运行 Electron API，因此这听上去可能有点反直觉。 实际上，打包后的应用本身会包含 Electron 的二进制文件，因此不需要将 Electron 作为生产环境依赖。

• npm
• Yarn

npm install electron --save-dev

在初始化并且安装完 Electron 之后，您的 package.json 应该长下面这样。 文件夹中会出现一个 node_modules 文件夹，其中包含了 Electron 可执行文件；还有一个 package-lock.json 文件，指定了各个依赖的确切版本。

package.json

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "Hello World!",
  "main": "main.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Jane Doe",
  "license": "MIT",
  "devDependencies": {
    "electron": "23.1.3"
  }
}

高级安装步骤

如果直接安装 Electron 失败，请参考我们的 安装指导 文档，了解有关下载镜像、代理和故障排除步骤的说明。

添加 .gitignore 文件​

.gitignore 文件可以指定哪些文件和目录应该在Git中不被跟踪。 建议您复制一份 GitHub 的 Node.js gitignore 模板 到您项目的根目录，以避免将 node_modules 文件夹提交到版本控制系统中。

运行 Electron 应用​

:::延伸阅读

参阅 Electron 进程模型(process model) 相关文档来了解 Electron 的进程之间是如何协作的。

:::

您在 package.json 中指定的 main 文件是 Electron 应用的入口。 这个文件控制 主程序 (main process)，它运行在 Node.js 环境里，负责控制您应用的生命周期、显示原生界面、执行特殊操作并管理渲染器进程 (renderer processes)，稍后会详细介绍。

在继续编写您的 Electron 应用之前，您将使用一个小小的脚本来确保主进程入口点已经配置正确。 在根目录的 main.js 文件中写一行代码：

main.js

console.log('Hello from Electron 👋')

因为 Electron 的主进程就是一个 Node.js 运行时，所以你可以直接用 electron 命令运行任意的 Node.js 代码（甚至还能把它当成 REPL 来用）。 要执行这个脚本，需要在 package.json 的 scripts 字段中添加一个 start 命令，内容为 electron . 。 这个命令会告诉 Electron 在当前目录下寻找主脚本，并以开发模式运行它。

package.json

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "Hello World!",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Jane Doe",
  "license": "MIT",
  "devDependencies": {
    "electron": "23.1.3"
  }
}

• npm
• Yarn

npm run start

您的终端应该会输出 欢迎来到 Electron 👋。 恭喜，您已经在 Electron 中执行了您的第一行代码！ 接下来，您会学习如何用 HTML 创建用户界面，并将它们装载到原生窗口中。

将网页装载到 BrowserWindow​

在 Electron 中，每个窗口展示一个页面，后者可以来自本地的 HTML，也可以来自远程 URL。 在本例中，您将会装载本地的文件。 在您项目的根目录中创建一个 index.html 文件，并写入下面的内容：

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <meta
      http-equiv="X-Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <title>Hello from Electron renderer!</title>
  </head>
  <body>
    <h1>Hello from Electron renderer!</h1>
    <p>👋</p>
  </body>
</html>

现在您有了一个网页，您可以将其加载到一个 Electron 的 BrowserWindow 上了。 将 main.js 中的内容替换成下列代码。 我们马上会逐行解释。

main.js

const { app, BrowserWindow } = require('electron')

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()
})

导入模块​

main.js (Line 1)

const { app, BrowserWindow } = require('electron')

在第一行中，我们使用 CommonJS 语法导入了两个 Electron 模块：

• app，这个模块控制着您应用程序的事件生命周期。
• BrowserWindow，这个模块创建和管理 app 的窗口。

打包您的应用程序

使用 Electron Forge​

Electron 的核心模块中没有捆绑任何用于打包或分发文件的工具。 如果您在开发模式下完成了一个 Electron 应用，需要使用额外的工具来打包应用程序 (也称为可分发文件) 并分发给用户 。 可分发文件可以是安装程序 (例如 Windows 上的 MSI) 或者绿色软件 (例如 macOS 上的 .app 文件)。

Electron Forge 是一个处理 Electron 应用程序打包与分发的一体化工具。 在工具底层，它将许多现有的 Electron 工具 (例如 @electron/packager、 @electron/osx-sign、electron-winstaller 等) 组合到一起，因此您不必费心处理不同系统的打包工作。

导入你的项目到 Forge​

将 Electron Forge 的 CLI 工具包安装到项目的 devDependencies 依赖中，然后使用现成的转化脚本将项目导入至 Electron Forge。

• npm
• Yarn

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

转换脚本完成后，Forge 会将一些脚本添加到您的 package.json 文件中。

package.json

  //...
  "scripts": {
    "start": "electron-forge start",
    "package": "electron-forge package",
    "make": "electron-forge make"
  },
  //...

CLI 文档

有关 make 或其他 Forge API 的更多信息，请查看 Electron Forge CLI 文档。

您还应该注意到您的 package.json 现在安装了更多的包 在 devDependencies 下，以及一个导出配置的新 forge.config.js 文件 目的。 您应该在预填充的配置中看到多个makers（生成可分发应用程序包的包），每个目标平台一个。

创建一个可分发版本​

要创建可分发文件，请使用项目中的 make 脚本，该脚本最终运行了 electron-forge make 命令。

• npm
• Yarn

npm run make

该 make 命令包含两步：

1. 它将首先运行 electron-forge package ，把您的应用程序 代码与 Electron 二进制包结合起来。 完成打包的代码将会被生成到一个特定的文件夹中。
2. 然后它将使用这个文件夹为每个 maker 配置生成一个可分发文件。

在脚本运行后，您应该看到一个 out 文件夹，其中包括可分发文件与一个包含其源码的文件夹。

macOS output example

out/
├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip
├── ...
└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app

out/make 文件夹中的应用程序应该可以启动了！ 现在，您已经创建了你的第一个 Electron 程序。

可分发文件格式

Electron Forge 通过配置可以为不同的操作系统创建特定格式的可分发文件 (例如 DMG、deb、MSI 等)。 相关配置选项详情，请参阅 Forge 的 Makers 文档。

创建和添加应用程序图标

设置自定义的应用程序图标，需要添加一些额外的配置。 查看 Forge 的图标教程 了解更多信息。

不使用 ELECTRON FORGE 打包

If you want to manually package your code, or if you’re just interested understanding the mechanics behind packaging an Electron app, check out the full Application Packaging documentation.

重要提示：对代码进行签名​

为了将桌面应用程序分发给最终用户，我们 强烈建议 您对 Electron 应用进行 代码签名。 代码签名是交付桌面应用程序的重要组成部分，并且它对于应用程序的自动更新功能 (将会在教程最后部分讲解) 来说是必需的。

代码签名是一种可用于证明桌面应用程序是由已知来源创建的安全技术。 Windows 和 macOS 拥有其特定的代码签名系统，这将使用户难以下载或启动未签名的应用程序。

在 macOS 上，代码签名是在应用程序打包时完成的。 而在 Windows 中，则是对可分发文件进行签名操作。 如果您已经拥有适用于 Windows 和 macOS 的代码签名证书，可以在 Forge 配置中设置您的凭据。