简介：这份资源面向希望把本地HTML页面封装成Windows桌面程序的开发者，尤其适合已掌握HTML、CSS与JavaScript、想快速上手Electron打包流程的前端人员。内容围绕Electron框架展开，覆盖将网页资源打包为.exe可执行文件、窗口全屏显示、隐藏任务栏图标、监听Esc键退出程序，以及通过electron-packager或electron-builder自定义exe图标与输出文件名等实用知识点，并涉及版本管理、错误处理与跨平台测试等注意事项。压缩包共约2000个文件，以js、ts源码及map映射文件为主，辅以json配置、md说明文档、license许可文件与少量pak、exe等运行时资源，整体约95.61MB，目录结构完整，便于对照查阅依赖与打包配置。目前已有1161人学习下载，可作为从网页到桌面应用落地的参考工程，帮助读者理解主进程与渲染进程通信、窗口属性设置及打包参数配置等关键环节。

1. 从网页到桌面程序：为什么我选 Electron 而不是直接打包浏览器快捷方式

很多做内部工具的朋友都遇到过这个场景：用 HTML+CSS+JS 写好了一个数据看板或者操作面板，本地双击打开就能用，但一旦发给非技术同事，问题就来了——有人用 Chrome，有人用 Edge，还有人默认浏览器是某个套壳的，打开后地址栏、书签栏、插件栏全露在外面，看着就不像个正经软件。更麻烦的是，如果这个页面需要全屏展示，比如车间里的看板、展厅里的查询机、收银台的操作界面，浏览器那几行 UI 会直接破坏沉浸感。

我试过几种方案：用 kiosk 模式启动浏览器，但不同浏览器参数不一样，而且任务栏还是可能弹出来；用 HTA，兼容性玄学，Win11 上各种报错；用 NW.js，打包体积和文档更新速度劝退。最后落到 Electron，原因很直接——它把 Chromium 和 Node.js 一起打包，你写的是网页，得到的是一个真正的 exe，窗口怎么显示、任务栏怎么处理、退出键怎么绑定，全在你自己手里。

这份资源要解决的就是这个完整链路：把一个本地 HTML 文件（或整个静态目录）转成单文件 exe，要求全屏、遮住任务栏、Esc 退出、自定义图标和文件名。适合手里有现成网页、不想重写、只想快速交付一个桌面壳的开发者。下面按我实际踩过的流程拆开讲。

2. 环境搭建与项目初始化：从零到能跑起来的 Electron 壳

2.1 为什么不用 electron-forge 或 electron-builder 的默认模板

Electron 的脚手架很多，electron-forge、electron-builder、electron-packager 各有拥趸。我一开始用 electron-forge，它默认生成的项目结构比较重，带了一堆示例代码和配置，对于“只想包一个本地 HTML”的需求来说，清理成本比从头搭还高。后来我固定用最朴素的方式：手动建 package.json，装 electron 和 electron-builder 两个依赖，自己写 main.js。这样每一步做了什么、哪个参数控制哪个行为，心里有数。

另一个原因是图标替换。electron-forge 的图标配置在不同版本里改过几次路径规则，而 electron-builder 的 win.icon 参数一直很稳定，直接指向 .ico 文件就行。对于需要频繁改图标和文件名的场景，electron-builder 的配置更直观。

2.2 初始化步骤与依赖安装

先建一个空目录，名字随意，比如web-to-exe。在里面执行：

npm init -y npm install electron --save-dev npm install electron-builder --save-dev

装完后 package.json 里会有两个 devDependencies。注意 Electron 的版本，我写这篇文章时稳定版是 28.x，但你不必追最新，选一个 LTS 附近的版本即可。版本太高有时会遇到 Node API 变动，版本太低又可能不兼容新版 Windows 的某些显示缩放行为。

接下来建三个核心文件：main.js、index.html、package.json的 build 字段。目录结构如下：

web-to-exe/ ├── main.js ├── index.html ├── package.json └── build/ └── icon.ico

index.html就是你的网页，可以是一个单文件，也可以是一个带 assets 的目录。如果是目录，把入口 HTML 放在根下，其他资源用相对路径引用即可。

