一小时快速上手Electron——下篇（打包electron应用、打包后生成的目录和文件分别有什么作用、打包过程中可能遇到的问题、electron-vite）

聂可以

878人浏览 · 2025-11-27 09:30:00

聂可以 · 2025-11-27 09:30:00 发布

文章目录

1. 打包electron应用
2. 打包后生成的目录和文件分别有什么作用
3. 打包过程中可能遇到的问题
4. electron-vite

视频教程：禹神：一小时快速上手Electron，前端Electron开发教程

阅读本文前可以先阅读以下博文：

1. 打包electron应用

Electron 的打包有 4 种工具，本文介绍的是较为繁琐的 electron-builder，繁琐归繁琐，electron-builder 能自定义很多内容，而且打包完的体积相对来说会小一点。我们一起来见证一下，我们写的这么简单的一个小东西，打包完之后能有多大

1.1 下载electron-builder开发依赖

我们下载 electron-builder 开发依赖

npm install electron-builder -D

在这里插入图片描述

下载 electron-builder 时控制台会给出以上警告，警告的大概意思是

一些依赖包（如 rimraf、glob 等）使用了过时的版本
这些旧版本可能存在内存泄漏或不再维护的问题
不过不用担心，这些是 electron-builder 的间接依赖，不影响你的项目正常运行

1.2 修改package.json文件

在这里插入图片描述

{
  "name": "electron",
  "version": "1.0.0",
  "description": "electron-quick-start",
  "main": "main.js",
  "scripts": {
    "start": "electron ./",
    "build": "electron-builder"
  },
  "build": {
    "appId": "com.electron.electron-quick-start",
    "win": {
      "icon": "electron.ico",
      "target": [
        {
          "target": "nsis",
          "arch": [
            "x64"
          ]
        }
      ]
    },
    "nsis": {
      "oneClick": false,
      "perMachine": true,
      "allowToChangeInstallationDirectory": true
    }
  },
  "author": "nie-ke-yi",
  "license": "ISC",
  "devDependencies": {
    "electron": "^38.4.0",
    "electron-builder": "^26.0.12",
    "nodemon": "^3.1.10"
  }
}

build 命令中各个参数的含义如下

appId

com.electron.electron-quick-start 是应用的唯一标识符，类似包名

win Windows 平台配置

icon: 指定应用图标为 electron.ico
target: 目标打包格式
- nsis: 使用 NSIS 作为安装程序格式
- arch: 只打包 64 位版本（x64）

nsis 安装程序配置

oneClick: false: 不是一键安装，会显示传统安装向导
perMachine: true: 默认为所有用户安装（需要管理员权限）
allowToChangeInstallationDirectory: true: 允许用户自定义安装路径

1.3 添加electron.ico图标

1.3.1 从图标库中获取图标

build 命令中的 icon 可以配置应用的图标，我们使用阿里巴巴图标库中的 Electron 图标，当然，你也可以使用其它图标

阿里巴巴图标库：Electron

https://www.iconfont.cn/search/index?searchType=icon&q=Electron

在这里插入图片描述

选择完颜色后下载 png 文件

在这里插入图片描述

1.3.2 将下载好的png文件转换为ico文件

下载好文件后，打开 https://www.freeconvert.com/zh 网址，点击从设备选项上传文件

https://www.freeconvert.com/zh

在这里插入图片描述

上传文件后，我们更改文件的输出格式，选择ICO格式

在这里插入图片描述

点击输出格式旁边的设置

在这里插入图片描述

格式和大小我们选择256 x 256选项

在这里插入图片描述

选择完毕后点击应用设置按钮

在这里插入图片描述

点击转变->按钮

在这里插入图片描述

转换完毕后点击下载按钮将 ico 文件下载到本地

在这里插入图片描述

1.3.3 将ico文件拷贝到项目的根目录下

将 icon 文件拷贝到项目的根目录下（名字可以自定义，与 build 命令中的 icon 属性对应就可以了）

在这里插入图片描述

1.4 执行打包操作

打包时需要从 GitHub 上下载文件，如果无法正常打开 GitHub，可以参考我的另一篇文章：GitHub的使用技巧（加速访问GitHub、查看GitHub的热门项目、查看GitHub推荐的项目、Fork、Issue、快速找到项目的安装包、GitHub的各种快捷键）

执行打包操作前记得开启 GitHub 访问加速或者直接使用魔法

点击 package.json 文件 build 指令前面的小三角执行打包操作，也可以在项目的终端中运行 npm build 指令来执行打包操作

npm run build

在这里插入图片描述

执行完打包操作之后，安装包在哪儿呢？在项目的根目录中一个名为 dist 的目录下，我们在资源管理器中打开 dist 文件夹

在这里插入图片描述

我们右键 electron Setup 1.0.0.exe 文件，查看文件的大小

在这里插入图片描述

可以发现安装包的大小为 220 MB，我们没有编写任何复杂的功能，安装包大小就达到了两百多 MB，说明 electron 应用打包后的体积还是偏大的，因为打包后的结果中包含一个 Chrome 浏览器，还有 Node.js 环境

打包体积偏大是 electron 固有的问题，但是我还是想跟你说，很多知名的软件也都是用 electron 写的，而且现在硬盘空间至少也有几百个 G，相对于 electron 的优势来说，打包体积偏大的问题可以忽略

2. 打包后生成的目录和文件分别有什么作用

在这里插入图片描述

2.1 📁 win-unpacked 目录

这是未打包的可执行程序目录，包含：

应用的所有运行时文件（exe、dll、资源文件等）
可以直接双击运行，无需安装
主要用于开发和测试阶段，方便快速验证功能
后续会基于这个目录打包成安装程序

