Electron-Builder 打包 Vue 项目避坑指南

最近在开发一个基于 Vue 的 Electron 项目，在打包时遇到了诸多问题，为了解决这些问题也查阅了非常多的资料，排除了很多坑。现在将可能遇到的问题整理成避坑指南，供大家参考（此避坑指南后续还会继续更新）。

依赖版本

“electron”: “^30.0.1”,
“electron-builder”: “^24.13.3”,
“electron-builder-squirrel-windows”: “^24.13.3”,
“electron-devtools-installer”: “^3.2.0”,
“electron-rebuild”: “^3.2.9”,
“vue”: “^3.4.26”,
node: 18.19.0

1. NPM换源

近期淘宝源更换域名导致非常多的朋友遇到npm无法使用的问题。应在用户文件夹下的 .npmrc 文件中添加这两行：

registry=https://registry.npmmirror.com/
electron_mirror=https://npmmirror.com/mirrors/electron/
1
2

2. 路由问题

应当将 Vue-Router 更改为 hash 模式，以避免白屏问题。

3. Builder配置的位置问题

最新版本的electron-builder配置得写在vue.config.js中才能生效。但网上好多文章都是直接在package.json里面配置，还有在electron生成的background.js里配置的。
因此我们应该在项目文件夹的vue.config.js中撰写配置：

module.exports = {
  //判断开发模式还是生产模式
  publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
  //插件配置
  pluginOptions: {
    //electronBuilder配置
    electronBuilder: {
      builderOptions: {
        'productName': 'all electron',//生成exe的名字
        "appId": "com.xi.www",//包名  
        "copyright": "xi",//版权信息
        "directories": { // 输出文件夹
          "output": "electron_output",
        },
        "nsis": {
          "oneClick": false, // 是否一键安装
          "allowElevation": true, // 允许请求提升。若为false，则用户必须使用提升的权限重新启动安装程序。
          "allowToChangeInstallationDirectory": true, //是否允许修改安装目录
          "installerIcon": "./build/icons/icon.ico",// 安装时图标
          "uninstallerIcon": "./build/icons/icon.ico",//卸载时图标
          "installerHeaderIcon": "./build/icons/icon.ico", // 安装时头部图标
          "createDesktopShortcut": true, // 是否创建桌面图标
          "createStartMenuShortcut": true,// 是否创建开始菜单图标
          "shortcutName": "all-electron", // 快捷方式名称
          "runAfterFinish": false,//是否安装完成后运行
        },
        "win": {
          "icon": "build/icons/icon.ico",//图标路径
          "target": [
            {
              "target": "nsis", //利用nsis制作安装程序
              "arch": [
                "x64", //64位
                // "ia32" //32位
              ]
            }
          ]
        }
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

注意严格检查配置格式，如果某个配置的格式或层级关系写得不对，配置是无法生效的，且运行npm run electron:build时有时也不会警告。

4. 静态资源的打包问题

对于在渲染进程中使用到的静态资源，Webpack会自动帮我们打包，但是主进程使用到的静态资源却不会被正常打包进应用中，因此我们需要使用extraResources或extraFiles的方式配置好需要打包的静态资源。
这里我在项目的根目录下新建了一个static文件夹，将静态资源放在里面。
在vue.config.js中做如下配置：

pluginOptions: {
        electronBuilder: {
            nodeIntegration: true,
            builderOptions: {
                ...
                extraResources: ["./static/"]
            }
        }
    }
1
2
3
4
5
6
7
8
9

然后在主进程代码中需要用到静态资源的地方，分情况处理静态资源的路径，分为调试时路径和运行时路径两种：

    let iconPath;
    if (process.env.WEBPACK_DEV_SERVER_URL) {
        iconPath = path.join(__dirname, '../static/icon.png');
    } else {
        iconPath = path.join(process.cwd(), '/resources/static/icon.png');
    }
1
2
3
4
5
6

这样就解决了静态资源无法打包的问题。

5. 图标字体不显示

iconfont.cn站点的字体图标下载到本地，采用Font class的方式调用，在开发预览环境中调用正常；可是打包后不显示字体图标。
其他各种框架的基于 字体 实现的图标也遇到了相同的问题。
在vue.config.js中设置 customFileProtocol字段：

pluginOptions: {
	electronBuilder: {
		customFileProtocol: "/"
	}
}
1
2
3
4
5

即可解决以上问题。