1. 从 Cocos Creator 到 Windows 桌面程序:整体思路拆解
把 Cocos Creator 做的游戏或互动应用打包成一个能在 Windows 上双击就跑的 exe,再进一步做成带安装向导的安装包,这件事听起来像是“发布流程里顺手点两下”的小事,但真做过的人都知道,中间踩的坑足够写满一页纸。我自己第一次做这个流程的时候,卡在“构建出来的东西到底是个啥”这个问题上整整一个下午——Cocos Creator 构建出来的 Windows 产物,本质上是一个基于 Electron 的壳工程,它把游戏资源、引擎运行时和一份 Electron 主进程代码揉在一起,最后交给构建工具去编译成 exe。理解这一点非常关键,因为后面所有的定制、排错、打包安装包,都建立在这个认知之上。
这套流程解决的核心问题是:让一个原本只能在编辑器或者浏览器里跑的项目,变成一个可以脱离开发环境、分发给普通用户的独立桌面程序。适合谁来参考?如果你是用 Cocos Creator 做小游戏、互动课件、展示类应用、工具类软件的开发者,尤其是需要把成品交付给不懂技术的客户或者上架到某些只认 exe 的渠道,那这套东西就是刚需。哪怕你之前完全没碰过 Electron 和 NSIS,只要跟着把每一步的“为什么”搞清楚,也能自己走通。
我先把整体链路捋一遍,让你心里有个地图。Cocos Creator 的构建面板里选择 Windows 平台,构建完成后会在build目录下生成一个windows文件夹,里面包含jsb-link或者jsb-default之类的子目录,以及一个packages目录。真正干活的是packages里的那个 Electron 工程,它有自己的package.json、main.js和一堆配置文件。你要做的第一件事,是用 npm 或者 yarn 把这个 Electron 工程的依赖装好,然后用 electron-builder 或者 electron-packager 把它编译成 exe。编译出来的产物通常是一个文件夹,里面有 exe、dll、资源文件等。第二步才是用 NSIS 或者 Inno Setup 这类安装包制作工具,把这个文件夹打包成一个带安装向导的 setup.exe。
为什么是 Electron 而不是别的方案?因为 Cocos Creator 从 2.x 后期到 3.x,Windows 原生构建走的就是 Electron 路线。Electron 的好处是跨平台一致性好,你的游戏逻辑用 JavaScript/TypeScript 写,渲染用 WebGL,Electron 提供一个 Chromium 内核和 Node.js 运行时,天然就能跑。坏处是包体大、启动稍慢、内存占用高,但对于大多数中小型项目来说,这些代价可以接受。如果你追求极致轻量,理论上可以用 Cocos 的原生 C++ 构建,但那条路配置复杂、坑更多,而且和热更新、JS 逻辑的衔接没那么顺。所以除非有硬性要求,Electron 路线是性价比最高的选择。
再说安装包工具的选择。NSIS 是老牌选手,体积小、脚本灵活、社区资料多,缺点是脚本语法有点反人类,写起来像在写汇编。Inno Setup 的脚本更接近 Pascal,可读性好一些,但自定义程度略低。我个人的习惯是:如果安装包逻辑简单,就是复制文件、创建快捷方式、写注册表,那 NSIS 足够;如果需要复杂的安装条件判断、多语言、自定义界面,Inno Setup 可能更省心。本文以 NSIS 为主线,因为它在 Cocos 社区里的使用率更高,遇到问题也更容易搜到答案。
还有一个容易被忽略的点:构建目标架构。Cocos Creator 构建 Windows 时,默认可能是 x64,也可能是 ia32(32 位)。如果你的用户群体里有老机器,或者某些工业控制场景还在用 32 位系统,那就得选 ia32。但要注意,Electron 从某个版本开始不再支持 32 位 Windows,所以你得确认你用的 Electron 版本和 Cocos Creator 版本是否还兼容 ia32。这个细节后面会展开讲。
2. 构建前的环境准备与关键配置
2.1 开发环境清单与版本匹配
在动手之前,先把环境理清楚。我见过太多人因为 Node.js 版本不对、Python 版本冲突、Visual Studio 组件缺失,导致构建到一半报一堆看不懂的错。下面这张表是我实测下来比较稳的组合,你可以直接抄作业。
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| Cocos Creator | 3.8.x LTS | 3.8 系列对 Electron 构建的支持比较成熟,社区资料多 |
| Node.js | 16.x 或 18.x | 不要用太新的 20+,某些 Electron 版本会有兼容问题 |
| Python | 2.7 或 3.x | 如果用到 node-gyp 编译原生模块,Python 是必须的 |
| Visual Studio | 2019 或 2022 | 安装时勾选“使用 C++ 的桌面开发”和 Windows SDK |
| Git | 最新版 | 某些 npm 包会从 git 仓库拉取依赖 |
| NSIS | 3.x | 安装时记得勾选插件和脚本编辑器 |
这里重点说几个坑。第一,Node.js 版本不是越新越好。Cocos Creator 构建出来的 Electron 工程,其package.json里锁定的 Electron 版本可能是 13、16 或者 22,不同版本对 Node.js 的要求不一样。如果你用 Node 20 去装依赖,可能会遇到node-gyp编译失败,报错信息里一堆gyp ERR。解决办法是用 nvm-windows 切换 Node 版本,或者直接在项目里用.nvmrc锁定。
第二,Visual Studio 的安装不能偷懒。很多人只装了 VS Code,以为就够了,但 Electron 在 Windows 上编译某些原生模块时,需要 MSBuild 和 Windows SDK。如果你看到MSB3428或者MSB4019之类的错误,八成是 VS 组件没装全。最稳妥的做法是打开 Visual Studio Installer,确认“使用 C++ 的桌面开发”这个工作负载已经勾选,右侧的“MSVC v142 - VS 2019 C++ x64/x86 生成工具”和“Windows 10 SDK”也要装上。
第三,Python 环境。如果你的项目里没有原生模块,Python 可能用不上。但一旦涉及到node-gyp,它就会去找 Python。Windows 上建议装 Python 2.7 和 Python 3.x 两个版本,然后用npm config set python指定路径。不过现在很多新版本的 node-gyp 已经支持 Python 3 了,所以优先用 Python 3,实在不行再退回 2.7。
2.2 Cocos Creator 构建面板的参数怎么填
打开 Cocos Creator,点“项目”->“构建发布”,选择“Windows”平台。这里有几个参数需要你特别留意。
构建选项里的“设备方向”一般选“横屏”或“竖屏”,看你的游戏类型。“渲染后端”通常选 WebGL,如果你的项目对性能要求极高,可以试试 WebGL2,但兼容性要自己测。“加密脚本”和“压缩纹理”这些按需勾选,注意加密脚本可能会影响热更新。
资源服务器地址这一栏,如果你打算把资源放在本地,就留空或者填相对路径。如果要做热更新,这里要填你的 CDN 地址。但注意,填了远程地址后,构建出来的程序启动时会先去远程拉资源,如果网络不通,游戏就卡在加载界面。所以本地测试时最好留空。
构建路径默认是build,你可以改成别的。构建完成后,去build/windows目录下看,会有一个以项目名命名的文件夹,里面就是 Electron 工程。
这里有个细节:Cocos Creator 3.x 构建出来的 Electron 工程,其package.json里的main字段指向main.js,而main.js里会加载index.html。这个index.html就是游戏的入口。如果你打开main.js看,会发现它创建了一个BrowserWindow,设置了宽高、是否全屏、是否显示菜单栏等。这些参数你都可以改,比如去掉默认菜单栏、设置窗口图标、禁止用户调整窗口大小等。
2.3 构建产物的目录结构解读
构建完成后,别急着去编译 exe,先花五分钟把目录结构看清楚。以 Cocos Creator 3.8 为例,build/windows下的结构大致是这样的:
build/ windows/ jsb-link/ # 或者 jsb-default,取决于构建配置 assets/ # 游戏资源 src/ # 引擎和项目脚本 ... packages/ YourProject/ # Electron 工程根目录 package.json main.js index.html ...jsb-link和jsb-default的区别在于链接方式,一般不用管。重点是packages/YourProject这个目录,它才是 Electron 工程的所在地。你后续所有的 npm 操作、electron-builder 配置、NSIS 脚本,都是围绕这个目录展开的。
打开package.json,你会看到类似这样的内容:
{ "name": "your-project", "version": "1.0.0", "main": "main.js", "scripts": { "start": "electron ." }, "devDependencies": { "electron": "^13.1.7" } }注意electron的版本。这个版本是 Cocos Creator 构建时写死的,你最好不要随意升级,因为升级后可能会和引擎的某些接口不兼容。如果你确实需要升级,先在本地跑npm start测试,确认游戏能正常启动再继续。
3. 从 Electron 工程到 exe 的完整实操
3.1 安装依赖与本地调试
进入packages/YourProject目录,打开命令行,执行:
npm install如果网络慢,可以换成淘宝镜像:
npm install --registry=https://registry.npmmirror.com装完之后,执行:
npm start这时候 Electron 会启动,你应该能看到游戏窗口。如果窗口一片空白,或者报错Failed to load index.html,那说明路径有问题。检查main.js里加载index.html的路径是否正确,通常是path.join(__dirname, 'index.html')。如果index.html不在根目录,而在某个子目录里,就要相应调整。
本地调试这一步非常重要,因为如果你直接去编译 exe,出了问题很难排查。在 Electron 里跑通了,说明资源加载、脚本执行、渲染都没问题,剩下的就是打包的事。
提示:如果你在
npm start时遇到Electron failed to install correctly,多半是 Electron 的二进制文件没下载下来。解决办法是设置环境变量ELECTRON_MIRROR指向国内镜像,然后删掉node_modules/electron重新npm install。
3.2 用 electron-builder 编译 exe
Electron 工程编译成 exe,有两种主流工具:electron-packager 和 electron-builder。前者简单粗暴,后者功能强大但配置稍复杂。我推荐用 electron-builder,因为它能直接生成 NSIS 安装包,省去后面单独写 NSIS 脚本的麻烦。
先安装:
npm install electron-builder --save-dev然后在package.json里添加build字段:
{ "build": { "appId": "com.yourcompany.yourproject", "productName": "YourProject", "directories": { "output": "dist" }, "win": { "target": [ { "target": "nsis", "arch": ["x64"] } ], "icon": "build/icon.ico" }, "nsis": { "oneClick": false, "allowToChangeInstallationDirectory": true, "createDesktopShortcut": true, "createStartMenuShortcut": true, "shortcutName": "YourProject" } } }这里解释几个关键参数。appId是应用的唯一标识,一般用反向域名。productName是显示给用户的名字。directories.output是输出目录,默认是dist。win.target指定目标格式,nsis表示生成安装包,arch指定架构,x64是 64 位,ia32是 32 位。icon是应用图标,必须是.ico格式,尺寸建议包含 256x256。
nsis字段里的配置决定了安装向导的行为。oneClick设为false表示显示安装向导,而不是一键安装。allowToChangeInstallationDirectory允许用户选择安装路径。createDesktopShortcut和createStartMenuShortcut分别创建桌面和开始菜单快捷方式。
配置好后,执行:
npx electron-builder --win如果一切顺利,dist目录下会出现一个YourProject Setup 1.0.0.exe,这就是安装包。双击它,会弹出安装向导,选路径、点下一步、完成,桌面上就会出现快捷方式。
但实际操作中,这一步很容易报错。最常见的错误是Error: Cannot find module 'xxx',说明某个依赖没装。还有Application entry file "main.js" does not exist,说明package.json里的main字段指向的文件不在根目录。另外,如果icon.ico的尺寸不对,electron-builder 会报icon size must be at least 256x256。
注意:electron-builder 默认会去 GitHub 下载一些辅助工具,比如
nsis、winCodeSign。如果网络不通,会卡在downloading阶段。解决办法是设置环境变量ELECTRON_BUILDER_BINARIES_MIRROR指向国内镜像,或者手动下载后放到缓存目录。
3.3 不用 electron-builder,手动用 NSIS 打包
有些团队出于定制化需求,不想用 electron-builder 自带的 NSIS 配置,而是自己写 NSIS 脚本。这时候流程是这样的:先用 electron-packager 或者 electron-builder 的dir模式生成一个免安装的文件夹,然后用 NSIS 把这个文件夹打包成安装包。
先生成免安装文件夹:
npx electron-builder --win --dir这会在dist/win-unpacked下生成一个文件夹,里面有 exe 和所有依赖。然后写一个 NSIS 脚本,比如installer.nsi:
!define APP_NAME "YourProject" !define APP_VERSION "1.0.0" !define APP_PUBLISHER "YourCompany" !define APP_EXE "YourProject.exe" Name "${APP_NAME}" OutFile "YourProject_Setup.exe" InstallDir "$PROGRAMFILES64\${APP_NAME}" RequestExecutionLevel admin Page directory Page instfiles Section "Install" SetOutPath "$INSTDIR" File /r "dist\win-unpacked\*.*" CreateShortCut "$DESKTOP\${APP_NAME}.lnk" "$INSTDIR\${APP_EXE}" CreateDirectory "$SMPROGRAMS\${APP_NAME}" CreateShortCut "$SMPROGRAMS\${APP_NAME}\${APP_NAME}.lnk" "$INSTDIR\${APP_EXE}" WriteUninstaller "$INSTDIR\uninstall.exe" SectionEnd Section "Uninstall" Delete "$DESKTOP\${APP_NAME}.lnk" Delete "$SMPROGRAMS\${APP_NAME}\${APP_NAME}.lnk" RMDir "$SMPROGRAMS\${APP_NAME}" RMDir /r "$INSTDIR" SectionEnd这个脚本做了几件事:定义应用名称、版本、发布者;设置安装目录为Program Files下的应用名;请求管理员权限;显示目录选择页和安装进度页;安装时复制所有文件、创建桌面和开始菜单快捷方式、写入卸载程序;卸载时删除快捷方式和安装目录。
用 NSIS 编译这个脚本,可以用命令行:
makensis installer.nsi也可以打开 NSIS 的脚本编辑器,加载脚本后点“编译”。编译完成后,会生成YourProject_Setup.exe。
手动写 NSIS 脚本的好处是灵活,你可以加自定义页面、检查系统版本、写注册表、安装 VC++ 运行库等。坏处是语法繁琐,容易出错。比如File /r后面的路径如果包含空格,必须用引号包起来。再比如RequestExecutionLevel admin如果写成highest,在某些系统上会不弹 UAC 提示,导致安装失败。
3.4 安装包体积优化与启动速度调优
Electron 应用的安装包体积通常比较大,因为 Chromium 内核本身就占几十兆。如果你的游戏资源又多,安装包上百兆很正常。但我们可以做一些优化。
第一,压缩资源。Cocos Creator 构建时已经对图片做了压缩,但你可以进一步用工具压缩 PNG、JPG。对于音频,可以转成更高效的格式,比如把 WAV 转成 MP3 或 OGG。
第二,剔除不必要的 Electron 文件。win-unpacked目录里有一些LICENSE、version之类的文件,可以删掉。locales目录里如果只保留en-US和zh-CN,能省几兆。
第三,用asar打包。electron-builder 默认会把resources/app打包成app.asar,这能减少文件数量、加快加载速度。但注意,如果你的游戏需要动态读取某些文件,asar里的文件不能直接通过文件系统路径访问,得用 Electron 的asar模块或者把那些文件放到asar外面。
启动速度方面,Electron 本身启动就慢,这是硬伤。能做的优化包括:减少主进程的初始化工作、延迟加载非关键模块、用show: false创建窗口然后等ready-to-show事件再显示。另外,如果你的游戏资源很大,可以考虑把资源加载做成异步的,先显示一个加载界面,再慢慢加载。
4. 常见问题与排查技巧实录
4.1 构建阶段的高频报错与解决
我在不同项目里遇到过各种各样的报错,下面整理成一张速查表,方便你对照排查。
| 报错信息 | 可能原因 | 解决办法 |
|---|---|---|
Error: Cannot find module 'electron' | 依赖没装 | 在 Electron 工程目录执行npm install |
Application entry file "main.js" does not exist | package.json的main字段路径不对 | 检查main字段,确保指向存在的文件 |
icon size must be at least 256x256 | 图标尺寸不够 | 用工具把 ico 文件做成包含 256x256 的 |
downloading ... failed | 网络问题 | 设置镜像环境变量,或手动下载放到缓存 |
MSB3428: Could not load Visual C++ component | VS 组件缺失 | 安装“使用 C++ 的桌面开发”工作负载 |
gyp ERR! stack Error: Python executable not found | Python 没装或路径不对 | 安装 Python 并配置npm config set python |
Error: ENOSPC: no space left on device | 磁盘空间不足 | 清理磁盘,或把构建目录换到空间大的盘 |
Cannot create symbolic link | 权限不足 | 以管理员身份运行命令行 |
这张表里的每一行,我几乎都亲自踩过。特别是MSB3428,当时折腾了很久,最后发现是 VS 安装时只勾了“通用 Windows 平台开发”,没勾“使用 C++ 的桌面开发”。所以如果你在编译原生模块时遇到 MSB 开头的错误,第一反应就是去检查 VS 组件。
4.2 安装包运行时的典型故障
安装包做出来之后,用户那边可能遇到各种问题。最常见的是“双击没反应”或者“闪退”。这时候你需要让用户提供日志,或者自己在本机模拟用户环境测试。
闪退问题:Electron 应用闪退,通常是因为主进程抛了未捕获的异常。你可以在main.js里加一个全局异常捕获:
process.on('uncaughtException', (error) => { console.error('Uncaught Exception:', error); // 可以写日志到文件 });然后把日志输出到用户目录下的某个文件,方便排查。
白屏问题:窗口打开了,但一片白。这多半是index.html加载失败,或者资源路径不对。检查main.js里loadFile或loadURL的路径。如果是loadFile,路径是相对于main.js的;如果是loadURL,要确保 URL 正确。
缺少 DLL 问题:在某些精简版 Windows 系统上,可能会提示缺少api-ms-win-crt-runtime-l1-1-0.dll之类的。这是因为系统没装 VC++ 运行库。解决办法是在 NSIS 脚本里检测并安装 VC++ Redistributable,或者让用户自己装。
杀毒软件误报:Electron 打包出来的 exe,有时候会被某些杀毒软件误报为病毒。这是因为 Electron 的二进制文件特征被误判。解决办法是给 exe 做代码签名,或者把安装包提交给杀毒厂商白名单。代码签名需要买证书,成本较高,小团队可以先不做,但要在安装说明里提醒用户添加信任。
4.3 独家避坑经验与实操心得
说几个文档里不会写、但实际项目中非常关键的点。
第一,构建路径不要有中文和空格。Cocos Creator 的构建路径、Electron 工程路径、NSIS 脚本路径,全都不要包含中文或空格。我遇到过因为路径里有空格,导致node-gyp编译失败的情况。虽然理论上加引号能解决,但有些工具内部处理不好,所以最省事的办法就是全用英文路径。
第二,版本锁定。Cocos Creator 构建出来的 Electron 工程,其package.json里的依赖版本是写死的。你npm install之后,package-lock.json会锁定具体版本。千万不要随意删掉package-lock.json或者升级依赖,否则可能引入不兼容的更新。如果非要升级,先在分支上测试。
第三,测试环境要干净。你本机可能装了各种运行库、SDK,所以你的 exe 跑得好好的,不代表用户的机器上也能跑。最好找一台刚装好系统的虚拟机,或者用 Windows Sandbox,测试安装包能否正常安装和运行。这样才能发现缺少运行库、权限不足等问题。
第四,安装包的数字签名。如果你的应用要分发给大量用户,尤其是企业用户,代码签名几乎是必须的。没有签名的 exe,Windows SmartScreen 会弹警告,用户看到“Windows 已保护你的电脑”就会慌。签名证书可以买,也可以用开源的签名工具做自签名,但自签名证书需要用户手动导入信任,体验不好。所以如果预算允许,尽早买证书。
第五,热更新与安装包的关系。如果你的游戏需要热更新,那安装包里只需要放一个基础版本,后续资源通过远程下载。但要注意,Electron 的主进程代码(main.js)是打包在app.asar里的,热更新一般只能更新游戏资源,不能更新主进程代码。如果你需要更新主进程逻辑,就得发新安装包。这一点在设计热更新方案时要考虑清楚。
第六,多语言支持。如果你的应用要面向不同语言的用户,NSIS 脚本里可以加多语言配置。Electron 的locales目录也可以只保留需要的语言,减小体积。但注意,删掉某些语言文件后,如果系统语言不在保留列表里,Electron 可能会回退到默认语言,这个要测试。
5. 进阶玩法:自定义安装界面与自动化构建
5.1 用 NSIS 插件定制安装向导
NSIS 自带的标准界面比较朴素,如果你想让安装向导看起来更专业,可以用nsDialogs插件自定义页面。比如加一个“选择安装类型”的页面,让用户选“完整安装”还是“自定义安装”。或者加一个“许可协议”页面,显示用户协议。
下面是一个用nsDialogs创建自定义页面的简单示例:
!include nsDialogs.nsh !include LogicLib.nsh Var Dialog Var Label Var Checkbox Var CheckState Page custom nsDialogsPage nsDialogsPageLeave Function nsDialogsPage nsDialogs::Create 1018 Pop $Dialog ${If} $Dialog == error Abort ${EndIf} ${NSD_CreateLabel} 0 0 100% 12u "请选择安装选项:" Pop $Label ${NSD_CreateCheckbox} 0 20u 100% 12u "创建桌面快捷方式" Pop $Checkbox ${NSD_SetState} $Checkbox ${BST_CHECKED} nsDialogs::Show FunctionEnd Function nsDialogsPageLeave ${NSD_GetState} $Checkbox $CheckState FunctionEnd这个脚本创建了一个页面,上面有一个标签和一个复选框。用户勾选后,$CheckState会保存状态,你可以在安装 Section 里根据这个状态决定是否创建桌面快捷方式。
nsDialogs的功能很强大,可以创建文本框、下拉框、进度条等。但它的语法也比较繁琐,需要花点时间熟悉。如果你只是想做简单的定制,用MUI2(Modern UI 2)可能更省事,它提供了一套现成的页面模板,改改文字和图片就行。
5.2 用脚本实现一键构建
如果你经常需要出包,手动点构建、等编译、再打包安装包,效率太低。可以写一个批处理或者 Node.js 脚本,把整个流程串起来。
比如写一个build.bat:
@echo off echo 正在构建 Cocos Creator 项目... "C:\Program Files\CocosCreator\CocosCreator.exe" --project "D:\MyProject" --build "platform=windows" echo 正在安装 Electron 依赖... cd /d "D:\MyProject\build\windows\packages\MyProject" call npm install echo 正在编译 exe 和安装包... call npx electron-builder --win echo 构建完成,安装包在 dist 目录下。 pause这个脚本假设 Cocos Creator 安装在默认路径,项目在D:\MyProject。实际使用时,路径要改成你自己的。Cocos Creator 的命令行构建参数可以参考官方文档,不同版本的参数可能略有不同。
如果你用 CI/CD,比如 Jenkins、GitLab CI,可以把这些步骤写成流水线脚本。注意 CI 环境里通常没有图形界面,Cocos Creator 的命令行构建需要额外配置,比如用--headless模式。这个配置起来比较麻烦,但一旦跑通,出包效率会大幅提升。
5.3 安装包自动更新方案
Electron 应用有一个很实用的功能:自动更新。你可以用electron-updater这个库,配合 electron-builder 生成的latest.yml文件,实现应用启动时检查更新、下载、安装。
基本流程是:electron-builder 打包时会生成一个latest.yml,里面包含版本号和安装包路径。你把这个文件和安装包一起上传到服务器。应用启动时,electron-updater会去请求这个latest.yml,对比版本号,如果有新版本就下载,然后提示用户重启安装。
配置方法是在main.js里:
const { autoUpdater } = require('electron-updater'); autoUpdater.checkForUpdatesAndNotify();然后在package.json的build字段里配置publish:
{ "publish": { "provider": "generic", "url": "https://your-server.com/updates/" } }这样打包时就会生成latest.yml。注意,自动更新需要代码签名,否则在某些系统上会失败。另外,更新服务器的 URL 必须是 HTTPS,否则 Electron 会拒绝下载。
自动更新对于游戏类应用特别有用,因为你可以只更新资源,不用让用户重新下载整个安装包。但要注意,electron-updater更新的是整个应用,包括 Electron 本身。如果你只想更新游戏资源,那应该用 Cocos 自带的热更新机制,而不是electron-updater。两者可以结合使用:electron-updater负责更新主程序,Cocos 热更新负责更新游戏资源。
6. 从 exe 到安装包:完整交付清单与检查项
6.1 交付前的自检清单
在把安装包发给用户之前,我通常会过一遍这个清单,确保没有遗漏。
- [ ] 安装包能在干净的 Windows 10/11 上正常安装
- [ ] 安装后桌面和开始菜单有快捷方式
- [ ] 双击快捷方式能启动应用,不闪退、不白屏
- [ ] 应用图标显示正确,不是默认的 Electron 图标
- [ ] 卸载程序能正常卸载,不留残留文件
- [ ] 安装包体积在可接受范围内
- [ ] 没有杀毒软件误报(至少在主流杀软上测过)
- [ ] 如果做了代码签名,签名有效
- [ ] 版本号正确,和
package.json里一致 - [ ] 如果支持自动更新,更新服务器配置正确
这个清单看起来简单,但每一条都可能出问题。比如“卸载不留残留”,NSIS 默认的卸载脚本可能不会删除用户数据目录,你需要手动加删除逻辑。再比如“杀毒误报”,这个很难完全避免,只能尽量做签名和提交白名单。
6.2 用户反馈的收集与处理
安装包发出去之后,用户的反馈就是最好的测试用例。我一般会在应用里加一个“反馈”按钮,或者至少留一个日志文件路径,让用户能把日志发给我。
日志文件可以放在app.getPath('userData')目录下,这个目录在 Windows 上通常是C:\Users\用户名\AppData\Roaming\YourProject。你可以在main.js里用fs模块写日志:
const log = require('electron-log'); log.transports.file.resolvePath = () => path.join(app.getPath('userData'), 'logs/main.log'); log.info('App started');electron-log是一个很好用的日志库,支持文件和控制台输出,还能自动处理路径。用户遇到问题时,让他把main.log发过来,你就能看到详细的错误信息。
如果用户反馈“安装失败”,先问他几个问题:系统版本是什么?安装时有没有报错?报错信息是什么?有没有装杀毒软件?这些信息能帮你快速定位问题。我遇到过用户因为系统盘空间不足导致安装失败,也遇到过因为杀毒软件拦截导致安装程序被删除。所以收集反馈时,信息越详细越好。
6.3 后续扩展方向
这套流程跑通之后,你可以进一步扩展。比如把构建流程自动化,每次提交代码后自动出包;比如加一个启动器,在游戏启动前检查更新、修复资源;比如把安装包做成绿色版,解压即用,不用安装。
绿色版的做法很简单:不用 NSIS 打包,直接把win-unpacked文件夹压缩成 zip,用户解压后双击 exe 就能跑。缺点是没法创建快捷方式、没法写注册表、没法做卸载。但对于一些便携场景,绿色版反而更受欢迎。
另一个扩展方向是多平台。Electron 的好处是跨平台,同样的代码可以打包成 macOS 的 dmg、Linux 的 AppImage 或 deb。Cocos Creator 也支持这些平台的构建。如果你有跨平台需求,可以在electron-builder的配置里加上mac和linux的目标,然后分别构建。但注意,macOS 的打包需要 macOS 环境,Linux 的打包可以在 Windows 上用 Docker 做,但配置起来比较麻烦。
我个人在实际操作中的体会是,Cocos Creator 构建 Windows exe 和安装包这件事,难点不在技术本身,而在于环境配置和细节处理。只要把环境搞对,把每一步的“为什么”搞清楚,剩下的就是耐心调试。踩过的坑越多,后面出包就越顺。最后再分享一个小技巧:每次构建前,先手动删掉build和dist目录,避免旧文件干扰。这个习惯能帮你省掉很多莫名其妙的错误。