2.3 main.js 的最小可用写法与参数说明

main.js 是 Electron 的主进程入口，控制窗口行为。下面是我常用的最小配置，逐行说明：

const { app, BrowserWindow, globalShortcut } = require('electron'); const path = require('path'); let mainWindow; function createWindow() { mainWindow = new BrowserWindow({ width: 1920, height: 1080, fullscreen: true, // 启动即全屏 frame: false, // 去掉窗口边框和标题栏 autoHideMenuBar: true, // 隐藏菜单栏 icon: path.join(__dirname, 'build/icon.ico'), // 任务栏图标 webPreferences: { nodeIntegration: false, // 安全起见，页面里不暴露 Node contextIsolation: true } }); mainWindow.loadFile('index.html'); // 注册 Esc 退出 globalShortcut.register('Escape', () => { app.quit(); }); // 窗口关闭时注销快捷键，避免残留 mainWindow.on('closed', () => { globalShortcut.unregisterAll(); mainWindow = null; }); } app.whenReady().then(createWindow); app.on('window-all-closed', () => { app.quit(); });

几个关键点：fullscreen: true让窗口直接全屏，但此时任务栏可能还会在鼠标移到屏幕边缘时弹出。要彻底遮住任务栏，还需要配合frame: false和setAlwaysOnTop，下一章细说。globalShortcut.register('Escape')是全局快捷键，即使焦点不在窗口内也能触发退出。icon参数在开发模式下可能不生效，打包后才会正确显示，这是 Electron 的已知行为，不用纠结。

2.4 开发模式验证与常见启动报错

写完 main.js 后，在 package.json 的 scripts 里加一行：

"scripts": { "start": "electron ." }

然后npm start。如果窗口正常弹出并加载了 index.html，说明基础链路通了。常见报错有两个：一是Cannot find module 'electron'，通常是 npm install 没装完或者 node_modules 被误删；二是页面白屏，多半是loadFile的路径写错，或者 index.html 里有语法错误导致渲染进程崩溃。白屏时按Ctrl+Shift+I打开开发者工具看 Console，比盲猜快得多。

3. 全屏与任务栏遮挡：窗口参数、置顶策略和分辨率适配

3.1 fullscreen 和 kiosk 模式的区别

Electron 的 BrowserWindow 支持fullscreen: true和kiosk: true两种模式。fullscreen 是全屏但保留退出全屏的能力，kiosk 是更严格的锁定模式，用户无法通过常规快捷键退出。我一开始用 kiosk，结果发现某些 Windows 版本下任务栏仍然会在特定操作后闪现，而且调试时想切出来很麻烦。后来改用 fullscreen + frame:false + setAlwaysOnTop 的组合，实测在 Win10 和 Win11 上都能稳定遮住任务栏。

具体做法是在 createWindow 里加两行：

mainWindow.setAlwaysOnTop(true, 'screen-saver'); mainWindow.setFullScreen(true);

setAlwaysOnTop的第二个参数'screen-saver'是置顶层级，比普通置顶更高，能盖住任务栏。但注意，这个层级在某些安全软件环境下可能被拦截，如果发现任务栏还是弹出来，先检查是否有安全软件在干预窗口层级。

3.2 多显示器与分辨率适配的坑

如果目标机器接了多个显示器，fullscreen: true默认在主显示器全屏。如果希望指定显示器，需要在创建窗口前获取screen模块的 displays 信息，然后设置窗口的x、y坐标。常见做法是：

const { screen } = require('electron'); const displays = screen.getAllDisplays(); const targetDisplay = displays[1] || displays[0]; // 选第二个显示器，没有就用主屏 mainWindow = new BrowserWindow({ x: targetDisplay.bounds.x, y: targetDisplay.bounds.y, width: targetDisplay.bounds.width, height: targetDisplay.bounds.height, fullscreen: true, frame: false });

分辨率适配方面，如果网页本身是固定宽度布局，在全屏后可能出现左右留白或内容被拉伸。建议在 HTML 的 head 里加<meta name="viewport" content="width=device-width, initial-scale=1.0">，并且用 CSS 的vh、vw单位替代固定像素。如果页面是给特定分辨率设计的，可以在 main.js 里根据targetDisplay.bounds动态调整zoomFactor，但这是最后手段，优先改页面样式。

3.3 防止用户通过 Alt+F4 或 Win 键退出

Esc 退出是我们主动绑定的，但用户可能按 Alt+F4 或者 Win 键。Alt+F4 会触发窗口的 close 事件，可以在 mainWindow 上监听close并阻止默认行为：

mainWindow.on('close', (e) => { e.preventDefault(); // 可以选择在这里什么都不做，或者弹确认框 });

但这样会导致 app.quit() 也无法关闭窗口，所以需要加一个标志位，在 Esc 触发时先设标志再退出。Win 键是系统级的，Electron 层面无法完全屏蔽，只能通过 kiosk 模式部分限制。如果场景要求严格禁止 Win 键，需要配合系统组策略或第三方工具，这超出了 Electron 的能力范围，选型时要心里有数。

3.4 任务栏遮挡的验证方法

改完参数后怎么确认任务栏真的被遮住了？我的做法是把鼠标移到屏幕最下方，停留几秒，看任务栏是否弹出。如果弹出，检查setAlwaysOnTop是否在窗口 ready 之后调用，以及是否有其他窗口抢了置顶层级。另一个验证点是按 Win+D 显示桌面，看我们的窗口是否还在最前面。如果不在，说明置顶层级不够，可以尝试'screen-saver'换成'pop-up-menu'或'status'，不同 Windows 版本表现略有差异，需要实测。

4. 图标与文件名定制：从默认 electron 图标到自定义 exe

4.1 图标文件的格式要求与制作

Electron 打包 Windows exe 时，图标必须是 .ico 格式，且建议包含多个尺寸（16x16、32x32、48x48、256x256）。如果只放一个尺寸，在某些系统缩放比例下会显示模糊。我一般用在线工具或 ImageMagick 把 PNG 转成多尺寸 ico：

magick convert icon.png -define icon:auto-resize=256,128,64,48,32,16 icon.ico

如果没有 ImageMagick，也可以用 Python 的 Pillow：

from PIL import Image img = Image.open('icon.png') img.save('icon.ico', sizes=[(256, 256), (128, 128), (64, 64), (48, 48), (32, 32), (16, 16)])

生成的 icon.ico 放到 build 目录下，main.js 里的icon路径指向它。

4.2 electron-builder 配置：productName 与 artifactName

package.json 里加 build 字段：

"build": { "appId": "com.example.webtoexe", "productName": "MyTool", "directories": { "output": "dist" }, "win": { "target": "portable", "icon": "build/icon.ico" }, "portable": { "artifactName": "MyTool.exe" } }

productName决定 exe 在系统中显示的名称，artifactName决定输出文件名。如果 target 是portable，生成的是一个单文件 exe，双击即用，不需要安装。如果 target 是nsis，会生成安装包，安装后 exe 在安装目录里。对于内部工具分发，portable 更省事。

注意appId虽然看起来不重要，但 Windows 会用它来区分任务栏图标分组，建议写成反向域名格式，避免和别的应用冲突。

4.3 打包命令与输出验证

在 package.json 的 scripts 里加：

"dist": "electron-builder --win portable"

然后npm run dist。打包完成后，dist 目录下会出现MyTool.exe。双击运行，检查三件事：图标是否替换成功、窗口是否全屏且遮住任务栏、Esc 是否能退出。如果图标没变，清理一下%APPDATA%下对应的缓存目录再试，Windows 图标缓存有时会延迟更新。

4.4 文件名的动态修改与版本管理

如果每次发版都要改文件名，手动改 artifactName 很烦。可以在打包前用脚本读取 package.json 的 version 字段，动态生成 artifactName：

// build-script.js const fs = require('fs'); const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8')); const buildConfig = pkg.build; buildConfig.portable.artifactName = `MyTool_v${pkg.version}.exe`; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));

然后在 dist 脚本前执行这个脚本。这样每次改 version 就能自动生成带版本号的文件名，避免新旧版本混淆。

5. 避坑与排查：打包过程中最容易翻车的五个点

5.1 打包后白屏，开发模式正常

现象：npm start一切正常，npm run dist后双击 exe 白屏。原因：打包后文件路径变了，loadFile('index.html')的相对路径基准是 exe 所在目录，而不是项目根目录。解决：用path.join(__dirname, 'index.html')或者app.getAppPath()拼接绝对路径。如果 index.html 在 asar 包里，确认 electron-builder 没有把它排除掉。

5.2 Esc 退出失效，按了没反应

现象：开发模式 Esc 能退出，打包后按 Esc 没反应。原因：globalShortcut 在某些 Windows 环境下被其他应用占用，或者窗口失焦后快捷键未注册成功。解决：在app.whenReady()之后、窗口创建之前注册快捷键，并且加一个globalShortcut.isRegistered('Escape')的判断。如果仍然失效，改用mainWindow.webContents.on('before-input-event')监听键盘事件，在渲染进程层面捕获 Esc。

5.3 任务栏遮挡不彻底，鼠标下移就弹出

现象：全屏后任务栏隐藏，但鼠标移到屏幕底部时任务栏滑出。原因：setAlwaysOnTop的层级不够，或者窗口没有真正覆盖任务栏区域。解决：确认frame: false和fullscreen: true同时生效，尝试把置顶层级改为'screen-saver'。如果还不行，在窗口 ready-to-show 事件里再次调用setAlwaysOnTop，因为某些 Windows 版本在窗口显示后会重置层级。

5.4 图标替换后任务栏显示默认 Electron 图标

现象：exe 文件图标变了，但任务栏和窗口左上角还是 Electron 默认图标。原因：main.js 里的icon参数在打包后路径不对，或者 .ico 文件缺少小尺寸图层。解决：确保icon路径用path.join(__dirname, 'build/icon.ico')，并且 ico 文件包含 16x16 和 32x32 尺寸。如果仍然不显示，检查 electron-builder 的 win.icon 配置是否指向同一个文件。

5.5 打包体积过大，超过 200MB

现象：一个简单的 HTML 页面，打包后 exe 有 200MB 以上。原因：Electron 本身包含 Chromium 和 Node.js，基础体积就在 150MB 左右。解决：如果对体积敏感，可以在 electron-builder 里配置asar: true压缩资源，排除不必要的 locales 文件（只保留 zh-CN 和 en-US），以及用files字段只打包必要文件。但要注意，体积压缩有上限，Electron 的底线就在那里，如果要求 50MB 以内，这个方案本身就不适合，需要换 Tauri 或 WebView2。

6. 进阶技巧：用 before-input-event 替代 globalShortcut 做退出控制

globalShortcut 有一个硬伤：它是系统级的，注册后即使窗口最小化也能触发。对于“Esc 退出”这个需求，其实更合理的做法是在窗口获得焦点时监听键盘事件，失焦时不响应。Electron 的before-input-event正好满足这个场景。

具体写法是在 main.js 里：

mainWindow.webContents.on('before-input-event', (event, input) => { if (input.key === 'Escape' && input.type === 'keyDown') { event.preventDefault(); app.quit(); } });

这段代码的好处是：只在窗口聚焦时生效，不会干扰其他应用；不需要注册全局快捷键，避免被安全软件拦截；而且可以精确控制按键组合，比如只响应单独的 Esc，不响应 Ctrl+Esc。

对比两种方案：

我现在的习惯是：如果目标机器上可能运行其他需要 Esc 的软件，优先用 before-input-event；如果确定是独占设备，globalShortcut 更省心。另外，before-input-event 还可以用来屏蔽其他按键，比如禁止 F12 打开开发者工具、禁止 Ctrl+R 刷新页面，对于交付给非技术用户的场景很实用。

还有一个细节：如果页面里有输入框，用户按 Esc 可能是想取消输入，这时候直接退出会显得很突兀。可以在渲染进程里监听 Esc，如果焦点在输入框内就只清空输入，否则再通知主进程退出。这需要在 preload 脚本里做进程间通信，复杂度高一些，但体验更好。

从那以后我每次打包前都会在目标机器上实际跑一遍 Esc 退出、任务栏遮挡和图标显示，确认无误再分发。希望帮到你。

本文还有配套的精品资源，点击获取