🎯 目标
将标准的 React/Vite 生产构建转化为一个独立的、高度定制的原生 Windows .exe 安装程序。该封装程序会绕过标准的操作系统窗口边框,呈现一个确定性的、电影风格的 5 步安装向导界面。
🛠️ 核心工程模块
1. 生命周期拦截与窗口样式 (electron.js)
初始化一个硬编码、固定布局的窗口($760 \times 480\text{px}$),并应用以下严格的原生属性:
frame: false(禁用所有原生 OS 窗口边界/边框)resizable: false(锁定窗口尺寸)transparent: true(启用透明背景以支持自定义的 Web 样式)
通过 preload.js 暴露一个隔离、安全的异步 IPC(进程间通信)架构。这允许数据在后端运行时与 React 渲染层之间干净地传递,而不会触发沙箱访问安全崩溃。
2. 系统资产部署(Node.js 后台层)
- 目录映射: 动态解析工作空间字符串路径,使用
fs-extra安全地构建目标文件夹。 - 快捷方式注入: 触发一个后台子进程,执行 Windows PowerShell 命令,直接在用户的桌面上构建原生
.lnk快捷方式。 - 操作系统应用列表注册表填充: 将必需的软件应用遥测数据直接注入本地机器注册表索引路径:
HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\[AppName]确保正确填充DisplayName、DisplayIcon、安装目录目标以及操作性的卸载字符串钩子,从而将应用干净地绑定到 Windows 的“应用和功能”工具。
🎨 前端架构与状态机(React)
该安装程序界面运行一个确定性的 5 步 React 状态机,并使用 Tailwind CSS 设计了深沉的、极简主义的石板蓝配色方案(#0a0f1d, #111827):
- 欢迎引导阶段: 极简排版标题,显示软件版本和配置标志。
- 自定义主题目录浏览器: 一个自定义的文件夹选择对话框模态框,直接在 Web 应用的 DOM 上下文中运行(绕过了不匹配的标准 Windows 原生文件资源管理器)。
- 工作空间切换: 有状态复选框组件(默认开启),控制桌面快捷方式的创建和部署。
- 电影级进度过渡阶段: 全出血、无边距布局,渲染流畅的 CSS 微交互和动画,同步到与文件系统复制执行相匹配的精确 3.5 秒线性进度动画。
- 完成选择: 双分支退出屏幕,提供标准退出触发器或通过“启动应用程序”立即执行系统操作。
🖼️ 应用图标分辨率协议
安装程序需要高保真图形素材(icon.ico 和透明的 logo.png)。使用以下回退序列解决缺失的视觉组件:
- 协议 A:用户提供的品牌素材(高级别): 如果通过向导配置屏幕提供了自定义素材,则捕获文件对象、验证尺寸、将其流式传输到 UI 层,并将
.ico变体直接编译到最终的可执行文件头元数据中。 - 协议 B:AI 驱动的上下文回退(零知识级别): 如果未提供品牌素材,则解析应用元数据(名称、描述、行业垂直领域)。执行向量或仓库查找,以提取一个干净、几何化、极简主义的开源图标。 防护栏: 绝对禁止混乱的、装饰性的、或字面上的剪贴画设计。只有抽象的高端矢量结构是有效的。
⚠️ 约束与防护栏
- 相对资源寻址: 确保构建配置中的所有输出资源都使用相对路径(
./static/...)。绝对的 Web 解析引用在打包文件系统内部会失效,导致空白白屏运行时错误。 - 安全隔离: 始终保持
nodeIntegration: false和contextIsolation: true处于激活状态。所有后台平台操作都必须安全地通过contextBridge层进行转换。
📝 示例
示例:将 Manifest 目标注入 package.json
"build": {
"appId": "com.whyskai.custominstaller",
"productName": "WhyskAI-CustomInstaller-Maker",
"win": {
"target": ["nsis"],
"icon": "assets/icon.ico"
},
"nsis": {
"oneClick": false,
"allowToChangeInstallationDirectory": true,
"installerIcon": "assets/icon.ico",
"uninstallerIcon": "assets/icon.ico",
"createDesktopShortcut": true,
"runAfterFinish": true
}
}