2.2 📄 electron Setup 1.0.0.exe（分发给用户使用的安装文件）

这是最终的Windows安装程序（NSIS打包产物）：

用户双击即可完成应用的安装、卸载
包含你在package.json中配置的所有安装选项（如安装目录选择、快捷方式等）
这是分发给用户使用的安装文件

2.3 📄 electron Setup 1.0.0.exe.blockmap

这是增量更新映射文件：

记录安装包中每个数据块的哈希值和位置
用于实现增量更新，用户更新时只需下载变化的部分
大幅减少更新流量和耗时
需要配合electron-updater使用

2.4 📄 builder-debug.yml

这是调试模式配置文件：

定义调试阶段的构建规则
包含日志级别、临时文件路径等调试参数
开发时用于排查构建问题

2.5 📄 builder-effective-config.yaml

这是实际生效的合并配置文件：

融合了package.json中的build配置和其他自定义配置
记录了构建时使用的所有参数
用于回溯和排查配置问题

2.6 🔄 electron-builder整体的工作流程

electron-builder 整体的工作流程是：

先构建未打包版本（win-unpacked）
基于未打包版本生成安装程序（exe）
同时生成配置文件和更新映射文件

这样设计的好处是既支持开发调试，又方便最终分发和后续更新维护

3. 打包过程中可能遇到的问题

3.1 image F:\Blog\electron\electron.ico must be at least 256x256

如果在打包过程中遇到以下问题，是因为 ico 文件的尺寸太小了，打包所用到的 ico 文件尺寸至少是 256 x 256

• electron-builder version=26.0.12 os=10.0.19045
• loaded configuration file=package.json (“build” field)
• writing effective config file=dist\builder-effective-config.yaml
• executing @electron/rebuild electronVersion=38.4.0 arch=x64 buildFromSource=false appDir=./
• installing native dependencies arch=x64
• completed installing native dependencies
• packaging platform=win32 arch=x64 electron=38.4.0 appOutDir=dist\win-unpacked
• updating asar integrity executable resource executablePath=dist\win-unpacked\electron.exe
⨯ image F:\Blog\electron\electron.ico must be at least 256x256
npm notice
npm notice New major version of npm available! 10.9.4 -> 11.6.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.6.2
npm notice To update run: npm install -g npm@11.6.2
npm notice

在这里插入图片描述

解决方法参考本文的添加electron.ico图标部分

3.2 Reserved header is not 0 or image type is not icon for ‘F:\Blog\electron\electron.ico’

如果在打包过程中遇到以下问题，是因为你的 ico 文件有问题，大概率是因为你的 ico 文件是简单地将 png 文件或 jpg 文件改了后缀名后得来的

• electron-builder version=26.0.12 os=10.0.19045
• loaded configuration file=package.json (“build” field)
• writing effective config file=dist\builder-effective-config.yaml
• executing @electron/rebuild electronVersion=38.4.0 arch=x64 buildFromSource=false appDir=./
• installing native dependencies arch=x64
• completed installing native dependencies
• packaging platform=win32 arch=x64 electron=38.4.0 appOutDir=dist\win-unpacked
• updating asar integrity executable resource executablePath=dist\win-unpacked\electron.exe
⨯ cannot execute cause=exit status 1
errorOut=Reserved header is not 0 or image type is not icon for ‘F:\Blog\electron\electron.ico’
Fatal error: Unable to set icon

在这里插入图片描述

解决方法参考本文的添加electron.ico图标部分

3.3 下载electron-v38.4.0-win32-x64.zip文件时卡住

打包过程中会用到 electron-v38.4.0-win32-x64.zip 文件，文件的大小为 136 M

从日志中可以看出，是从 GitHub 上下载 electron-v38.4.0-win32-x64.zip 文件的，但是即使我们开启 GitHub 加速或者使用魔法，在下载文件这一步还是会卡住

• electron-builder version=26.0.12 os=10.0.19045
• loaded configuration file=package.json (“build” field)
• writing effective config file=dist\builder-effective-config.yaml
• executing @electron/rebuild electronVersion=38.4.0 arch=x64 buildFromSource=false appDir=./
• installing native dependencies arch=x64
• completed installing native dependencies
• packaging platform=win32 arch=x64 electron=38.4.0 appOutDir=dist\win-unpacked
• downloading url=https://github.com/electron/electron/releases/download/v38.4.0/electron-v38.4.0-win32-x64.zip size=136 MB parts=8

在这里插入图片描述

我们可以提前从 GitHub 上下载 electron-v38.4.0-win32-x64.zip 文件

下载文件完毕后，我们在项目的根目录下创建一个名为 electron-cache 的目录，将下载好的文件拷贝到 electron-cache 目录中

electron-cache

在这里插入图片描述

将下载好的文件拷贝到 electron-cache 目录中后，向 package.json 文件 build 指令中添加 electronDownload 属性，指定下载时使用的缓存目录

在这里插入图片描述

"electronDownload": {
  "cache": "./electron-cache"
}

指定下载时使用的缓存目录后，打包时就会直接使用我们拷贝到缓存目录中的文件，而不会再次通过 GitHub 下载

3.4 ERROR: Cannot create symbolic link : electron-builder\Cache\winCodeSign\190103631\darwin\10.12\lib\libcrypto.dylib

如果在打包过程中遇到以下问题，是因为打包过程卡在了解压一个叫 winCodeSign 的工具包上。这个工具包里包含了一些用于给 macOS 应用签名的文件

ERROR: Cannot create symbolic link : �ͻ��û��Ȩ�� : C:\Users\��\AppData\Local\electron-builder\Cache\winCodeSign\190103631\darwin\10.12\lib\libssl.dylib

在这里插入图片描述