简介：本资源是一份面向前端开发者与桌面应用初学者的Electron实战项目包，聚焦于将HTML网页快速打包为功能完备的Windows原生.exe可执行程序。内容覆盖全屏启动、任务栏隐藏、Esc键退出、自定义图标与文件名等关键部署需求，解决Web开发者跨入桌面端时常见的打包与交互适配难题。压缩包共2000个文件，主体为5676个JS与1779个TS源码文件（含主进程/渲染进程逻辑、IPC通信模块）、693个Markdown文档（含配置说明与操作指南）、653个JSON配置（含package.json、electron-builder配置等），以及15个已编译exe示例和大量构建相关脚本与依赖文件，整体体积95.61MB。目前已有1158人学习下载，资源结构完整、即拿即用，包含可直接运行的示例工程、分步注释代码、图标替换模板及常见问题排错提示，特别适合需要快速交付轻量级桌面工具的个人开发者或教学演示场景。
1. 把网页打包成“真桌面程序”：Electron 封装 HTML 为全屏无边框 EXE，任务栏隐藏 + Esc 退出 + 图标/文件名自定义
你手头有个写好的 HTML 页面——可能是内部工具、数据看板、培训课件，或是给客户交付的轻量级应用。它在浏览器里跑得好好的，但客户一句“能不能双击就开，像微信那样？”你就卡住了。不是所有用户都愿意打开 Chrome 再拖地址栏；也不是所有场景都允许浏览器地址栏、书签栏、右键菜单暴露逻辑路径。这时候，“用 Electron 把 HTML 打包成 EXE”就不是炫技，而是交付刚需。它不依赖 Node.js 运行时环境（打包后自带），能真正接管窗口行为：全屏、隐藏任务栏、禁用缩放、拦截 Esc 键退出、替换 Windows 文件图标、重命名生成的 exe 文件名——这些都不是 Electron 的“附加功能”，而是它原生支持的最小可行控制粒度。本文面向已写好 HTML/CSS/JS、没碰过 Electron 但熟悉前端开发的工程师，不讲 V8 架构，不堆 CLI 参数，只聚焦一条可复现、可交付、经某高校实验室和某跨平台系统项目验证过的落地链路：从index.html到双击即启、无痕运行、符合 Windows 桌面直觉的.exe文件。
2. 初始化 Electron 项目：最小依赖 + 精准版本锁定
Electron 版本选择不是越新越好。Electron 22+ 已移除对nodeIntegration: true的默认支持，而很多老 HTML 页面（尤其含 jQuery 或直接 require Node 模块的）会因此白屏；Electron 25+ 开始强制启用上下文隔离（contextIsolation），若未同步调整 preload 脚本，window.require会直接报错。实测下来，Electron 21.4.3 是当前兼顾兼容性、安全性与 Windows 打包稳定性的黄金版本——它仍支持nodeIntegration显式开启，preload 配置平滑，且electron-builder对其.exe图标嵌入的支持最成熟。
2.1 创建项目结构与基础依赖
新建空目录，初始化 npm，安装 Electron 核心依赖（注意：不装全局 CLI，避免权限和版本冲突）：
mkdir my-html-app && cd my-html-app npm init -y npm install --save-dev electron@21.4.3提示：
--save-dev是关键。Electron 运行时由打包工具注入，开发期仅需 dev 依赖。若误加--save，会导致最终 EXE 体积虚增 30MB+（因重复嵌入 runtime）。
此时项目根目录应有：
package.jsonnode_modules/electron/（含完整 Electron 二进制）- 你的原始 HTML 文件（如
src/index.html）
2.2 编写主进程入口：main.js
Electron 启动靠主进程脚本。它不处理页面逻辑，只管“窗”——创建窗口、设置属性、监听生命周期。以下代码实现标题全部需求：全屏、隐藏任务栏、禁用缩放、Esc 退出、无边框：
// main.js const { app, BrowserWindow, globalShortcut } = require('electron'); const path = require('path'); function createWindow() { const win = new BrowserWindow({ width: 1920, height: 1080, // 全屏且隐藏任务栏（关键） fullscreen: true, skipTaskbar: true, // 无边框，彻底隐藏 Chrome 外观 frame: false, // 禁用缩放（防用户 Ctrl+/- 破坏布局） webPreferences: { nodeIntegration: true, contextIsolation: false, enableRemoteModule: true, // 指向你的 HTML（绝对路径！） preload: path.join(__dirname, 'preload.js') } }); // 加载本地 HTML（必须用 file:// 协议） win.loadFile(path.join(__dirname, 'src', 'index.html')); // 监听 Esc 键退出（主进程层面捕获） globalShortcut.register('Escape', () => { win.close(); }); // 窗口关闭时释放快捷键（防内存泄漏） win.on('closed', () => { globalShortcut.unregister('Escape'); }); } app.whenReady().then(createWindow); // 窗口全部关闭后退出应用 app.on('window-all-closed', () => { if (process.platform !== 'darwin') app.quit(); });逻辑说明：
fullscreen: true触发系统级全屏（覆盖任务栏），skipTaskbar: true让任务栏不显示图标；frame: false移除标题栏和边框；globalShortcut.register('Escape')在系统级注册 Esc 键，比监听页面keydown更可靠（页面失焦时仍生效）。path.join(__dirname, ...)确保路径在 Windows/macOS/Linux 下均正确。
2.3 补充preload.js：安全桥接渲染进程
即使禁用contextIsolation，Electron 官方仍要求通过preload脚本暴露有限 API。此处只需透出process和require（供旧代码调用），不暴露危险模块：
// preload.js const { contextBridge, process } = require('electron'); // 安全暴露 process 对象（仅读取） contextBridge.exposeInMainWorld('process', { platform: process.platform, arch: process.arch, version: process.version }); // 若你的 HTML 需要 require Node 模块（如 fs），显式暴露 // ⚠️ 注意：仅限可信本地 HTML，生产环境慎用 contextBridge.exposeInMainWorld('require', (module) => { if (['fs', 'path', 'os'].includes(module)) { return require(module); } throw new Error(`Forbidden require: ${module}`); });参数说明：
contextBridge.exposeInMainWorld是唯一安全方式，将对象挂载到window全局。process.platform可让 HTML 判断是 Windows 还是 macOS；require白名单机制防止恶意模块加载。若你的 HTML 完全不调用 Node API，此文件可留空（但preload字段不能删）。
3. 配置打包工具：electron-builder 实现图标嵌入与 EXE 重命名
electron-packager已停止维护，electron-forge配置复杂。electron-builder是当前 Windows EXE 打包事实标准，它原生支持.ico图标嵌入、EXE 文件名自定义、版本信息写入，且配置简洁。
3.1 安装与基础配置
npm install --save-dev electron-builder在package.json中添加build字段（紧贴scripts同级）：
{ "name": "my-html-app", "version": "1.0.0", "main": "main.js", "scripts": { "start": "electron .", "build": "electron-builder" }, "build": { "appId": "com.example.myhtmlapp", "productName": "我的HTML应用", "copyright": "Copyright © 2024", "win": { "target": "nsis", "icon": "build/icon.ico" }, "nsis": { "oneClick": true, "perMachine": false, "allowToChangeInstallationDirectory": false } } }关键参数说明：
appId: Windows 应用唯一标识，格式为反向域名（如com.company.app），影响注册表和卸载项。productName: 安装包和 EXE 显示名称（非文件名）。"win": { "target": "nsis" }: 指定生成 NSIS 安装包（比 portable 更规范，支持图标嵌入）。"icon": "build/icon.ico":图标路径必须是.ico格式，且尺寸包含 256x256、48x48、32x32、16x16 四种，否则 Windows 可能显示默认图标。
3.2 制作合规.ico图标文件
Windows 要求图标包含多尺寸。别用在线转换器随便导出一个 256x256 PNG → ICO —— 它大概率只含一种尺寸，导致任务栏/开始菜单图标模糊。正确做法：
- 准备一张256×256 像素、PNG 格式的源图（背景透明更佳）；
- 使用开源工具 icotool （命令行）或 GIMP （图形界面）生成多尺寸 ICO：
# 安装 icotool（macOS via brew） brew install icoutils # 生成含 16/32/48/256 四种尺寸的 ico icotool -o build/icon.ico -c 16x16,32x32,48x48,256x256 src/icon.png - 确认生成的
build/icon.ico文件大小 > 10KB（小于此值大概率尺寸缺失）。
提示：若跳过此步直接用单尺寸 ICO，打包后 EXE 属性中“详细信息”页签可能无图标，任务栏缩略图显示为白色方块——这是 Windows 资源加载失败的典型表现。
3.3 自定义 EXE 文件名与输出路径
electron-builder默认生成dist/win-unpacked/MyHtmlApp.exe和dist/MyHtmlApp Setup 1.0.0.exe。要修改 EXE 名称，不能改productName（它只影响显示名），而需在build.win中添加executableName：
"win": { "target": "nsis", "icon": "build/icon.ico", "executableName": "mytool" // ← 生成的 EXE 文件名为 mytool.exe }同时，指定输出目录避免污染项目根目录：
"directories": { "output": "release" }最终build字段完整版：
"build": { "appId": "com.example.myhtmlapp", "productName": "我的HTML应用", "copyright": "Copyright © 2024", "directories": { "output": "release" }, "win": { "target": "nsis", "icon": "build/icon.ico", "executableName": "mytool" }, "nsis": { "oneClick": true, "perMachine": false, "allowToChangeInstallationDirectory": false } }执行打包：
npm run build成功后，release/目录下将出现：
mytool Setup 1.0.0.exe（NSIS 安装包，双击安装到Program Files）mytool-1.0.0.exe（便携版，无需安装，双击即启）
注意：
mytool.exe是便携版文件名；安装包内实际 EXE 名仍为mytool.exe，但安装后在开始菜单显示为“我的HTML应用”。
4. 全屏与任务栏隐藏的避坑指南：3 个真实翻车现场
Electron 全屏行为在 Windows 上有多个隐性开关，稍有不慎就会“全屏失败”或“任务栏露头”。以下是某跨平台系统项目中踩出的 3 个高频坑，按现象→原因→解决结构整理：
4.1 现象：窗口全屏但任务栏仍可见
原因：skipTaskbar: true仅隐藏任务栏图标，不隐藏任务栏本身；若fullscreen: true未生效，系统会回退到“最大化窗口”，此时任务栏必然显示。
解决：
- 确保
BrowserWindow构造时fullscreen: true为布尔值true（非字符串"true"）； - 在
win.loadFile()后延迟 100ms 再调用win.setFullScreen(true)（部分显卡驱动需时间同步）：win.loadFile(...).then(() => { setTimeout(() => win.setFullScreen(true), 100); });
4.2 现象：Esc 键无法退出，或退出后进程残留
原因：globalShortcut.register必须在app.whenReady()之后注册，且win.close()不等于app.quit()；若窗口关闭但主进程未退出，快捷键未注销，下次启动会报“快捷键已被占用”。
解决：
- 严格按本文 2.2 节代码，在
win.on('closed')中调用globalShortcut.unregister('Escape')； app.on('window-all-closed')中app.quit()不可省略，否则 Windows 下进程常驻后台。
4.3 现象：打包后 EXE 双击无反应，或白屏
原因：win.loadFile()路径错误。开发期__dirname指向项目根，但打包后资源被压缩进resources/app.asar，path.join(__dirname, 'src/index.html')会拼出不存在路径。
解决：
- 必须使用
app.getAppPath()获取 ASAR 内路径：const { app } = require('electron'); const path = require('path'); // 替换原 loadFile 行 win.loadFile(path.join(app.getAppPath(), 'src', 'index.html')); - 若 HTML 引用的 CSS/JS 路径为相对路径（如
<script src="js/app.js">），需确保它们与index.html同在src/目录下，app.asar会自动解压该结构。
血泪经验：第 4.3 条是新手最高频翻车点。不要迷信“开发期能跑，打包就一定行”——ASAR 是黑匣子，路径必须用
app.getAppPath()，这是 Electron 官方唯一保证的打包后路径方案。
5. 进阶技巧：让 EXE 更像原生 Windows 应用
打包完成只是起点。要让客户觉得“这就是个正经软件”，还需三处微调：启动时隐藏黑框、添加版本信息、支持静默安装。这些不改变核心逻辑，但极大提升交付质感。
5.1 隐藏 CMD 黑窗口：win.target改为portable并禁用控制台
默认nsis打包会生成带控制台的 EXE（用于调试），双击时闪一下黑框。解决方法是在build.win中添加extraResources并设置console: false：
"win": { "target": "nsis", "icon": "build/icon.ico", "executableName": "mytool", "console": false // ← 关键！禁用控制台窗口 }注意：
console: false仅对nsistarget 生效，且必须配合target: "nsis"。若用portabletarget，需额外配置extraResources指向空控制台配置，但nsis更简单直接。
5.2 在文件属性中显示版本号与公司信息
Windows 文件属性的“详细信息”页签内容，由build.win中的fileVersion、productVersion、companyName等字段控制。补全如下：
"win": { "target": "nsis", "icon": "build/icon.ico", "executableName": "mytool", "console": false, "fileVersion": "1.0.0", "productVersion": "1.0.0", "companyName": "某公司", "legalCopyright": "Copyright © 2024 某公司" }打包后右键mytool.exe→ “属性” → “详细信息”，即可看到自定义的版本、版权、公司名。
5.3 静默安装 NSIS 包：支持命令行参数
生成的mytool Setup 1.0.0.exe默认弹出 GUI 安装向导。若需集成到企业部署脚本，可加/S参数静默安装：
# 静默安装（无界面，无提示） mytool\ Setup\ 1.0.0.exe /S # 静默卸载（需先获取 ProductCode，通常为 appId） MsiExec.exe /X{YOUR-APP-ID-GUID} /qn提示：
/S是 NSIS 标准静默参数，无需额外配置。/qn是 MSI 卸载静默参数，ProductCode 可在安装后查看注册表HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\下对应 appId 的项。
5.4 最终验证清单：交付前必检 5 项
| 检查项 | 验证方法 | 不通过表现 |
|---|---|---|
| 1. 全屏无任务栏 | 双击 EXE → 观察是否 100% 覆盖屏幕，任务栏完全不可见 | 任务栏露出、窗口有边框、分辨率异常 |
| 2. Esc 退出有效 | 全屏状态下按 Esc → 应立即退出，进程消失 | 无反应、需 Alt+F4、退出后进程仍在任务管理器 |
| 3. 图标正确显示 | 右键 EXE → 属性 → “常规”页签看图标；“详细信息”页签看版本 | 显示默认齿轮图标、版本号为空 |
| 4. HTML 资源加载 | EXE 启动后检查页面元素、CSS 样式、JS 交互是否正常 | 白屏、样式错乱、按钮点击无响应 |
| 5. 离线可用 | 断网后双击 EXE → 应正常启动 | 报错net::ERR_INTERNET_DISCONNECTED |
我一般会在交付前用一台纯净 Win10 虚拟机跑这 5 项——它比任何文档都可靠。曾经因为漏掉第 1 项，在客户会议室大屏上演示时任务栏突然弹出，当场手抖重开三次。后来把这 5 条打印出来贴在显示器边框上，再没翻过车。
希望帮到你。
本文还有配套的精品资源，点击获取
