Electron 内网离线打包全攻略

一、背景与问题核心

近期维护一个内网传统网页开发项目，该项目采用「网页+Electron壳」的架构。由于原Electron版本过旧，导致项目中依赖的Antv G6 v5图表库出现兼容性问题（表现为图表渲染异常或功能报错）。升级Electron本身可参考官方文档快速实现，但内网环境下打包时无法联网下载预编译二进制文件，成为本次迁移的核心难点。本文将详细记录完整解决方案，帮助有类似需求的开发者避坑。

二、完整实操流程

整个过程分为「依赖安装配置」和「离线缓存准备」两大步骤，确保开发环境运行与内网打包均正常。

Step 1：安装并配置Electron依赖

Electron默认会根据当前系统自动下载对应平台的预编译包，但内网环境需提前指定下载参数，避免后续打包时依赖网络。

1.1 创建.npmrc文件固定下载参数

在项目根目录新建.npmrc文件，写入以下内容（根据实际需求修改平台和架构，此处以Windows x64为例）：

# .npmrc 配置
# 系统架构（x64/arm64等）
arch=x64
# 操作系统（win32/mac/linux等）
platform=win32
# 可选：设置npm镜像（非必需，若内网有镜像可配置）
# registry=https://your-internal-npm-mirror.com/

1.2 安装核心依赖

执行以下命令安装Electron及打包工具@electron-forge/cli（用于后续打包操作）：

# 安装开发依赖

npm install electron @electron-forge/cli --save-dev
# 将项目导入Electron Forge（自动生成打包配置文件forge.config.js）

npx electron-forge import

1.3 验证开发环境

确保package.json中已指定Electron入口文件（通过main字段配置，如"main": "main.js"），随后运行以下命令启动项目，验证Antv G6兼容性是否解决：
npm run start
💡 注意：若启动后图表仍异常，可检查Antv G6是否与当前Electron版本匹配（参考G6官方兼容性说明），或清除node_modules后重新安装依赖。

Step 2：准备离线缓存文件

Electron打包时需依赖预编译二进制文件，内网环境无法联网下载，因此需提前在外网环境下载对应文件并配置缓存路径。

2.1 下载对应版本的Electron预编译包

- electron-v38.4.0-win32-x64.zip（对应系统的预编译包）

- SHASUMS256.txt（文件校验码，用于验证完整性）

2.2 校验文件完整性（可选但推荐）

下载完成后，通过校验工具（如Windows的PowerShell、Linux/macOS的终端）验证文件哈希值是否与SHASUMS256.txt一致，避免文件损坏：

Windows PowerShell示例（替换文件名和版本号）

Get-FileHash .\electron-v38.4.0-win32-x64.zip -Algorithm SHA256 | Select-Object Hash
将输出的哈希值与SHASUMS256.txt中对应文件名的哈希值对比，一致则文件完整。

2.3 配置forge.config.js离线缓存路径

在项目根目录创建electron-cache文件夹，将下载的预编译包和校验文件放入其中。然后修改forge.config.js，在packagerConfig中添加缓存配置：

const { FusesPlugin } = require("@electron-forge/plugin-fuses");
const { FuseV1Options, FuseVersion } = require("@electron/fuses");
const path = require("path");

module.exports = {
packagerConfig: {
asar: true, // 启用asar打包（可选，用于压缩和保护资源）
download: {
// 本地缓存镜像路径（绝对路径更稳妥）
mirror: path.resolve(__dirname, "electron-cache"),
cache: path.resolve(__dirname, "electron-cache"),
focus: false, // 禁用下载进度聚焦（避免终端干扰）

    },
electronZipDir: path.resolve(__dirname, "electron-cache/"), // 预编译包所在目录

  },
// ... 其他配置

};

2.4 执行内网离线打包

完成上述配置后，在项目根目录执行打包命令，Electron Forge将从本地缓存读取预编译包，无需联网：

npm run make

打包成功后，可在项目根目录的out文件夹中找到对应系统的安装包或绿色版程序。

三、关键注意事项

• 
  
• 路径必须准确：配置中使用path.resolve生成绝对路径，避免相对路径导致的缓存找不到问题；
  
• 文件名严格匹配：本地缓存的预编译包文件名需与官方一致（如electron-v{version}-{platform}-{arch}.zip），否则无法识别；
  
• 多系统适配：若需打包多个系统（如Windows和macOS），需下载对应平台的预编译包放入缓存文件夹，无需修改配置；
  
• 版本号统一：确保package.json中的Electron版本与下载的预编译包版本完全一致，避免兼容性问题。
  

四、总结

本次Electron升级及内网打包的核心是「提前配置下载参数+本地缓存预编译包」。通过固定.npmrc参数确保依赖安装时匹配目标系统，再通过配置Forge的缓存路径实现离线打包，最终解决了Antv G6的兼容性问题和内网环境限制。若后续需升级Electron版本，只需重复「下载对应版本预编译包→更新缓存文件夹」的步骤即可。
如果遇到其他特殊场景（如内网npm镜像配置、asar包解压问题），欢迎在评论区交流讨论！